aidlc-requesting-code-review

name	aidlc-requesting-code-review
description	태스크나 unit 구현이 완료되어 머지 전 코드 리뷰가 필요할 때, 또는 사용자가 명시적으로 코드 리뷰를 요청할 때 사용. Use when a task or unit implementation is complete and needs code review before merging, or when the user explicitly requests a code review on their changes.
metadata	{"version":"0.1.0","author":"Jay","category":"ai-dlc-workflow","invoke_mode":"user-invocable","return_behavior":"stop-no-gate","skill_nature":"hybrid","lifecycle":"active","model_dependency":"모델이 자신의 코드를 비판적으로 재검토하지 않음","amplification_notes":"3-stage/4-stage 리뷰 + 다중 reviewer 디스패치 구조"}

aidlc-requesting-code-review

Trigger

다음 상황에서 이 스킬을 실행한다:

• 태스크/유닛 구현이 완료되고 머지 전 리뷰가 필요할 때
• PR 생성 전 코드 품질을 확인하고 싶을 때
• 복잡한 리팩토링이나 버그 수정 후 검증이 필요할 때
• aidlc-subagent-driven-development가 태스크 완료 후 자동 호출할 때

Purpose

depth에 따라 3-stage (Standard) 또는 4-stage (Comprehensive) code review를 실행하고 결과를 반환한다. 이 스킬이 코드 리뷰 프로세스의 유일한 정의이다 — 다른 스킬은 리뷰 로직을 자체 구현하지 않고 이 스킬을 호출한다.

---

입력

항목	필수	설명
리뷰 대상	필수	git diff, 파일 경로, 또는 커밋 SHA
spec/plan 경로	선택	spec compliance 검증용. 미제공 시 Stage 1 스킵
depth	선택	Minimal/Standard/Comprehensive. 기본 Standard

---

프로세스

0. Depth 확인

• Minimal / Standard / Comprehensive: 리뷰 모드 선택으로 진행

0.1. 리뷰 모드 선택

리뷰 모드를 선택한다. 호출 시 모드가 지정되면 해당 모드를 사용하고, 미지정이면 기본값(R1).

리뷰 모드:
R1) 단일 리뷰 (3-stage Standard / 4-stage Comprehensive) ← 기본
R2) Council 리뷰
Ra) 자동 선택 (risk score 기반)

R1 선택: Stage 1 → Stage 2 → Stage 3 → Stage 4 (기존 동작 그대로)

R2/Ra 선택: Council 리뷰로 진행

---

R1 흐름: 단일 리뷰

Step 0 — 프로젝트 루트 결정

devflow-docs/devflow-state.md의 ## Worktree → path 값을 확인한다.

• 값이 있으면: 해당 워크트리의 절대 경로를 {project-root}로 사용
• 값이 없거나 none이면: 현재 CWD를 {project-root}로 사용

이후 모든 Stage의 서브에이전트 dispatch 시 {project-root}를 프롬프트에 포함한다:

프로젝트 루트: {project-root}
중요: 모든 파일 경로는 프로젝트 루트 기준이다. 파일을 읽을 때 반드시 프로젝트 루트를 prefix로 사용하라.

Stage 1 — Spec Compliance

spec/plan 경로가 제공된 경우에만 실행. 미제공 시 Stage 2로 바로 진행.

1. _shared/reviewers/spec-reviewer-prompt.md 읽기
2. 서브에이전트 dispatch — {project-root} + 리뷰 대상 + spec/plan 경로 전달
3. 결과 확인 (Verdict 기준):
   • PASS → Stage 2로
   • FAIL → 수정 후 re-dispatch (conventions 리뷰 루프 규약: 최대 3회, 초과 시 사용자 escalate)
   • CONDITIONAL → Stage 2로 (수정 권장)

Codex 세컨드 오피니언 (결과 반환 시 안내)

conventions Codex 세컨드 오피니언 정책 적용.

Claude 리뷰 결과 반환 시, Codex 세컨드 오피니언 실행 가이드를 함께 표시한다.

수동 실행 전용: /codex:review는 disable-model-invocation 제약으로 Claude가 자동 호출할 수 없다. 아래 가이드를 표시하고 사용자가 직접 실행한다.

안내 생성 규칙:

1. devflow-state.md에서 워크트리 정보를 읽는다:
   • ## Worktree → branch, path 값 확인
2. 리뷰 대상 범위를 결정한다:
   • 워크트리 있음 → --scope branch (현재 브랜치의 전체 변경)
   • 워크트리 없음 + staged 변경 → --uncommitted
   • 워크트리 없음 + 커밋 완료 → --base main (main 대비 diff)
3. CONDITIONAL/FAIL stage가 있으면 해당 관점을 힌트로 포함한다

안내 템플릿:

> **Codex 세컨드 오피니언**: 추가 검증이 필요하면 아래 명령을 실행하세요.
> → `/codex:review --scope branch`
>   브랜치: [branch명], 워크트리: [path]
>   [CONDITIONAL/FAIL stage가 있으면] 참고: [stage명]에서 [이슈 요약] 발견 — Codex 관점도 확인 권장

Codex CLI 미감지 시 안내를 생략한다 (conventions fallback 참조).

Stage 2+3(+4) — Code Quality + Security (+ Maintainability) 병렬

타임아웃: conventions 타임아웃 정책 적용. 개별 리뷰어 기본 300초. 타임아웃 시 "⏭ 타임아웃" 표시, 나머지 결과로 종합.

Stage 1 완료 후, depth에 따라 병렬 dispatch한다.

Minimal: Stage 2만 단독 실행 (Stage 3 스킵) Standard: Stage 2 + Stage 3 병렬 dispatch Comprehensive: Stage 2 + Stage 3 + Stage 4 전부 병렬 dispatch

1. _shared/reviewers/code-quality-reviewer-prompt.md — Stage 2 서브에이전트 dispatch (background, {project-root} 포함)
2. _shared/reviewers/security-reviewer-prompt.md — Stage 3 서브에이전트 dispatch (background, Standard 이상)
3. _shared/reviewers/maintainability-reviewer-prompt.md — Stage 4 서브에이전트 dispatch (background, Comprehensive만)
4. 모든 결과 수신 후 종합:
   • 모두 PASS → 결과 반환
   • 일부 FAIL → FAIL stage만 수정 루프 (PASS stage 결과 유지, 최대 3회)
   • 모두 FAIL → 모든 stage 수정 루프

---

R2/Ra 흐름: Council 리뷰

R2 또는 Ra 선택 시, 4-stage 관점을 외부 AI와 함께 실행한다.

4-stage와 Council의 관계: 4-stage는 "무엇을 볼 것인가"(관점 커버리지), Council은 "누가 볼 것인가"(다모델 편향 보완). 두 차원은 직교한다. Council이 바꾸는 것은 Stage 2-4의 실행 주체이지, 관점 자체를 대체하지 않는다.

1. Stage 1 (Spec Compliance): spec/plan 제공 시 Claude 서브에이전트로 실행 (R1과 동일)
   • 요구사항 대조는 사실 확인이므로 외부 AI 불필요
2. _shared/patterns/council-cli-detection.md 절차 실행:
   • CLI 감지 → 가용 AI 목록 표시 → 사용자에게 참여 AI 확인 (전부/일부/없이)
   • 사용자 선택으로 모드 확정 (council-full/council-lite/single)
   • Ra 선택 시: 확정된 모드 범위 내에서 Risk Scoring으로 single/council 자동 결정
   • single 확정 시: R1 흐름의 Stage 2로 전환하여 이후 Stage 3 → Stage 4 순서대로 진행
3. Stage 2-4를 council-review-protocol로 dispatch:
   • Codex 관점: Stage 2 (Quality) + Stage 4 (Maintainability, Comprehensive만)
   • Gemini 관점: Stage 3 (Security/Edge-case)
   • council-lite 시: 병합 프롬프트 사용 (1개 AI가 모든 관점 수행)
   • 리뷰 입력 번들 (파일 경로만 전달):
     • 리뷰 대상: git diff + 변경 파일 경로
     • 참조: 테스트 결과 요약, requirements.md
4. 결과 저장: devflow-docs/construction/{unit}/code-review-raw/{codex,gemini,synthesis}.md
5. Claude 의장이 개별 결과를 읽고 synthesis.md 작성 (충돌 해결 4단계 적용)
6. synthesis 결과를 사용자에게 표시 + 승인 대기:

   [Council Code Review 결과]
   Verdict: [PASS|CONDITIONAL|FAIL]
   Rationale: [판정 근거]
   Action Items: [수정 항목]
   
   A) 리뷰 반영하여 수정
   B) 현재 상태로 승인
   

7. 결과를 결과 반환 형식으로 반환 (council 모드 표시 추가)

---

결과 반환

각 Stage의 리뷰어는 _shared/patterns/review-feedback-schema.md의 출력 포맷을 따른다. Synthesis는 개별 Verdict를 worst-of 로직으로 집계한다.

## Code Review 결과
- Stage 1 (Spec Compliance): PASS | CONDITIONAL | FAIL | ⏭ 스킵 (spec 미제공)
- Stage 2 (Code Quality): PASS | CONDITIONAL | FAIL
- Stage 3 (Security/Edge-case): PASS | CONDITIONAL | FAIL | ⏭ 스킵 (Minimal)
- Stage 4 (Maintainability): PASS | CONDITIONAL | FAIL | ⏭ 스킵 (Standard 이하)
- Verdict: PASS | CONDITIONAL | FAIL (worst-of across all stages)
- Issues: [있으면 — severity + file:line 테이블]
- Score: [루브릭 항목별 🟢/🟡/🔴 집계]

Verdict 집계 (worst-of): 어느 Stage든 FAIL이면 전체 FAIL. FAIL 없이 CONDITIONAL 있으면 전체 CONDITIONAL. 모두 PASS면 전체 PASS.

---

Standalone vs SDD 호출

모드	트리거	spec/plan	depth	리뷰 모드
Standalone	사용자 직접 호출	사용자 지정 (없으면 Stage 1 스킵)	사용자 지정 또는 Standard	사용자 선택 (R1/R2/Ra)
SDD	태스크 완료 후 자동	태스크의 spec/plan 경로	plan Complexity 연동	R1 (기본값 고정)

SDD에서 호출 시, SDD가 리뷰 대상(변경 파일)과 spec/plan 경로를 전달한다. 리뷰 모드는 항상 R1 — 팀/Council 모드는 사용자 명시 선택 시에만.

---

리뷰어 프롬프트 관계

프롬프트	용도	이 스킬에서의 역할
spec-reviewer-prompt.md	spec compliance 단독 검증	Stage 1
code-quality-reviewer-prompt.md	코드 품질 단독 검증	Stage 2
security-reviewer-prompt.md	보안/엣지케이스 심층 분석	Stage 3 (Standard 이상)
maintainability-reviewer-prompt.md	유지보수성/기술부채 평가	Stage 4 (Comprehensive만)
code-reviewer-prompt.md	Spec + Quality 통합	이 스킬에서 사용하지 않음 (construction-orchestrator 간편 리뷰용)

---

리뷰 시점 가이드

필수:

• 태스크/유닛 구현 완료 후
• PR/머지 전

권장:

• 복잡한 리팩토링 후
• 버그 수정 후 (회귀 테스트와 함께)
• 아키텍처 변경이 포함된 작업 후

---

Examples

Example 1: Standalone — PR 전 리뷰 (Standard)

사용자: "이 변경사항 리뷰해줘"

[depth: Standard, spec 미제공]
→ Stage 1 스킵 (spec 없음)
→ Stage 2: code-quality-reviewer dispatch → PASS
→ Stage 3: security-reviewer dispatch → PASS
→ Verdict: PASS / Recommendations 2건

Example 2: SDD에서 자동 호출 (Standard)

SDD: 태스크 3 완료, requesting-code-review 호출
  리뷰 대상: src/auth.py, tests/test_auth.py
  spec: docs/plans/auth-plan.md Task 3
  depth: Standard

→ Stage 1: spec-reviewer → FAIL (누락된 에러 핸들링)
→ 수정 후 재리뷰 → PASS
→ Stage 2: code-quality-reviewer → PASS
→ Stage 3: security-reviewer → PASS
→ Verdict: PASS

Example 3: Comprehensive 리뷰

[depth: Comprehensive, spec 제공]
→ Stage 1: spec-reviewer → PASS
→ Stage 2: code-quality-reviewer → PASS
→ Stage 3 + 4 병렬 dispatch:
  → security-reviewer → FAIL (SQL injection 위험)
  → maintainability-reviewer → PASS
→ 수정 후 Stage 3 재리뷰 → PASS
→ Verdict: PASS / Recommendations 1건

---

Troubleshooting

Stage 1에서 반복 실패

증상: spec compliance 리뷰가 3회 넘게 실패 원인: spec 자체가 모호하거나 현재 구현과 맞지 않음 해결: 사용자 escalate 후 spec 수정 또는 Stage 1 스킵 결정

Standalone에서 Stage 1이 항상 스킵됨

증상: spec/plan 경로를 제공하지 않아 항상 Stage 2만 실행 해결: 리뷰 요청 시 관련 spec/plan 경로를 함께 전달. 예: "docs/plans/xxx-plan.md의 Task 2 기준으로 리뷰해줘"