Review Fix Plan

코드를 수정하기 전, 문제 진단 → 이슈 ID 부여 → 구조화된 수정 계획 문서 생성을 수행한다. 실제 코드 수정은 이 문서를 기반으로 sagwan-agent가 별도로 수행한다.

설정

프로젝트 접두어 (Issue ID Prefix)

이슈 ID의 프로젝트 접두어. CLAUDE.md 또는 사용자 지시로 설정한다. 미설정 시 기본값 RFP를 사용한다.

예시:
  VCT_DR_Pytorch  → PREFIX=VCT
  ddingdong-be    → PREFIX=DDG
  my-web-app      → PREFIX=MWA

사용자에게 접두어를 확인한다: "프로젝트 접두어를 설정해주세요 (예: VCT). 미설정 시 RFP를 사용합니다."

서브에이전트 모델

아키텍처 근거 (벤치마크 2026-04-13)

27개 알려진 이슈(C:9, W:9, L:9) 기준 벤치마크 결과에 기반한 설계:

• Claude 서브에이전트 조합이 탐지율 100%로 충분하며 속도 2.3배 우위
• Codex는 오탐률이 높아(82개) 진단 단계에서는 비효율적
• Codex는 계획 검증(adversarial) 단계에서 가치 있음 — 발견이 아닌 도전 목적

Phase 0: 의도 명확화 (브레인스토밍 게이트)

이 단계는 HARD GATE다. "리뷰 대상만 알면 되지" 같은 가정은 어디에 집중하고 어디는 건드리지 말지 모르는 채로 진단을 시작하게 만든다 — 결과적으로 사용자가 원치 않는 영역까지 plan.md에 들어간다. CLAUDE.md "참고 문서 ≠ 확정 사양 — 넘겨짚기 금지" 원칙과 정합한다.

Phase 0-1: 컨텍스트 사전 확인 (하네스 직접)

사용자에게 묻기 전에 하네스가 다음을 읽는다 (병렬):

• CLAUDE.md (프로젝트 코드 수정 원칙)
• memory/MEMORY.md 및 사용자가 언급한 도메인의 domain_*.md 토픽 파일
• 최근 커밋 (git log --oneline -10)
• 사용자가 언급한 파일/디렉토리 — 가볍게 살펴 어떤 종류의 코드인지 파악

Phase 0-2: superpowers:brainstorming 통합 호출

Skill 도구로 superpowers:brainstorming을 호출하기 직전에, 다음 통합 오버라이드를 사용자와 모델 모두에게 텍스트로 명시한다:

brainstorming 통합 모드 (review-fix-plan Phase 0)

1. docs/superpowers/specs/에 design doc을 작성하지 않는다. 합의된 결과는 "리뷰 의도 브리프"로 본 스킬 컨텍스트에만 보존되며, Step 4 plan.md의 메타 섹션 상단에 통합된다.
2. writing-plans / superpowers:writing-plans를 호출하지 않는다. design 승인 게이트 통과 후 즉시 본 스킬의 Step 1 (리뷰 대상 확인) 으로 복귀한다.

보존되는 brainstorming 행동: 한 번에 한 질문(가능하면 객관식) / 2~3 대안 + 트레이드오프 / HARD GATE — 사용자 승인 없이는 진단 단계 진입 금지 / spec self-review.

Phase 0-3: 결정점 체크리스트 (review-fix-plan 전용)

brainstorming 진행 중 다음 결정점이 모두 다뤄져야 한다:

1. 리뷰 종류 — bug detection / 보안 / 성능 / 아키텍처 / 전체 — 어디에 집중할 것인가.
2. 대상 범위 — 특정 파일 / 디렉토리 / git diff / PR — 정확히 어디까지.
3. 심각도 컷 — CRITICAL만 / WARNING 이상 / 전체. 사용자가 "현재 의미 있게 고칠 수 있는" 수준에 맞춘다.
4. 건드리지 말 영역 — 안정 코드 / legacy / 외부 의존성 — 발견되어도 plan.md에 넣지 않는다.
5. 리뷰 강도 — 빠른 스캔 vs 적대적 깊이 / Codex adversarial 포함 여부.
6. 사용자 의심 부분 — 이미 알고 있는 hot spot이 있는가 (이거부터 보라고 우선 지정).
7. 결과물 형태 — 전체 plan.md (sagwan-agent 입력) / quick advisory only (즉시 의사결정용).

Phase 0-4: 리뷰 의도 브리프 정리 및 사용자 승인

brainstorming 종료 시점에 다음 형식으로 사용자에게 보여준다:

## 리뷰 의도 브리프 (review-fix-plan)
- 리뷰 종류: {bugs / security / perf / arch / all}
- 대상 범위: {파일·디렉토리·diff·PR 명시}
- 심각도 컷: {CRITICAL only / W+ / all}
- 건드리지 말 영역: {목록 — 발견돼도 plan.md에 넣지 않음}
- 리뷰 강도: {standard / 적대적 + Codex adversarial}
- 의심 부분 (있으면 우선): {목록}
- 결과물 형태: {full plan.md / quick advisory}

사용자에게 묻는다: "이 리뷰 의도 브리프대로 Step 1 (리뷰 대상 확인)로 진행해도 될까요?" 승인 있어야만 Step 1로 진입한다. 승인 없이 진행 금지.

Phase 0-5: 리뷰 의도 브리프 보존

리뷰 의도 브리프는:

• Step 2 서브에이전트 프롬프트에 "건드리지 말 영역", "심각도 컷", "우선 검토 hot spot" 등이 명시적 제약으로 포함된다 — 진단 결과가 사용자 의도에서 벗어나는 것을 사전 차단
• Step 4 plan.md의 상단에 그대로 포함된다 — sagwan-agent가 수정 단계에서 이 브리프를 참조해 스코프 크리프를 차단한다

Process

Step 1: 리뷰 대상 확인

사용자에게 리뷰 대상과 도메인을 확인한다.

확인 항목:

• 대상: 특정 파일/디렉토리, git diff, PR, 모듈
• 도메인 키워드: 폴더명에 사용할 간결한 식별자 (예: trainer-nan, auth-refactor)
• 프로젝트 접두어: 위 설정 참조

대상이 명확하지 않으면 반드시 먼저 질문한다. 추측으로 진행하지 않는다.

Step 2: 병렬 진단 (서브에이전트 디스패치)

Agent tool로 두 서브에이전트를 동시에 디스패치한다. 모델은 claude-sonnet-4-6으로 고정한다 (Agent A/B 공통).

Agent A — code-reviewer 관점 (설계/아키텍처):

벤치마크에서 단독 27/27 전수 탐지. 큰 그림을 보는 역할.

프롬프트 핵심:
- 스펙 준수 여부, 아키텍처 건전성
- 설계 결함, 패턴 일관성, 확장성/유지보수성 위험
- API 설계 일관성, 에러 계약
- 리소스 라이프사이클 (연결, 핸들, 메모리)
- 스레드 안전성, 싱글톤 패턴
- 각 발견 사항: 파일:라인, 문제 설명, 심각도 제안, AS-IS/TO-BE 코드

Agent B — systematic-debugging 관점 (코드/런타임):

벤치마크에서 CRITICAL 100% 재현율. 버그와 런타임 결함에 특화.

프롬프트 핵심:
- 버그, 런타임 에러, NaN/Inf 전파, division by zero
- 메모리 누수, GPU 메모리 관리, 연산 그래프 유지
- 보안 취약점 (injection, eval, 안전하지 않은 역직렬화)
- 동시성 (race condition, 공유 상태)
- 엣지 케이스, 경계값, 빈 입력 처리
- 각 발견 사항: 파일:라인, 문제 설명, 심각도 제안, AS-IS/TO-BE 코드

각 서브에이전트 프롬프트에는 반드시 다음을 포함한다:

1. 리뷰 대상 파일 경로 목록
2. 프로젝트 컨텍스트 (언어, 프레임워크, 목적)
3. 출력 형식: JSON 배열 (file, line, severity, category, description, as_is, to_be, rationale)

Step 3: 통합 및 분류 (하네스)

서브에이전트 결과를 수신 후 하네스(당신, Opus)가 통합한다.

3-1. 중복 병합: 동일 파일:라인에 대한 중복 발견 사항을 병합한다. 양쪽 관점을 모두 반영한다.

3-2. 심각도 분류:

3-3. 이슈 ID 부여:

형식: {PREFIX}-{심각도}{2자리 번호}
예시: VCT-C01, VCT-W02, VCT-L03

번호는 심각도별로 01부터 순차 부여한다.

3-4. 우선순위 정렬: CRITICAL → WARNING → LOW 순서로 정렬한다.

3-5. AS-IS / TO-BE 구성: 각 이슈에 대해 현재 코드(AS-IS)와 수정 코드(TO-BE)를 구성한다. TO-BE는 구체적인 코드여야 하며, "적절히 수정" 같은 모호한 표현은 금지한다.

3-6. 실행 체크리스트 부여: 각 이슈에 sagwan-agent가 틱오프할 수 있는 체크리스트를 붙인다. 심각도에 따라 회귀 테스트 요건이 다르다.

• CRITICAL: 회귀 테스트 작성 필수 (버그를 재현하는 테스트를 먼저 쓰고 실패를 확인한 뒤 수정)
• WARNING: 회귀 테스트 선택 (동작 변경이 있을 때만)
• LOW: 회귀 테스트 생략 (스타일/dead code 등 동작 무변경 항목)

3-7. Self-Review (하네스): plan.md를 저장하기 전에 하네스가 직접 3가지를 재확인한다. 서브에이전트 디스패치가 아니다.

1. 커버리지: 서브에이전트 A/B가 보고한 모든 발견 사항이 이슈 섹션으로 존재하는가? 중복 병합 과정에서 누락된 건 없는가?
2. Placeholder 스캔: "적절히 수정", "TBD", "유사하게 처리", "필요시 ..." 같은 모호 표현이 TO-BE/해결 방법/예상 결과에 남아있지 않은가?
3. AS-IS 정합성: 각 이슈의 AS-IS 블록이 현재 파일의 해당 라인을 그대로 인용한 것인가? 추측·재작성이 섞여 있으면 실제 코드를 다시 읽어 교체한다.

문제 발견 시 인라인에서 바로 수정한다. 3가지 모두 통과해야 Step 4로 진행한다.

Step 3.5: [선택적] Codex Adversarial 계획 검증

사용자가 "codex 검증도 해줘" 또는 "adversarial 포함"을 요청한 경우에만 실행한다. 기본 흐름에서는 생략한다.

Step 3에서 생성한 plan.md 초안을 Codex(codex:codex-rescue)에게 전달하여 도전적 검증을 수행한다.

프롬프트 핵심:
- 이 수정 계획에서 빠진 이슈가 있는가?
- 제안된 TO-BE 코드가 새로운 버그를 만들 가능성은?
- 심각도 분류가 과소/과대 평가된 것은?
- 수정 순서에 의존성 충돌이 있는가?

Codex가 유효한 누락 이슈를 발견하면 plan.md에 추가한다. 기존 이슈의 심각도 변경을 제안하면 하네스가 판단하여 반영 여부를 결정한다.

벤치마크 참고: Codex는 진단(발견) 단계에서는 오탐률이 높지만(82개/107개), 이미 작성된 계획에 대한 검증(도전) 단계에서는 범위가 제한되어 효과적이다.

Step 4: 문서 생성 및 저장

폴더 규칙:

{project_root}/m_docs/fix-plans/{YYYY-MM-DD}_{PREFIX}_{domain}/
  └── plan.md

• {project_root}: git root 또는 현재 작업 디렉토리
• {YYYY-MM-DD}: 문서 생성일
• {PREFIX}: 프로젝트 접두어
• {domain}: Step 1에서 확인한 도메인 키워드 (kebab-case)

예시: m_docs/fix-plans/2026-04-13_VCT_trainer-nan-handling/plan.md

m_docs/fix-plans/ 디렉토리가 없으면 생성한다.

문서 작성 후 사용자에게 보고한다:

## review-fix-plan 완료

- 경로: m_docs/fix-plans/{폴더명}/plan.md
- 이슈: {N}개 (🔴 C:{n} / 🟡 W:{n} / 🟢 L:{n})
- 다음 단계: sagwan-agent에게 plan.md 경로를 전달하여 수정 실행
  예시: "@sagwan plan.md 기반으로 수정해줘: m_docs/fix-plans/{폴더명}/plan.md"

plan.md 템플릿

아래 템플릿을 정확히 따른다. 구조를 변경하지 않는다 — sagwan-agent가 파싱한다.

# {작업명} 코드 리뷰 수정 계획

| 항목 | 값 |
|------|-----|
| 날짜 | {YYYY-MM-DD} |
| 프로젝트 접두어 | {PREFIX} |
| 대상 브랜치 | {branch name} |
| 총 이슈 | {N}개 (C:{n}, W:{n}, L:{n}) |
| 상태 | PLAN |

## 수정 대상 파일

- `{파일 경로}`

---

## [{PREFIX}-C01] {파일}:{라인} — {이슈 한줄 요약}

**심각도**: 🔴 CRITICAL
**문제 상황**: {사용자/시스템 관점에서 어떤 동작이 문제인지}
**문제 원인**: {코드 레벨에서 왜 이 문제가 발생하는지}

```{lang}
// AS-IS
{기존 코드 — 실제 코드를 그대로 인용}
```

**해결 방법**: {구체적인 수정 방안 서술}

```{lang}
// TO-BE
{수정 코드 — 실행 가능한 구체적 코드}
```

**예상 결과**: {수정 후 기대 효과}
**커밋 규칙**: `fix({PREFIX}-C01): {요약}`

**실행 체크리스트** (sagwan-agent용):
- [ ] AS-IS 코드가 현재 파일과 일치하는지 확인
- [ ] 회귀 테스트 작성 — 버그를 재현하는 테스트를 먼저 작성하고 실패를 확인
- [ ] TO-BE 적용
- [ ] 회귀 테스트 통과 확인 + 기존 테스트/빌드 실행
- [ ] 커밋

---

## [{PREFIX}-W01] {파일}:{라인} — {이슈 한줄 요약}

**심각도**: 🟡 WARNING
**문제 상황**: {서술}
**문제 원인**: {서술}

```{lang}
// AS-IS
{기존 코드}
```

**해결 방법**: {서술}

```{lang}
// TO-BE
{수정 코드}
```

**예상 결과**: {서술}
**커밋 규칙**: `refactor({PREFIX}-W01): {요약}`

**실행 체크리스트** (sagwan-agent용):
- [ ] AS-IS 코드가 현재 파일과 일치하는지 확인
- [ ] 회귀 테스트 작성 — 동작 변경이 있을 때만 (선택)
- [ ] TO-BE 적용
- [ ] 기존 테스트/빌드 실행
- [ ] 커밋

---

## [{PREFIX}-L01] {파일}:{라인} — {이슈 한줄 요약}

**심각도**: 🟢 LOW
**문제 상황**: {서술}
**문제 원인**: {서술}

```{lang}
// AS-IS
{기존 코드}
```

**해결 방법**: {서술}

```{lang}
// TO-BE
{수정 코드}
```

**예상 결과**: {서술}
**커밋 규칙**: `style({PREFIX}-L01): {요약}`

**실행 체크리스트** (sagwan-agent용):
- [ ] AS-IS 코드가 현재 파일과 일치하는지 확인
- [ ] TO-BE 적용
- [ ] 기존 테스트/빌드 실행
- [ ] 커밋

---

## 패턴 정리

| 이슈 ID | 교훈 | 재발 방지 규칙 |
|---------|------|---------------|
| {PREFIX}-C01 | {이번 리뷰에서 얻은 교훈} | {재발 방지를 위한 규칙} |

---

## sagwan-agent 실행 가이드

1. 이 파일을 sagwan-agent에게 전달한다
2. **각 이슈 수정 전, AS-IS 코드가 현재 코드와 일치하는지 반드시 확인한다.** 불일치 시 TO-BE를 현재 코드의 문법·패턴·관습에 맞게 조정한 뒤 수정한다. TO-BE는 참고 코드이지 verbatim 복사 대상이 아니다.
3. CRITICAL → WARNING → LOW 순서로 수정한다
4. 각 이슈의 **실행 체크리스트**를 순서대로 틱오프한다. CRITICAL은 회귀 테스트(실패 확인 → TO-BE → 통과 확인)가 필수다.
5. 각 이슈의 **커밋 규칙**을 반드시 준수한다
6. 모든 수정 완료 후 같은 폴더에 `result.md`를 생성한다

result.md 템플릿 (sagwan-agent가 생성)

sagwan-agent는 plan.md 기반 수정 완료 후 같은 폴더에 아래 형식으로 result.md를 생성한다.

# {작업명} 코드 리뷰 수정 결과

| 항목 | 값 |
|------|-----|
| 날짜 | {YYYY-MM-DD} |
| 원본 계획 | [plan.md](./plan.md) |
| 프로젝트 접두어 | {PREFIX} |
| 상태 | ✅ DONE / ⚠️ PARTIAL |

## 수정 결과 요약

| 이슈 ID | 심각도 | 상태 | 커밋 해시 | 커밋 메시지 |
|---------|--------|------|-----------|------------|
| {PREFIX}-C01 | 🔴 | ✅ 완료 | `abc1234` | `fix({PREFIX}-C01): 요약` |
| {PREFIX}-W01 | 🟡 | ✅ 완료 | `def5678` | `refactor({PREFIX}-W01): 요약` |
| {PREFIX}-L01 | 🟢 | ⏭️ 스킵 | - | 사유: {스킵 사유} |

## 이슈별 상세

### [{PREFIX}-C01] ✅ 완료
- **계획된 수정**: {plan.md의 해결 방법 요약}
- **실제 수정**: {실제로 적용된 변경 요약}
- **차이점**: {계획과 다른 부분이 있으면 기술, 없으면 "계획대로 수정"}
- **커밋**: `fix({PREFIX}-C01): {메시지}` → `{full commit hash}`
- **검증**: {테스트 통과 여부, 동작 확인 결과}

## 검증 결과

| 항목 | 결과 |
|------|------|
| 테스트 | ✅ 통과 / ❌ 실패 ({상세}) |
| 빌드 | ✅ 성공 / ❌ 실패 ({상세}) |
| 린트 | ✅ 통과 / ❌ 실패 ({상세}) |

## 잔설의 최종 소견
{한 문장으로 전체 수정 작업에 대한 판단}

## Git 추적 명령어
```bash
# 전체 이슈 추적
git log --grep="{PREFIX}-"

# 특정 이슈 추적
git log --grep="{PREFIX}-C01"
```

Git 커밋 규칙

이슈 ID를 conventional commit 형식에 포함한다.

추적:

git log --grep="VCT-C01"      # 특정 이슈
git log --grep="VCT-"         # 프로젝트 전체
git log --grep="VCT-C"        # CRITICAL만

통합 스킬

• sagwan-agent — plan.md 기반 수정 실행 + result.md 생성
• superpowers:systematic-debugging — Agent B의 진단 프레임워크 (CRITICAL 100% 재현율)
• superpowers:code-reviewer — Agent A의 리뷰 프레임워크 (단독 27/27 전수 탐지)
• codex:codex-rescue — [선택적] Step 3.5 adversarial 계획 검증 엔진