Review
목표는 되돌림·사고를 늘리지 않으면서 사람 리뷰 시간을 최소로 하는 것이다. 우선순위는 진짜 버그를 잡는 것이 첫째, 리뷰 왕복을 줄이는 것이 둘째다.
한 번의 리뷰로 다 잡을 수는 없다. 레이어마다 잘 잡는 것과 놓치는 것이 다르다.
| 레이어 |
맡는 것 |
| 1. PR 전 자기 검증 |
verification-before-completion(실행 출력), 화면이면 스크린샷 비교, 새 컨텍스트의 evaluator |
| 2. AI 리뷰 |
이 스킬 §2~4 |
| 3. 보안 |
이 스킬 §5 |
| 4. 필수 CI |
프로젝트 전체 검사(AGENTS.md ## 명령)와 브랜치 보호 |
| 5. 위험 등급별 사람 승인 |
이 스킬 §6 |
| 6. 병합 큐·기능 플래그·릴리스 채널 |
프로젝트 운영(이 스킬은 PR의 Risk·How to revert 칸만 확인) |
| 7. 배포 뒤 감시·복구·회고 |
이 스킬 §9의 놓친 사례 |
0. 준비
- 대상: PR 번호면
gh pr diff와 PR 설명, 아니면 기본 브랜치 대비 현재 브랜치(git diff <base>...HEAD), 사용자가 지정한 파일·커밋.
- 의도: PR 설명,
docs/work/*/intent.md·spec.md·plan.md(화면이면 design.md). 의도를 모르면 리뷰가 "이 변경이 문제를 푸는가"를 판단할 수 없으니 한 줄로 묻는다.
- 기준:
AGENTS.md(또는 CLAUDE.md)와 REVIEW.md. REVIEW.md가 없으면 끝에서 references/REVIEW.template.md로 만들자고 제안한다.
- 작성자 쪽 확인: 테스트·빌드·린트 출력이 이번 대화나 CI에 있는지 본다. 없으면 먼저 돌린다(
verification-before-completion). 화면 변경이면 결과 스크린샷도 본다. 빨간 검사 위에서는 리뷰하지 않는다.
- PR 세 칸: PR 설명에 Testing(무엇을 검증했나)·Risk(문제가 생기면 어디까지 영향)·How to revert(어떻게 되돌리나)가 비었으면 채워 달라고 한다(
references/PR.template.md). 되돌리는 방법은 병합 전에 정한다.
- 원장:
.review/<브랜치>.md(없으면 만들고 .gitignore에 .review/를 더한다). 라운드 번호, 마지막으로 본 커밋 SHA, 낸 지적과 그 처리 결과를 적는다. PR이 있으면 PR 코멘트가 원장을 대신한다.
1. 깊이
| 단계 |
언제 |
탐색 에이전트 |
검증 에이전트 |
합계(보안 포함) |
| Quick |
문서·문구·작은 국소 변경 |
1개(렌즈 ①②) |
1개, 1표면 남김 |
2개 |
| Standard(기본) |
보통 제품 변경 |
3개(렌즈 ①②③) |
3개, 2표 이상이면 남김 |
7개 |
| Deep |
놓친 버그 하나가 리뷰 시간보다 비싼 곳(결제·인증·마이그레이션·동시성·공개 API) |
5개(렌즈 ①~⑤) |
3개 + 재현 |
9개 |
멀티 에이전트는 대화보다 토큰을 15배가량 쓴다. 깊이는 변경의 위험에 맞춰 고르고, REVIEW.md가 경로별 깊이를 정해 두었으면 그것을 따른다. 검증 에이전트 수는 지적 개수와 상관없이 고정이다(각자 전체 목록을 판정한다).
2. 탐색 (병렬, 새 컨텍스트)
이 세션(조율자)은 리뷰하지 않고 나눠 주고 모은다. 렌즈마다 서브에이전트 하나를 한 번에 같이 띄운다. 브리프는 references/finder.md를 채워 넘긴다: 목표(렌즈), 출력 형식(지적 행), 도구 지침(읽기·grep·git만, 파일 수정 금지), 경계(이 diff와 그 영향 범위), 예산(파일 읽기 30회 안팎, 찾은 것이 없으면 "없음"). 작성한 세션이 같은 컨텍스트에서 스스로 리뷰하지 않는다.
- 의도: 이 변경이 말한 문제를 실제로 푸는가. 버그 수정이면 증상이 아니라 근본 원인을 고쳤는가.
- 시스템 적합: 호출자·계약·이웃 코드·설정을 깨뜨리는가. diff 밖 사용처까지 grep한다.
- 경계와 실패 경로: 빈 값·큰 입력·동시성·오류 처리·데이터 손실·권한.
- (Deep) 테스트: 테스트가 바뀐 동작을 실제로 검증하는가, 약해지거나 건너뛴 테스트는 없는가.
- (Deep) 자원·성능: 루프 안 I/O, N+1, 무제한 증가, 정리되지 않는 자원.
모든 지적은 file:line, 무엇이 틀렸나, 어떤 입력·상태에서 어떤 잘못된 결과가 나오나를 갖춘다. 이름만 보고 짐작한 지적, 스타일·진단 메시지·정리만의 지적은 내지 않는다. 같은 원인이 여러 곳에 있으면 버그의 종류로 묶고 위치를 모두 적는다(작성자가 한 줄이 아니라 전부 고치게).
3. 병합과 검증 투표
- 병합(조율자): 탐색 결과를 모아 같은 위치·같은 원인은 하나로 합치고
F1, F2… 번호를 붙인다. 원장·PR 코멘트에 이미 있는 지적은 뺀다. 남은 목록을 원장에 적는다(검증자에게는 파일 위치로 넘긴다).
- 투표(별도 에이전트): 검증자를 표 수만큼 한 번에 같이 띄운다. 각자
references/verifier.md로 전체 목록을 독립 판정한다. 탐색자의 추론은 넘기지 않고 지적 문장·위치와 diff만 넘긴다.
- 재현: 싸게 재현할 수 있으면 재현이 판정보다 우선이다. 재현은 격리된 곳에서만 한다(Claude Code는 서브에이전트
isolation: worktree, 아니면 임시 폴더 복사본). 공유 작업 트리는 바꾸지 않는다.
- 집계: 지적별 REAL 표를 세어 기준(Quick 1표, Standard·Deep 2표) 이상만 남긴다. 표가 갈린 지적은 보고에 "판정 갈림"으로 따로 적는다.
4. 정렬과 꼬리표
- Important: 병합 전에 고쳐야 하는 진짜 버그.
- Nit: 고치면 좋은 작은 것. REVIEW.md가 정한 개수(기본 3개)를 넘기지 않는다.
- Pre-existing: diff 밖에서 원래 있던 버그. 작성자 잘못처럼 보이지 않게 따로 표시하고 병합을 막지 않는다.
이미 낸 지적은 다시 내지 않는다(원장·PR 코멘트 확인).
5. 보안 (별도 패스)
보안만 보는 패스를 따로 돌린다. Claude Code는 내장 /security-review, 다른 호스트는 security-reviewer 에이전트(Quick은 인증·입력 처리·비밀 값을 건드릴 때만). 열린 보안 지적과 Important는 병합을 막는다.
6. 위험 등급과 사람 승인
| 등급 |
예 |
필요한 사람 승인 |
| Low |
문서·문구, 내부 전용, 플래그 뒤의 추가 기능 |
자동 리뷰·보안이 깨끗하면 0명 |
| Medium |
보통 제품 변경, 캐시·자동 업데이트·시스템 프롬프트 같은 민감 영역 |
1명 |
| High |
결제·인증·마이그레이션·CI 워크플로·남들이 따라 할 구조 |
2명 |
- 등급은 작성자가 아니라 변경이 정한다. CI 워크플로 파일은 항상 사람 1명 이상이다.
- 에이전트의 승인은 사람의 승인을 대신하지 않는다. 변경을 지시한 사람이 그 결과의 책임자이고, 그 사람이 diff와 검증 결과를 직접 확인했으면 승인 1명으로 친다. 승인 권한은 그 코드를 알고 문제가 나면 대응할 수 있는 사람에게만 준다.
- 처음에는 엄격하게(Medium부터 1명) 시작하고, 놓친 사례·잡음 비율을 보며 푼다.
- 승인은 특정 커밋에 대한 것이다. 승인 뒤 새 커밋이 오면 다시 본다.
7. 보고
첫 줄은 개수다: 발견 N건 — Important a · Nit b · Pre-existing c · 보안 d 또는 고칠 것 없음(있는 그대로 말한다). 이어서 위험 등급과 필요한 승인 수, 그다음 심각도 순 목록(꼬리표, file:line, 문제, 재현 조건, 고칠 방향). 사용자가 원하면 PR에 줄 단위 코멘트로 올린다(gh api .../pulls/<번호>/comments 또는 gh pr review).
모든 지적은 답을 받아야 한다: 고치거나, 이유를 적고 닫는다. 작성자 답을 원장에 고침 / 틀림 / 의도함 / 상관없음으로 적는다.
8. 수렴
- 2라운드부터는 원장의 마지막 SHA 이후 diff만 본다.
- 3라운드를 넘기면 지적을 더 내기 전에 "접근을 다시 생각하자"고 작성자에게 말한다.
- 같은 종류의 지적이 라운드마다 나오면 종류로 묶어 한 번에 고치게 한다.
9. 피드백 루프
- 틀림이 같은 이유로 두 번 나오면 REVIEW.md에 건너뛸 규칙(경로·패턴)을 제안한다.
- 진짜 버그가 같은 종류로 반복되면, 기계적으로 잡을 수 있는 것은 린트·테스트 규칙으로 옮긴다(가장 확실하다). 판단이 필요한 것은
memory 스킬로 기록하고(hits), 자주 나오면 AGENTS.md ## 자주 틀리는 것이나 REVIEW.md로 올린다.
- 병합 뒤 되돌림이나 사고로 이어진 버그는 REVIEW.md "놓친 사례"에 어느 레이어가 잡았어야 했나와 함께 남긴다.
- 잡음 측정: 리뷰가 끝나면 원장의 처리 결과로
틀림 / 전체 비율을 한 줄 보고한다. 높으면 REVIEW.md의 건너뛸 규칙·깊이를 고친다.
- 회귀 점검: 이 스킬이나 REVIEW.md를 바꾸면 "놓친 사례"의 diff(커밋 SHA)에 다시 돌려 여전히 잡는지 본다. 사례가 쌓이면 이것이 리뷰의 평가 세트다.
설명 (선택)
리뷰를 AI가 맡으면 팀원이 남의 코드를 읽으며 배우는 기회가 줄어든다. 사용자가 원하면 바뀐 흐름을 코드 근거(file:line)와 함께 설명하고, 필요하면 요청이 어디로 들어와 어디를 지나는지 작은 다이어그램으로 보여 준다. 그림만 보고 넘기지 않게, 고칠 자리를 코드에서 함께 짚는다.
도입 순서 (작게 시작)
- PR 템플릿에 Testing·Risk·How to revert를 넣는다.
- 모든 PR에 이 리뷰와 보안 패스를 돌린다. CI가 부담이면 로컬에서 먼저 돌리고, 자주 쓰는 검사부터 CI로 옮긴다.
- GitHub 브랜치 보호: 필수 상태 검사, "Require conversation resolution before merging"(미해결 코멘트가 있으면 병합 불가).
- 실제 코멘트를 보며 REVIEW.md를 다듬고, 기계적인 것은 린트·테스트로 옮긴다.
- 사람 승인 등급은 엄격하게 시작해 결과를 보며 푼다.
호스트 차이
서브에이전트를 병렬로 띄울 수 없는 호스트에서는 렌즈를 차례로 돌린다. 검증은 새 세션(claude -p, codex exec)으로 해서 탐색한 컨텍스트와 분리한다.
1---2name: review3description: 병합 전에 diff·브랜치·PR을 리뷰할 때 사용. 렌즈별 탐색 에이전트를 병렬로 돌리고, 별도 검증 에이전트 투표로 거짓 양성을 걸러, 심각도 순으로 근거(file:line)와 함께 보고하고 위험 등급과 필요한 사람 승인 수를 정한다. Triggers - 코드 리뷰, 리뷰해 줘, PR 리뷰, review, 병합 전 점검.4metadata:5 source: https://skillmd.com/skills/jh941213/review6---78# Review910목표는 **되돌림·사고를 늘리지 않으면서 사람 리뷰 시간을 최소로** 하는 것이다. 우선순위는 진짜 버그를 잡는 것이 첫째, 리뷰 왕복을 줄이는 것이 둘째다.1112한 번의 리뷰로 다 잡을 수는 없다. 레이어마다 잘 잡는 것과 놓치는 것이 다르다.1314| 레이어 | 맡는 것 |15|---|---|16| 1. PR 전 자기 검증 | `verification-before-completion`(실행 출력), 화면이면 스크린샷 비교, 새 컨텍스트의 `evaluator` |17| 2. AI 리뷰 | 이 스킬 §2~4 |18| 3. 보안 | 이 스킬 §5 |19| 4. 필수 CI | 프로젝트 전체 검사(AGENTS.md `## 명령`)와 브랜치 보호 |20| 5. 위험 등급별 사람 승인 | 이 스킬 §6 |21| 6. 병합 큐·기능 플래그·릴리스 채널 | 프로젝트 운영(이 스킬은 PR의 Risk·How to revert 칸만 확인) |22| 7. 배포 뒤 감시·복구·회고 | 이 스킬 §9의 놓친 사례 |2324## 0. 준비2526- **대상:** PR 번호면 `gh pr diff`와 PR 설명, 아니면 기본 브랜치 대비 현재 브랜치(`git diff <base>...HEAD`), 사용자가 지정한 파일·커밋.27- **의도:** PR 설명, `docs/work/*/intent.md`·`spec.md`·`plan.md`(화면이면 `design.md`). 의도를 모르면 리뷰가 "이 변경이 문제를 푸는가"를 판단할 수 없으니 한 줄로 묻는다.28- **기준:** `AGENTS.md`(또는 CLAUDE.md)와 `REVIEW.md`. REVIEW.md가 없으면 끝에서 `references/REVIEW.template.md`로 만들자고 제안한다.29- **작성자 쪽 확인:** 테스트·빌드·린트 출력이 이번 대화나 CI에 있는지 본다. 없으면 먼저 돌린다(`verification-before-completion`). 화면 변경이면 결과 스크린샷도 본다. 빨간 검사 위에서는 리뷰하지 않는다.30- **PR 세 칸:** PR 설명에 Testing(무엇을 검증했나)·Risk(문제가 생기면 어디까지 영향)·How to revert(어떻게 되돌리나)가 비었으면 채워 달라고 한다(`references/PR.template.md`). 되돌리는 방법은 병합 전에 정한다.31- **원장:** `.review/<브랜치>.md`(없으면 만들고 `.gitignore`에 `.review/`를 더한다). 라운드 번호, 마지막으로 본 커밋 SHA, 낸 지적과 그 처리 결과를 적는다. PR이 있으면 PR 코멘트가 원장을 대신한다.3233## 1. 깊이3435| 단계 | 언제 | 탐색 에이전트 | 검증 에이전트 | 합계(보안 포함) |36|---|---|---|---|---|37| Quick | 문서·문구·작은 국소 변경 | 1개(렌즈 ①②) | 1개, 1표면 남김 | 2개 |38| Standard(기본) | 보통 제품 변경 | 3개(렌즈 ①②③) | 3개, 2표 이상이면 남김 | 7개 |39| Deep | 놓친 버그 하나가 리뷰 시간보다 비싼 곳(결제·인증·마이그레이션·동시성·공개 API) | 5개(렌즈 ①~⑤) | 3개 + 재현 | 9개 |4041멀티 에이전트는 대화보다 토큰을 15배가량 쓴다. 깊이는 변경의 위험에 맞춰 고르고, REVIEW.md가 경로별 깊이를 정해 두었으면 그것을 따른다. 검증 에이전트 수는 지적 개수와 상관없이 고정이다(각자 전체 목록을 판정한다).4243## 2. 탐색 (병렬, 새 컨텍스트)4445이 세션(조율자)은 리뷰하지 않고 나눠 주고 모은다. 렌즈마다 서브에이전트 하나를 **한 번에 같이** 띄운다. 브리프는 `references/finder.md`를 채워 넘긴다: 목표(렌즈), 출력 형식(지적 행), 도구 지침(읽기·grep·git만, 파일 수정 금지), 경계(이 diff와 그 영향 범위), 예산(파일 읽기 30회 안팎, 찾은 것이 없으면 "없음"). 작성한 세션이 같은 컨텍스트에서 스스로 리뷰하지 않는다.46471. **의도:** 이 변경이 말한 문제를 실제로 푸는가. 버그 수정이면 증상이 아니라 근본 원인을 고쳤는가.482. **시스템 적합:** 호출자·계약·이웃 코드·설정을 깨뜨리는가. diff 밖 사용처까지 grep한다.493. **경계와 실패 경로:** 빈 값·큰 입력·동시성·오류 처리·데이터 손실·권한.504. (Deep) **테스트:** 테스트가 바뀐 동작을 실제로 검증하는가, 약해지거나 건너뛴 테스트는 없는가.515. (Deep) **자원·성능:** 루프 안 I/O, N+1, 무제한 증가, 정리되지 않는 자원.5253모든 지적은 `file:line`, 무엇이 틀렸나, 어떤 입력·상태에서 어떤 잘못된 결과가 나오나를 갖춘다. 이름만 보고 짐작한 지적, 스타일·진단 메시지·정리만의 지적은 내지 않는다. 같은 원인이 여러 곳에 있으면 **버그의 종류**로 묶고 위치를 모두 적는다(작성자가 한 줄이 아니라 전부 고치게).5455## 3. 병합과 검증 투표56571. **병합(조율자):** 탐색 결과를 모아 같은 위치·같은 원인은 하나로 합치고 `F1`, `F2`… 번호를 붙인다. 원장·PR 코멘트에 이미 있는 지적은 뺀다. 남은 목록을 원장에 적는다(검증자에게는 파일 위치로 넘긴다).582. **투표(별도 에이전트):** 검증자를 표 수만큼 **한 번에 같이** 띄운다. 각자 `references/verifier.md`로 **전체 목록**을 독립 판정한다. 탐색자의 추론은 넘기지 않고 지적 문장·위치와 diff만 넘긴다.593. **재현:** 싸게 재현할 수 있으면 재현이 판정보다 우선이다. 재현은 격리된 곳에서만 한다(Claude Code는 서브에이전트 `isolation: worktree`, 아니면 임시 폴더 복사본). 공유 작업 트리는 바꾸지 않는다.604. **집계:** 지적별 REAL 표를 세어 기준(Quick 1표, Standard·Deep 2표) 이상만 남긴다. 표가 갈린 지적은 보고에 "판정 갈림"으로 따로 적는다.6162## 4. 정렬과 꼬리표6364- **Important:** 병합 전에 고쳐야 하는 진짜 버그.65- **Nit:** 고치면 좋은 작은 것. REVIEW.md가 정한 개수(기본 3개)를 넘기지 않는다.66- **Pre-existing:** diff 밖에서 원래 있던 버그. 작성자 잘못처럼 보이지 않게 따로 표시하고 병합을 막지 않는다.6768이미 낸 지적은 다시 내지 않는다(원장·PR 코멘트 확인).6970## 5. 보안 (별도 패스)7172보안만 보는 패스를 따로 돌린다. Claude Code는 내장 `/security-review`, 다른 호스트는 `security-reviewer` 에이전트(Quick은 인증·입력 처리·비밀 값을 건드릴 때만). 열린 보안 지적과 Important는 병합을 막는다.7374## 6. 위험 등급과 사람 승인7576| 등급 | 예 | 필요한 사람 승인 |77|---|---|---|78| Low | 문서·문구, 내부 전용, 플래그 뒤의 추가 기능 | 자동 리뷰·보안이 깨끗하면 0명 |79| Medium | 보통 제품 변경, 캐시·자동 업데이트·시스템 프롬프트 같은 민감 영역 | 1명 |80| High | 결제·인증·마이그레이션·CI 워크플로·남들이 따라 할 구조 | 2명 |8182- 등급은 작성자가 아니라 **변경**이 정한다. CI 워크플로 파일은 항상 사람 1명 이상이다.83- **에이전트의 승인은 사람의 승인을 대신하지 않는다.** 변경을 지시한 사람이 그 결과의 책임자이고, 그 사람이 diff와 검증 결과를 직접 확인했으면 승인 1명으로 친다. 승인 권한은 그 코드를 알고 문제가 나면 대응할 수 있는 사람에게만 준다.84- 처음에는 엄격하게(Medium부터 1명) 시작하고, 놓친 사례·잡음 비율을 보며 푼다.85- 승인은 특정 커밋에 대한 것이다. 승인 뒤 새 커밋이 오면 다시 본다.8687## 7. 보고8889첫 줄은 개수다: `발견 N건 — Important a · Nit b · Pre-existing c · 보안 d` 또는 `고칠 것 없음`(있는 그대로 말한다). 이어서 위험 등급과 필요한 승인 수, 그다음 심각도 순 목록(꼬리표, `file:line`, 문제, 재현 조건, 고칠 방향). 사용자가 원하면 PR에 줄 단위 코멘트로 올린다(`gh api .../pulls/<번호>/comments` 또는 `gh pr review`).9091모든 지적은 답을 받아야 한다: 고치거나, 이유를 적고 닫는다. 작성자 답을 원장에 **고침 / 틀림 / 의도함 / 상관없음**으로 적는다.9293## 8. 수렴9495- 2라운드부터는 원장의 마지막 SHA 이후 diff만 본다.96- 3라운드를 넘기면 지적을 더 내기 전에 "접근을 다시 생각하자"고 작성자에게 말한다.97- 같은 종류의 지적이 라운드마다 나오면 종류로 묶어 한 번에 고치게 한다.9899## 9. 피드백 루프100101- **틀림**이 같은 이유로 두 번 나오면 REVIEW.md에 건너뛸 규칙(경로·패턴)을 제안한다.102- 진짜 버그가 같은 종류로 반복되면, 기계적으로 잡을 수 있는 것은 **린트·테스트 규칙**으로 옮긴다(가장 확실하다). 판단이 필요한 것은 `memory` 스킬로 기록하고(hits), 자주 나오면 AGENTS.md `## 자주 틀리는 것`이나 REVIEW.md로 올린다.103- 병합 뒤 되돌림이나 사고로 이어진 버그는 REVIEW.md "놓친 사례"에 **어느 레이어가 잡았어야 했나**와 함께 남긴다.104- **잡음 측정:** 리뷰가 끝나면 원장의 처리 결과로 `틀림 / 전체` 비율을 한 줄 보고한다. 높으면 REVIEW.md의 건너뛸 규칙·깊이를 고친다.105- **회귀 점검:** 이 스킬이나 REVIEW.md를 바꾸면 "놓친 사례"의 diff(커밋 SHA)에 다시 돌려 여전히 잡는지 본다. 사례가 쌓이면 이것이 리뷰의 평가 세트다.106107## 설명 (선택)108109리뷰를 AI가 맡으면 팀원이 남의 코드를 읽으며 배우는 기회가 줄어든다. 사용자가 원하면 바뀐 흐름을 코드 근거(`file:line`)와 함께 설명하고, 필요하면 요청이 어디로 들어와 어디를 지나는지 작은 다이어그램으로 보여 준다. 그림만 보고 넘기지 않게, 고칠 자리를 코드에서 함께 짚는다.110111## 도입 순서 (작게 시작)1121131. PR 템플릿에 Testing·Risk·How to revert를 넣는다.1142. 모든 PR에 이 리뷰와 보안 패스를 돌린다. CI가 부담이면 로컬에서 먼저 돌리고, 자주 쓰는 검사부터 CI로 옮긴다.1153. GitHub 브랜치 보호: 필수 상태 검사, "Require conversation resolution before merging"(미해결 코멘트가 있으면 병합 불가).1164. 실제 코멘트를 보며 REVIEW.md를 다듬고, 기계적인 것은 린트·테스트로 옮긴다.1175. 사람 승인 등급은 엄격하게 시작해 결과를 보며 푼다.118119## 호스트 차이120121서브에이전트를 병렬로 띄울 수 없는 호스트에서는 렌즈를 차례로 돌린다. 검증은 새 세션(`claude -p`, `codex exec`)으로 해서 탐색한 컨텍스트와 분리한다.