코드 리뷰 스킬
리뷰 원칙에서 파생된 모든 질문을 생성하고 답변하여 PR을 리뷰합니다. 구체적인 PR 코멘트와 추론 근거 아티팩트에 대한 참조가 포함된 최종 문서를 생성합니다.
작동 방식
코드 리뷰는 심문입니다. 질문을 생성하고, 모든 질문에 답변하며, 불명확하거나 우려되는 사항을 표면화합니다.
이 스킬이 생성하는 것:
- 리뷰 원칙에서 도출된 질문
- 모든 질문에 대한 답변(또는 명시적인 "작성자 확인 필요")
- 답변에서 도출된 함의
- 카테고리별로 정리된 표면화된 우려 사항
이 스킬이 생성하지 않는 것:
- 심각도 등급(치명적/주요/경미)
- 차단 vs 비차단 분류
- 승인 권장 사항
프로세스: 0. 설정 - PR 브랜치를 로컬에 체크아웃
- 정찰 - PR 영역 매핑, 초기 질문 생성(얕을 수 있음)
- 질문 정제 - 지식 격차 해소, 실제 질문 백로그 생성, 유형별 분류
- 질문 답변 - 각 질문을 적절한 핸들러로 라우팅, Q&A 문서 생성
- 종합 사전 평가 - Q&A를 사용하여 접근 방식 평가(5단계와 병렬)
- 커밋별 리뷰 - Q&A를 사용하여 각 커밋 리뷰(병렬) 5.5. 함의 필터링 - 이진 표면화 결정 + 분류
- 종합 사후 평가 - 재평가, 요구 사항 충족 확인
- 종합 - 카테고리별로 정리된 우려 사항으로 결합
질문 유형 및 핸들러:
- FACT →
fact-find스킬(인용된 답변) - RESEARCH →
deep-research스킬(교육 문서) - DESIGN → 설계 평가(대안 제안, 원칙에 따라 평가)
- CORRECTNESS → 정확성 분석(코드 추적, 동작 확인)
- INTENT → 작성자 확인 필요로 표시(스스로 답변 불가)
핵심 통찰: 모든 질문에는 명시적이고 문서화된 답변(또는 명시적인 "작성자 확인 필요")이 있습니다. 이는 검증 가능한 아티팩트를 생성합니다.
입력
- PR 참조(URL, 번호 또는 브랜치)
- 선택 사항: 사용자가 식별한 중요 이슈 또는 문서
설정
시작하기 전에 오케스트레이터가 PR을 체크아웃합니다:
# 대상 리포지토리 디렉토리에서
github pr checkout <PR-번호>
전제 조건:
- 작업 디렉토리는 PR이 포함된 리포지토리여야 함
- 커밋되지 않은 변경 사항이 없어야 함(초기에 실패)
- GitHub CLI 인증 완료
체크아웃 후, 모든 서브 에이전트는 gh CLI를 사용하는 대신 로컬 파일 시스템에서 코드를 읽습니다.
워크스페이스
모든 아티팩트를 위해 planning/<PR-슬러그>/를 생성합니다. 이 아티팩트를 커밋하지 마십시오. 이는 작업 문서이며, 전달물이 아닙니다.
planning/<PR-슬러그>/
├── 00-scout.md # 초기 영역 맵
├── 01-questions.md # 정제되고 분류된 질문 백로그
├── 02-answers.md # 통합 Q&A 문서
├── answers/ # 개별 답변 아티팩트
│ ├── fact-Q1.md
│ ├── design-Q2.md
│ └── ...
├── 03-commit-NN.md # 커밋별 리뷰
├── 04-holistic-pre.md
├── filtered-implications.md # 표면화할 분류된 함의
├── 05-holistic-post.md
└── REVIEW.md # 최종 출력
서브 에이전트 프로토콜
전달할 파일: PRINCIPLES.md, 에이전트 명령 파일, 이전 단계의 아티팩트
전달할 데이터: workspace 경로, 단계별 데이터
응답:
OUTPUT: <파일명>
STATUS: ok | problems
NOTES: <문제가 있는 경우>
STATUS: ok를 신뢰합니다. problems인 경우 노트를 읽고 결정합니다.
리포지토리 접근
리뷰가 시작되기 전에 PR이 로컬에 체크아웃됩니다. 서브 에이전트는 다음을 전달받습니다:
repo_path: PR이 체크아웃된 리포지토리 경로base_ref: 기본 브랜치(예:main)head_ref: PR 브랜치(체크아웃됨)
서브 에이전트는 repo_path에서 직접 파일을 읽습니다. diff를 위해 git diff {base_ref}...HEAD를 사용합니다.
단계
0. 설정
분석 전에 PR을 로컬에 체크아웃합니다:
github pr checkout <PR-번호>
diff 명령을 위해 PR 메타데이터에서 base_ref를 캡처합니다.
1. 정찰
에이전트: agents/01-scout.md
파일: PRINCIPLES.md, 에이전트 파일
데이터: workspace, repo_path, base_ref, pr_number, 사용자 컨텍스트
출력: 00-scout.md
2. 질문 정제
에이전트: agents/02-refine-questions.md
파일: PRINCIPLES.md, 에이전트 파일, 00-scout.md
데이터: workspace, repo_path, base_ref, 연결된 이슈/문서
출력: 01-questions.md
이 단계는 fact-find를 사용하여 지식 격차를 해소하고 분류된 질문 백로그를 생성합니다.
3. 질문 답변
01-questions.md의 각 질문에 대해 적절한 답변 에이전트를 생성합니다:
| 유형 | 에이전트 | 출력 |
|---|---|---|
| FACT | agents/03-answer-fact.md | answers/fact-{id}.md |
| RESEARCH | agents/04-answer-research.md | answers/research-{id}.md |
| DESIGN | agents/05-answer-design.md | answers/design-{id}.md |
| CORRECTNESS | agents/06-answer-correctness.md | answers/correctness-{id}.md |
| INTENT | (건너뜀—작성자 확인 필요로 표시) |
가능한 경우 답변 에이전트를 병렬로 실행합니다.
모든 완료 후 02-answers.md로 통합합니다:
# 답변된 질문
| ID | 유형 | 질문 | 답변 요약 | 세부 정보 |
|----|------|----------|----------------|--------|
| Q1 | FACT | ... | ... | [answers/fact-Q1.md] |
## 작성자 확인 필요
| ID | 질문 | 답변 불가 이유 |
4. 종합 사전 평가
에이전트: agents/07-holistic-pre.md
파일: PRINCIPLES.md, 에이전트 파일, 01-questions.md, 02-answers.md
데이터: workspace, PR 설명, 커밋 메시지
출력: 04-holistic-pre.md
5단계와 병렬로 실행할 수 있습니다.
5. 커밋별 리뷰
에이전트: agents/08-commit-review.md (커밋당 하나, 병렬)
파일: PRINCIPLES.md, 에이전트 파일, 01-questions.md, 02-answers.md
데이터: workspace, repo_path, base_ref, commit_sha, commit_message, commit_number, total_commits, all_commit_messages
출력: 03-commit-NN.md
for each commit in PR:
spawn commit_reviewer(
commit_diff=commit.diff,
commit_number=N,
...
) → 03-commit-{N}.md
# 각 커밋에 대해 하나의 에이전트 - 배치하지 마십시오
5.5. 함의 필터링
에이전트: agents/085-filter-implications.md
파일: PRINCIPLES.md, 에이전트 파일, 모든 03-commit-*.md
데이터: workspace
출력: filtered-implications.md
에이전트가 커밋 리뷰 파일에서 직접 함의와 작성자 질문을 파싱합니다.
이진 표면화 결정(표면화 또는 하지 않음) 및 분류:
- correctness - 논리 오류, 버그, 잘못된 동작
- assumption - 명시되지 않았지만 유효하지 않을 수 있는 가정
- type-system - 타입 안전성 문제, 누락된 제약 조건
- intent - 명확화가 필요한 작성자 의도에 대한 질문
spawn implication_filter(workspace=workspace) → filtered-implications.md
# 에이전트가 03-commit-*.md 파일에서 함의를 추출합니다
6. 종합 사후 평가
에이전트: agents/09-holistic-post.md
파일: PRINCIPLES.md, 에이전트 파일, 01-questions.md, 02-answers.md, 04-holistic-pre.md, 모든 03-commit-*.md, filtered-implications.md
데이터: workspace
출력: 05-holistic-post.md
7. 종합
에이전트: agents/10-synthesize.md
파일: PRINCIPLES.md, 에이전트 파일, 모든 아티팩트
데이터: workspace
출력: REVIEW.md
표면화된 우려 사항을 심각도가 아닌 카테고리(correctness, assumption, type-system, intent)별로 정리합니다.
8. 전달
REVIEW.md를 사용자에게 제시합니다.
⚠️ 로컬 전용: 이 스킬은 로컬 아티팩트만 생성합니다. 초기 gh pr checkout 이후 GitHub에 코멘트를 게시하거나 GitHub과 상호 작용하지 마십시오. 리뷰 출력은 사용자가 수동으로 작업할 수 있도록 제공됩니다.
토큰 보존
당신은 오케스트레이션만 수행하고, 서브 에이전트가 분석을 수행합니다. 상태 응답을 신뢰합니다.
다음 경우를 제외하고 중간 아티팩트를 읽지 마십시오:
STATUS: problems→ 노트 읽기- 사용자가 질문
- 실패 디버깅
항상 읽을 것: 상태 응답, REVIEW.md 최종 출력.
스킬 파일
skills/review-code/
├── SKILL.md
├── PRINCIPLES.md
└── agents/
├── 01-scout.md
├── 02-refine-questions.md
├── 03-answer-fact.md
├── 04-answer-research.md
├── 05-answer-design.md
├── 06-answer-correctness.md
├── 07-holistic-pre.md
├── 08-commit-review.md
├── 085-filter-implications.md
├── 09-holistic-post.md
└── 10-synthesize.md