Pre-Commit Review

커밋/푸시 전 변경사항을 분석하여 코드 품질, 사이드이펙트, 보안, 성능 문제를 검출하는 코드 리뷰 스킬.

실행 워크플로우

Step 1: 변경사항 수집

1. git diff (unstaged) + git diff --cached (staged) 로 전체 변경사항 수집
2. git diff --name-only + git diff --cached --name-only 로 변경된 파일 목록 수집
3. 변경된 파일 각각의 전체 내용을 Read 도구로 읽기 (diff만으로는 맥락 부족)

Step 2: 영향 범위 분석

변경된 파일이 속한 레이어와 해당 파일을 참조하는 다른 파일을 탐색:

1. 변경된 Model 파일의 함수를 호출하는 Service/Lib 파일을 Grep으로 검색
2. 변경된 Lib 파일을 require하는 Service/Controller 파일을 Grep으로 검색
3. 변경된 Service 파일을 require하는 Controller 파일을 Grep으로 검색
4. 변경된 Controller 라우트가 있다면 API 엔드포인트 영향 정리

이 탐색 결과를 바탕으로 사이드이펙트 가능성을 판단한다.

Step 3: 체크리스트 기반 리뷰

review-checklist.md를 읽고 다음 5개 영역을 검증:

1. 코드 품질 & 버그 - 컨벤션 준수, 레이어 규칙, 에러 처리, 잠재 버그
2. 사이드이펙트 & 영향도 - 레이어 간 영향, 캐시, DB, API 호환성
3. 보안 - 인젝션, XSS, 인증/인가, 민감정보
4. 성능 - N+1 쿼리, 캐시, 커넥션, 외부 API
5. 프로젝트 특수 - 이 프로젝트에서만 틀리는 것 (체크리스트 5절에 프로젝트별로 채운다)

Step 3.5: 발견별 독립 판정 (review-judge)

Step 3에서 발견이 1건 이상 나오면, 확정 전에 발견별로 독립 판정을 거친다. 리뷰어(이 컨텍스트)는 방금 코드를 작성/분석한 당사자라 자기 확신 편향이 있다 — 같은 코드를 깨끗한 컨텍스트의 독립된 눈이 다시 봐야 그럴듯하지만 틀린 지적과 진짜 결함이 갈린다.

실행 규칙:

1. 발견 1건당 review-judge 에이전트(Agent 도구, subagent_type: "review-judge") 1개를 스폰한다. 발견이 여러 건이면 단일 메시지에서 병렬 스폰한다.
2. 전달 내용: 지적 요지, 대상 파일:라인, 리뷰어가 본 근거. (diff 전체가 아니라 발견 단위로 좁혀 전달)
3. 규모 절제: 발견이 5건을 넘으면 심각도 상위 5건만 판정하고, 나머지는 판정 없이 "미판정" 표기로 보고한다. 사용자가 "철저히/꼼꼼히 리뷰"를 요청한 경우에만 전 건 판정 + 건당 판정자 3명(2표 다수결)으로 확장한다.
4. 판정 반영:
   • VALID → 확정 발견으로 보고
   • INVALID → 본문에서 제외하되, "기각된 발견" 섹션에 기각 사유와 함께 남긴다 (침묵 삭제 금지 — 사용자가 판정 자체를 검증할 수 있어야 한다)
   • DEBATABLE → 발견과 함께 트레이드오프를 병기하고 판단을 사용자에게 넘긴다
5. 발견이 0건이면 이 단계를 건너뛴다.
6. 폴백: subagent_type: "review-judge"가 없는 세션이면(에이전트 정의는 세션 시작 시에만 로드된다) general-purpose 에이전트를 스폰하되, .claude/agents/review-judge.md 본문을 읽어 지침으로 프롬프트에 포함시켜 동일한 판정 프로토콜을 따르게 한다. 에이전트 스폰 자체가 불가능한 환경이면 판정 생략 사실을 결과에 명시한다.

Step 4: 리뷰 결과 출력

아래 형식으로 결과를 출력한다. 문제가 없는 섹션은 "이상 없음"으로 간략히 표시.

## Pre-Commit Review 결과

### 변경 요약
- 변경 파일: N개 (파일 목록)
- 변경 레이어: Controller / Service / Lib / Model 중 해당 항목

### 1. 코드 품질 & 버그
(발견 사항 또는 "이상 없음")

### 2. 사이드이펙트 & 영향도
- **영향받는 파일**: (Grep 결과 기반 목록)
- **캐시 영향**: (해당 시)
- **DB 영향**: (해당 시)
- **API 호환성**: (해당 시)

### 3. 보안
(발견 사항 또는 "이상 없음")

### 4. 성능
(발견 사항 또는 "이상 없음")

### 5. 프로젝트 특수 검증
(체크리스트 5절 항목 중 해당 시에만 표시)

### 판정 결과 (Step 3.5 수행 시)
- 확정 발견 N건 / 논쟁적(트레이드오프) N건 / 기각 N건
- **기각된 발견**: (지적 요지 + 기각 사유 — 판정을 검증할 수 있도록)

### 최종 판정
- PASS: 커밋해도 좋습니다
- WARN: 커밋 가능하지만 아래 사항을 확인하세요 (경고 목록)
- BLOCK: 아래 문제를 먼저 수정해야 합니다 (차단 사유)

자동 트리거 규칙

사용자가 다음과 같은 요청을 할 때 리뷰를 먼저 제안:

• "커밋해줘", "commit", "푸시해줘", "push"
• "변경사항 확인해줘", "리뷰해줘"

제안 방식: "변경사항이 있습니다. 커밋 전에 리뷰를 진행할까요?" 로 질의 후, 사용자가 수락하면 리뷰 워크플로우 실행.

주의사항

• diff 크기가 매우 클 경우 (20개 파일 이상) 핵심 변경 파일을 우선 분석하고 나머지는 요약
• 테스트 파일(test/)의 변경은 별도로 분리하여 간략히 확인
• config 파일 변경은 환경별 일관성과 민감정보 노출 여부만 확인
• 리뷰 결과에서 false positive를 줄이기 위해 파일 전체 맥락을 반드시 읽은 후 판단