deep-review-workflow

Deep Review Workflow

이 스킬은 /deep-review 커맨드에서 로드되어 리뷰 프로세스를 가이드합니다.

참조 문서

• references/review-criteria.md — 5가지 리뷰 관점
• references/codex-integration.md — Codex 교차 검증
• references/contract-schema.md — Sprint Contract 스키마
• references/report-format.md — 리포트 형식

4단계 파이프라인

Stage 1: Collect (변경 수집)

1. 환경 감지 스크립트 실행: bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/detect-environment.sh
2. 결과를 key=value 형식으로 파싱
3. 결과에 따라 diff 수집:
   • change_state=non-git → 사용자에게 리뷰할 파일 목록 요청
   • change_state=initial → 모든 파일 대상 리뷰
   • change_state=clean → git diff {review_base}..HEAD
   • change_state=staged → git diff --cached
   • change_state=unstaged → git diff
   • change_state=mixed → git diff HEAD (staged + unstaged 모두)
   • change_state=untracked-only → git ls-files --others --exclude-standard로 파일 목록 수집
4. 모든 git 상태에서 untracked > 0이면:
   • git ls-files --others --exclude-standard로 추가 파일을 리뷰 대상에 포함 (primary state의 diff와 union)
5. diff에서 제외: 바이너리, vendor/, node_modules/, *.min.js, .generated., *.lock

Stage 2: Contract Check (계약 검증)

--contract 플래그 처리:

• --contract SLICE-{NNN} (슬라이스 지정): .deep-review/contracts/SLICE-{NNN}.yaml만 로드 (status: active 확인)
• --contract (슬라이스 미지정): .deep-review/contracts/ 내 모든 status: active contract 로드
• 플래그 없이 .deep-review/contracts/에 active contract가 있으면: 자동으로 전체 contract 검증
• contract 디렉토리가 없거나 active 파일이 없으면: 이 단계 건너뜀
• status: archived contract는 자동 로드에서 제외. 명시적 SLICE-NNN 지정 시에도 archived이면 경고 표시.
• YAML 파싱 오류 시: 해당 contract 건너뜀 + 경고 "Contract {파일명} 파싱 실패 — 건너뜀"

Stage 3: Deep Review (교차 검증)

환경에 따라 리뷰어 구성이 달라짐:

공통: 유저 고지 + 백그라운드 실행 모든 Case에서 리뷰어 spawn 직전 고지 메시지를 출력하고, 모든 리뷰어를 백그라운드에서 실행한다.

• Case A/B: "Opus 리뷰를 백그라운드에서 실행합니다. 완료되면 결과를 알려드리겠습니다."
• Case C: "3개 리뷰어(Opus, Codex review, Codex adversarial)를 백그라운드에서 실행합니다. 완료되면 결과를 합성하여 알려드리겠습니다." 코드 경로 단일화를 위해 단독 리뷰어(Case A/B)에서도 백그라운드로 실행한다.

Case A: non-git 또는 커밋 0건 → Claude Opus 서브에이전트 단독 리뷰 (run_in_background: true)

Case B: git + 커밋 있음 + Codex 플러그인 미설치 (codex_plugin=false) → Claude Opus 서브에이전트 단독 리뷰 (run_in_background: true) → 세션 내 최초 1회 안내:

• codex_cli=false: Codex 플러그인 설치 안내
• codex_cli=true: "CLI가 감지되었지만 플러그인이 필요합니다" 안내

Case C: git + 커밋 있음 + Codex 플러그인 설치 (codex_plugin=true) → 3-way 병렬 백그라운드 실행:

1. Agent(code-reviewer, model: opus, run_in_background: true) — 독립 리뷰
2. Bash(node "{codex_companion_path}" review {codex_target_flag}, run_in_background: true) — 코드 리뷰
3. Bash(node "{codex_companion_path}" adversarial-review {codex_target_flag} - < /tmp/deep-review-focus.txt, run_in_background: true) — 적대적 리뷰 (focus_text는 stdin)

{codex_target_flag}: clean 또는 WIP 커밋 후 → --base {review_base}, dirty tree → --uncommitted

커밋되지 않은 상태에서:

• 사용자에게 WIP 커밋 제안
• 수락 → WIP 커밋 후 Case C (--base)
• 거부 → Claude Opus 리뷰 (diff 기반) + Codex도 실행 (--uncommitted로 동일 대상 리뷰)

Stage 4: Verdict (판정)

1. 모든 백그라운드 리뷰어의 완료 알림 수신 후 결과 수집
   • 완료 알림은 Claude Code 런타임이 자동 전달 (polling 불필요)
   • 리뷰어 실패 시 "미수행" 표시, 성공한 리뷰어만으로 합성
2. 교차 검증 합성 (codex-integration.md 참조)
3. Verdict 결정: APPROVE / REQUEST_CHANGES / CONCERN
4. 리포트 생성: .deep-review/reports/{날짜}-review.md
5. REQUEST_CHANGES 시 + Codex 있으면: "codex:rescue로 수정을 위임하시겠습니까?" 제안

config.yaml 스키마

# .deep-review/config.yaml
review_model: opus              # opus | sonnet (리뷰어 모델)
codex_notified: false           # Codex 설치 안내 1회 표시 여부
last_review: null               # 마지막 리뷰 시각
app_qa:                         # Mode 2 (v1.1에서 구현)
  last_command: null
  last_url: null