review-code - SKILL.md Agent Skill

name: review-code description: 변경된 코드를 합리적 동료 태세로 검토하여 구체적 탐지 시그널에 매치되는 결함 의문점을 생성합니다. user-invocable: true

Review — 합리적 동료 의문점 생성기

리뷰 에이전트는 구현 에이전트를 합리적 동료로 보고, 구체적 탐지 시그널이 매치될 때만 "이 구간이 실제 문제를 일으키는가?"라는 의문을 생성한다. 스타일·취향 지적이 아니라 PR에서 더 물을 것이 남지 않게 만드는 결함 질문기다.

실행 모드

/review-code는 단일 서브에이전트가 14개 카테고리를 전부 순회한다. personas/*.md 5개 파일이 카테고리 인덱스이고, 충돌 시 .agents/rules/*.md가 SSOT다.

운영 모델

요소	규칙
하네스 SSOT	persona는 인덱스, `.agents/rules/*.md` 본문이 최종 판단 근거
의문점	"이 구간이 실제 문제를 일으키는가?" 형태만 허용. 개방형 "왜?" 금지
해소	코드 수정 수용 또는 규칙·선례·스코프·도메인 근거로 반박 인정
미해소	수용/반박 인정 없음. Critical이면 루프 종료 차단
Warning	실제 운영 해 가능성이 구체적으로 관찰될 때만 생성. Info 생성 금지

rules/에 신규 금지·안티패턴·시그널이 추가되면 persona 인덱스가 stale해도 서브에이전트는 rules/ 본문을 직접 읽어 적용한다. persona 인덱스는 토큰 절약용이므로 같은 PR 또는 즉시 후속 PR에서 동기화한다.

실행 흐름

git diff (또는 git diff --cached)로 변경 사항을 확인한다.
단일 리뷰 서브에이전트 1개를 opus로 디스패치한다. 디스패치 시 아래를 전달한다:
- personas/architecture.md, personas/type.md, personas/naming.md, personas/simplicity.md, personas/test-coverage.md 5개 파일 경로 — 서브에이전트가 모두 읽어 14 카테고리 체크리스트로 사용한다.
- diff 전체.
- 이슈 맥락(목표·수용 기준·제약 사항).
서브에이전트는 14 카테고리를 순회하며 Critical / Warning으로 분류된 의문점 리스트를 반환한다. 탐지 시그널에 매치되지 않은 카테고리는 "통과"로 명시한다. Info 섹션은 생성하지 않는다.
구현 에이전트의 응답(수정 또는 반박)을 받아 재검증한다. 재검증은 동일 단일 서브에이전트를 갱신된 diff에 대해 다시 디스패치하여 수행한다.
루프 종료 조건: 재디스패치된 서브에이전트가 Critical을 0개 생성하면 수렴. Warning은 반박 또는 후속 티켓 위임 허용 (개수 무관). Critical 미해소가 남은 상태로 루프를 종료하지 않는다.
Iteration 예산: /process-ticket의 Phase 4 셸이 최대 2 iteration을 강제한다 (Iter 1 = 초기 리뷰 + 응답, Iter 2 = 재검증). Iter 2에서 수렴하지 못하면 escalation 경로(Default = 사용자 질문, --overnight = PR body 기록)로 전환한다.
모순 에스컬레이션 (무한 루프 방지): 새 iteration이 직전 iteration에서 해소된 결정을 뒤집는 의문점을 생성하면 자동 루프를 중단하고 사용자에게 사용자 질의로 확정 방향을 요청한다.

Critical만 "신규 생성 0" 강제: Warning은 주관 재발로 수렴을 막으므로 개수 무시, Critical(동작·타입·레이어 위반)만 강제 차단. Warning 처리 경로 = 수용 / 반박 / /plan-issues 후속 티켓 — 수렴 판정 시 선택 경로를 iteration 로그에 명시.

순회 규칙: 탐지 시그널 미매치 카테고리도 "통과"로 명시. 체크 누락과 의문점 없음을 구분.

심각도 정의 (의문점 weight)

심각도	성격	해소 요건
Critical	아키텍처/레이어/트랜잭션 무결성/테스트 게이트/스펙 오류	해소 필수 — 수정 또는 근거가 명백한 반박(규칙 인용 + 코드 선례). 어느 쪽도 못 하면 루프 종료 불가
Warning	타입 규율, YAGNI 역설, 네이밍, defensive 과다, 코드 스멜, 영속/API 규율	실제 운영 해 가능성이 구체적으로 관찰될 때만 보고. 해소 또는 반박 근거 필요 — 규칙 인용·코드 선례·스코프 근거·도메인 근거 중 하나 이상 제시. 단순 "그냥 그렇게 했다"는 반박으로 인정되지 않음

Info 심각도 제거. 가독성·스타일은 사람 리뷰어에 위임 (iteration 순환 주원인).

의문점 해소 프로토콜

각 의문점에 대해 구현 에이전트는 다음 중 하나를 수행한다.

(1) 수용 (Accept)

코드를 수정하여 의문의 원인을 제거한다.
수정 요약 1줄과 함께 해소를 선언한다.
리뷰 에이전트는 수정된 diff가 실제로 의문을 해소했는지 재검증한다. 새 의문이 생기면 다음 iteration으로 피드한다.

(2) 반박 (Rebut)

구현 에이전트가 코드를 유지하려면 아래 중 하나 이상의 근거를 제시한다.

#	근거 유형	설명
1	규칙 인용	`.agents/rules/<file>.md`의 구체적 규칙을 인용하며, 해당 규칙이 현 상황에 적용됨을 논증
2	코드베이스 선례	같은 패턴이 코드베이스에 이미 있음을 `파일:라인`으로 증명
3	스코프 근거	현 티켓 스코프를 벗어남을 증명하고, 후속 티켓 생성(`/plan-issues`)을 약속
4	도메인 근거	도메인 사전·스펙 문서의 해당 판단 근거를 인용

리뷰 에이전트는 반박을 재검증하여 설득력 있음 → 해소, 설득력 없음 → 미해소로 분류한다. 단순 "그렇게 했다" / "필요 없어 보인다"는 설득력 없음으로 기각된다.

(3) 미해소 (Unresolved)

수용도 반박도 없거나, 반박이 기각된 상태.
루프 종료 조건을 막는다. 구현 에이전트는 다른 반박을 시도하거나 수용으로 전환해야 한다.

의문점 카테고리 (14개)

각 카테고리의 상세(의문점 프롬프트, 탐지 시그널)는 persona 파일이 인덱싱하고, 최종 판단 근거는 .agents/rules/*.md가 SSOT다. 리뷰 서브에이전트는 5개 파일을 모두 로드하여 14 카테고리 전체를 순회한다.

#	카테고리	심각도	상세 SSOT
1	아키텍처 엄수 (레이어·의존 방향)	Critical	`personas/architecture.md`
2	타입 규율	Warning	`personas/type.md`
3	YAGNI (You Aren't Gonna Need It) 역설	Warning	`personas/simplicity.md`
4	도메인 제네릭성 (Aggregate·Port 경계)	Critical	`personas/architecture.md`
5	네이밍 엄수	Warning	`personas/naming.md`
6	테스트 게이트 (커버리지·신규 분기)	Critical	`personas/test-coverage.md`
7	가독성 & 간소화	Warning	`personas/simplicity.md`
8	API/REST 컨벤션	Warning	`personas/test-coverage.md`
9	영속성/Repository 규율	Warning	`personas/architecture.md`
10	트랜잭션 무결성 (단일 Aggregate 변경)	Critical	`personas/architecture.md`
11	코드 스멜 / 패턴 이질성	Warning	`personas/simplicity.md`
12	Defensive / Helper 과다	Warning	`personas/simplicity.md`
13	Infra / 운영 일관성	Warning	`personas/test-coverage.md`
14	스펙 검증 / 후속 티켓	Critical	`personas/architecture.md`

카테고리 7·12는 Warning 필터링 원칙(실제 운영 해 가능성이 구체적으로 관찰될 때만 보고)을 적용하므로 스타일·가독성 수준의 지적은 생성되지 않는다.

보고 템플릿

리뷰 에이전트는 14개 카테고리 상태를 모두 보고한다. 탐지 시그널 미매치도 "통과"로 명시하고 Info 섹션은 만들지 않는다.

## Review 결과 (Iteration N)

### 카테고리별 상태
| # | 카테고리 | 상태(통과/해소됨/미해소) | 의문점 수 |

### Critical — 해소 필수 (N건)
- **[#카테고리 · 파일:라인]** 의문점
  - 탐지 시그널:
  - 관련 규칙: `rules/<file>.md`
  - 상태: `미해소` / `해소됨 (수용)` / `해소됨 (반박 인정)`

### Warning — 해소/반박 필요 (N건)
- Critical과 동일 포맷

### 수렴 판정
- 미해소 Critical: N
- 루프 종료 가능 여부: 가능/불가능
- 다음 iteration 전달 항목: 미해소 의문점 목록

규칙

모든 14개 카테고리를 단일 서브에이전트가 순회한다. 병렬 fan-out 금지. 탐지 시그널에 매치되지 않은 카테고리도 "통과"로 보고하여 누락과 구분한다.
카테고리 체크리스트는 persona 파일이 인덱싱하고 rules가 최종 SSOT다. 리뷰 서브에이전트는 5개 파일을 모두 로드한다. SKILL.md는 디스패처 역할이므로 본문 중복을 피한다.
규칙 본문을 복제하지 않는다. 의문점 프롬프트가 근거로 삼는 규칙은 rules/<file>.md를 직접 읽어 적용한다 (SSOT).
체크리스트는 "구체적 시그널이 매치될 때 의문을 꺼내는 장치"지 "룰 통과 여부 체크"가 아니다. 항목 추가/수정 시 이 성격을 유지한다.
Warning은 실제 운영 해 가능성이 구체적으로 관찰될 때만 보고한다. 카테고리가 Warning이라는 이유만으로 지적을 생성하지 않는다. Info 심각도는 생성하지 않는다.
미해소 Critical이 남은 상태로 루프를 종료하지 않는다. Warning은 반박 또는 후속 티켓 위임으로 해소 가능.
수정은 구현 에이전트가 수행한다. 리뷰 에이전트는 의문점 생성과 응답 재검증만 담당한다 (역할 분리).
수정 후 /check를 실행하여 회귀를 확인한다.