중단. 모든 엔드포인트를 호출하기 전에 이 SKILL.MD를 전체적으로 읽으십시오.
평가 (Assess)
프로젝트 상태를 객관적으로 재평가합니다. 대화형 안내(인간 참여형)와 프로그램 분석(자동화된 파이프라인)을 제공합니다. 문서 정리 및 문서-코드 정렬 분석에 특화되어 있습니다.
CLI 사용법
# 파이프라인용 구조화된 JSON 평가
.pi/skills/assess/assess.py run . --output assessment.json
# 평가 결과에서 모든 그림 생성
create-figure from-assess --input assessment.json --output-dir ./figures/
평가 흐름 (Assessment Flow)
1. 평가 범위 설정 (Scope the Assessment)
명확한 범위 ("auth 모듈 평가") → 바로 진행. 열린 범위 ("돌아보기") → 질문: 우려 사항? 코드 품질 vs 문서? 알려진 문제 중 건너뛸 것? 문서 정리 ("문서 정리") → 질문: 사용 중단 기능? 누락된 문서? 정렬 상태?
2. 프로젝트 루트 찾기 및 생태계 탐지 (Find Project Root & Detect Ecosystem)
마커 파일(pyproject.toml, package.json, Cargo.toml, go.mod)을 통해 탐지. 생태계별 메타데이터를 읽고, 이후 범용 문서(README.md, CONTEXT.md, AGENTS.md)를 읽습니다.
3. 스킬 매니페스트 불러오기 (Load Skill Manifest, 경로 기반 게이트)
"X를 구축해야 합니다" 같은 권장 사항으로 이어질 수 있는 평가의 경우 .pi/skills-manifest.json을 로드합니다. 상태 확인 및 문서 전용 검토에서는 건너뜁니다.
cat .pi/skills-manifest.json | python3 -c "
import json, sys
data = json.load(sys.stdin)
print(f'Skills: {data[\"skill_count\"]} (generated: {data[\"generated\"]})')
"
매니페스트가 7일 이상 지난 경우 경고. 대안: ls .pi/skills/ | wc -l.
4. 빠른 스캔 → 확인 요청 → 심층 분석 (Quick Scan → Check In → Deep Dive)
- 프로젝트 메타데이터, README, 구조를 위한 glob 읽기
- 초기 관찰 사항 2-3가지 기록, 사용자에게 확인
- 사용자 지침에 따라 심층 분석 — 각 발견 사항: 차단성? 알려짐? 수정 복잡도?
5. 협업 보고서 (Collaborative Report)
발견 사항을 제시하고 수정할 항목을 질문. 시각화를 위해 /create-figure 제안.
평가 카테고리 (Assessment Categories)
1. 문서-코드 정렬 (Doc-Code Alignment)
- README 주장과 실제 구현 비교
- 상호 참조 검증 (내부 링크, 코드 예제)
- 플레이스홀더 마커 및 오래된 정보
- 사용 중단: 제거된 기능에 대한 문서
2. 이상적 vs 구현됨 (Aspirational vs Implemented)
- 스텁 (
pass,raise NotImplementedError), 플레이스홀더 노트 - 코드 구조에는 있지만 로직이 없는 기능, 사용되지 않는 종속성
3. 취약 코드 (Brittle Code)
- 하드코딩된 값, 누락된 오류 처리, 취약한 정규식/파싱
4. 작동하지 않는 코드 (Non-Working Code)
- 데드 코드 경로, 조용한 예외 삼키기, 깨진 통합
5. 과잉 엔지니어링된 코드 (Over-Engineered Code)
- 단일 구현을 위한 추상화, 가상의 유연성을 위한 설정
6. 테스트 커버리지 (Test Coverage, 협상 불가)
각 기능/모듈에 대해 테스트 파일, 통과 테스트, 경계 사례를 확인.
이유 없는 pytest.mark.skip, "0 tests collected", assert가 없는 테스트를 플래그.
작업 파일 감사: 각 작업에 특정 테스트/assert를 포함한 완료 정의(Definition of Done)가 있는지 확인. 구현 작업에 완료 정의가 없으면 실행 차단.
7. 잘 작동하는 부분 (Working Well)
견고한 코드를 인정하여 평가의 균형을 맞춥니다.
출력 형식 (Output Format)
# 평가: <프로젝트-이름>
## 요약
<2-3문장: 전반적인 상태, 주요 발견 사항>
## 발견 사항
### 문서-코드 정렬
| 주장 | 실제 | 조치 필요? |
### 발견된 문제
1. **file.py:123** - [문제] — 심각도: H/M/L — 제안된 수정: [간략히]
### 테스트 커버리지
| 특징 | 테스트 상태 | 필요 조치 |
### 잘 작동하는 부분
- [인정할 견고한 코드]
## 권장 다음 단계
1-4개의 우선순위 조치. 어느 것부터 시작할지 질문.
정책 (Policies)
- 기본적으로 읽기 전용 — 명시적 동의 없이 파일 쓰기 금지
- 먼저 출력, 동의 후 쓰기 — 제안된 내용을 보여준 후, 쓰기 제안
- 협업 — 평가는 독백이 아닌 대화
- 실행 전 질문 — 테스트, 빌드, 유료 서비스 전에 허가 받기
- 현명하게 에스컬레이션 — 복잡/중요 이슈는
/review-code제안 - 구체적으로 — 파일 경로와 라인 번호 포함
- 실행 가능하게 — 각 발견 사항이 다음 단계를 제안
- 테스트 커버리지는 협상 불가 — 누락된 테스트를 차단 항목으로 플래그
외부 리소스 (External Research)
필요 시 사용 가능 (유료 서비스는 사전 질문):
/context7— 라이브러리 문서 (무료)/brave-search— 일반 웹 검색 (무료)/perplexity— 심층 연구 (유료)
일반적인 실수 (Common Mistakes)
# 잘못된 예: 모든 평가 결과를 차단 이슈로 간주
# → 에이전트가 12개의 비공개 헬퍼에 자동으로 독스트링 추가. 불필요한 비대화.
# 올바른 예: 발견 사항을 사용자와 검토. 복잡한 이슈는 /review-code로 에스컬레이션.
# 잘못된 예: 주요 변경 후 /assess 건너뛰기
# → README 예제가 이전 함수 시그니처 사용. 사용자 오류 발생.
# 올바른 예: 핵심 API 수정 후 assess --focus "doc-code-alignment" 실행
# 잘못된 예: /assess 실행 후 오래된 결과로 작업
# → 평가가 3일 전. 코드베이스가 그 이후 변경됨.
# 올바른 예: 항상 assess 재실행; 세션 간 결과 캐싱 금지