review

name	review
description	Independent code & visual review via sub-agents. 2-pass evaluation (Critical→Informational) with bias isolation. Use after /verify passes.

Review

Chain

Before	Current	Next (auto)
/verify pass	/review	/wrap (on PASS)

Principle

• implement/verify를 수행한 세션의 reasoning을 review에 노출하지 않는다
• 서브에이전트에게 diff + PRD(spec) 만 전달하여 독립 평가를 보장한다
• 2-pass 구조: Critical(프로덕션 장애) → Informational(개선 사항) 순서로 분리
• Fix-First: 기계적 수정은 바로 고치고, 판단이 필요한 것만 질문

Flow

/review 호출
│
├── 1. 컨텍스트 수집
│   ├── git diff (변경 파일 + 내용)
│   ├── PRD/spec (clarify 산출물, 있으면)
│   ├── CLAUDE.md (프로젝트 컨벤션)
│   └── 변경 파일 수 확인 → 8개+ 시 스코프 드리프트 경고
│
├── 2. 프로젝트 타입 감지
│   ├── tsx/jsx/vue 변경 + dev server 설정 → frontend = true
│   └── auth/middleware/API route 변경 → security_sensitive = true
│
├── 3. Sub-agent 실행 (해당 조건 시 반드시 병렬 실행)
│   ├─▶ [code-review] ← 항상 실행 (2-pass)
│   └─▶ [visual-review] ← frontend = true일 때 동시 실행 (Agent tool 병렬 호출)
│
├── 4. 결과 종합 → Triage → Verdict
│
└── 5. Fix-First 실행
    ├── AUTO-FIX 항목 → 즉시 수정
    └── ASK 항목 → 사용자에게 질문

Code Review (sub-agent) — 2-Pass 구조

Input

• git diff (staged + unstaged)
• PRD/spec (선택)
• CLAUDE.md
• security_sensitive 플래그

Pass 1: Critical (프로덕션 장애 가능성)

반드시 먼저 실행. 하나라도 발견되면 P0/P1으로 분류.

검사 항목	대상
SQL/데이터 안정성	파라미터화 미사용, 트랜잭션 경계 누락, 마이그레이션 안전성
Race condition	공유 상태 동시 접근, lock 없는 업데이트, 비원자적 읽기-수정-쓰기
신뢰 경계	LLM 출력 미검증 사용, 외부 API 응답 직접 신뢰, 사용자 입력 미새니타이즈
Enum/분기 완전성	switch exhaustiveness, 누락된 에러 케이스, 타입 narrowing 빈틈
인증/인가	미보호 라우트, 권한 우회 가능 경로, 토큰 검증 누락
데이터 유실	에러 시 부분 쓰기, 롤백 미처리, cascade delete 영향 범위

security_sensitive = true일 때 추가 검사:

검사 항목	대상
입력 검증	SQL injection, XSS, command injection
시크릿 관리	하드코딩된 키/토큰, 로그에 민감정보 노출
세션/쿠키	httpOnly, secure, sameSite 설정
CORS	와일드카드 origin, credentials 허용 범위

Pass 2: Informational (개선 사항)

Pass 1 완료 후 실행. 참고용이며 FAIL 사유가 되지 않음.

검사 항목	대상
매직 넘버	의미 불명 상수, 하드코딩된 설정값
조건부 부작용	조건문 내부 상태 변경, 숨겨진 side effect
테스트 갭	비즈니스 규칙 변경인데 테스트 미작성
복잡도	불필요한 추상화, 과잉 설계, 깊은 중첩
성능	O(n²)+ 패턴, N+1 쿼리, 불필요한 할당
컨벤션	CLAUDE.md 규칙 위반, 기존 패턴 불일치

Triage (Gravtile 4단계)

모든 이슈에 심각도를 부여:

등급	기준	행동
P0-CRITICAL	프로덕션 장애 직결	반드시 수정. FAIL 사유
P1-HIGH	버그 가능성 높음	수정 권장. 2건+ 시 FAIL
P2-MEDIUM	개선하면 좋음	선택적
P3-LOW	스타일/참고	무시 가능

Fix-First 분류

각 이슈에 행동 유형 부여:

유형	기준	예시
AUTO-FIX	기계적으로 수정 가능, 판단 불필요	임포트 정렬, 미사용 변수, 타입 단언, lint 위반
ASK	아키텍처/비즈니스 판단 필요	에러 처리 전략, API 계약 변경, 성능-가독성 트레이드오프

Rules

• 문제만 찾는다 (칭찬 금지)
• 각 이슈에 반드시 등급 + 근거(file:line + 이유) 를 명시
• implement 과정의 의도를 추측하지 않는다 — diff와 PRD만으로 판단
• Pass 1에서 P0 발견 시 Pass 2 생략하고 즉시 리포트 가능

Visual Review (sub-agent, 조건부)

실행 조건

• frontend 파일(tsx/jsx/vue/css) 변경됨
• Playwright 설치됨 (npx playwright --version 성공)
• dev server 기동 가능

Flow

1. dev server 기동 (이미 실행 중이면 스킵)
2. 변경된 페이지/컴포넌트 대상 Playwright 스크린샷 촬영
3. 스크린샷 + PRD 디자인 섹션을 visual-review 에이전트에 전달

Scoring (각 1-5)

기준	평가 대상
Layout	깨짐, 오버플로우, 반응형 대응
Consistency	디자인 시스템/컴포넌트 라이브러리 일관성
Accessibility	명암비, 포커스 표시, 시맨틱 구조
Authenticity	AI 기본 출력 느낌 탈피 (아래 RED FLAG 참조)

AI-Design RED FLAGS

다음이 감지되면 Authenticity 감점:

항목	RED FLAG
Color	브랜드/PRD 지정 없이 보라-파랑 기본 팔레트 사용
Decoration	기능적 의미 없는 그라디언트, blur, 애니메이션
Density	시각적 계층 없이 요소가 균일하게 빽빽함
Whitespace	의도적 여백(breathing room) 부재
Originality	SaaS 랜딩페이지 템플릿 패턴 그대로 (3열 카드, hero+features+CTA)
Copy	"Supercharge", "Built for the modern" 등 generic AI 카피

Verdict

PASS 조건

• P0-CRITICAL 0건
• P1-HIGH 2건 미만
• Visual Review 해당 시 전 항목 3점 이상

Output

## Review Result

### Pass 1: Critical Issues
| # | 등급 | 이슈 | 위치 | 행동 |
|---|------|------|------|------|
| 1 | P0 | SQL injection 가능 | src/api.ts:42 | AUTO-FIX |
| 2 | P1 | race condition | src/store.ts:88 | ASK |

### Pass 2: Informational
| # | 등급 | 이슈 | 위치 | 행동 |
|---|------|------|------|------|
| 3 | P2 | 매직 넘버 | src/config.ts:15 | AUTO-FIX |
| 4 | P3 | 깊은 중첩 | src/utils.ts:30 | - |

### Visual Review (해당 시)
| Criterion | Score | Issues |
|-----------|-------|--------|
| Layout | 4 | ... |
| Consistency | 3 | ... |
| Accessibility | 4 | ... |
| Authenticity | 3 | ... |

### Summary
- P0: 0건 / P1: 1건 / P2: 2건 / P3: 1건
- AUTO-FIX: 2건 (즉시 수정)
- ASK: 1건 (아래 질문)

### Verdict: PASS | FAIL (reason)

Rules

• 병렬 실행: frontend 감지 시 code-review와 visual-review를 하나의 메시지에서 Agent tool 2개를 동시 호출한다. 순차 실행 금지.
• Fix-First: PASS/FAIL 판정 후 AUTO-FIX 항목은 즉시 수정. ASK 항목은 사용자에게 질문.
• 스코프 드리프트: 변경 파일 8개+ 시 리뷰 시작 전 경고 출력 ("변경 범위가 넓습니다. 의도된 범위인지 확인하세요.")
• FAIL → fix issues → /verify → /review (사이클)
• PASS + AUTO-FIX 수정 완료 → immediately call /wrap. Do not ask "shall I wrap?"
• visual-review 조건 미충족 시 code-review만으로 판정 (Visual 점수 제외)