Build Plan

신규 기능을 구현하기 전, 조사 → 브레인스토밍 → 스펙 확정 → 피처 ID 부여 → 구조화된 빌드 계획 문서 생성을 수행한다. 실제 코드 작성은 이 문서를 기반으로 sagwan-agent가 별도로 수행한다.

review-fix-plan과 대칭 구조이며, ID 체계·폴더 규칙·result.md 흐름을 같은 형식으로 유지해 프로젝트 내 두 흐름(버그 패치 / 신규 빌드)이 통합 추적될 수 있게 한다.

설정

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

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

review-fix-plan과 같은 PREFIX를 쓰면 이슈 추적이 통합된다. 예: VCT-C01(버그 패치) + VCT-F01(신규 기능)이 한 프로젝트 안에서 공존.

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

ID 카테고리

분류 기준:

• F: 지금까지 없던 기능의 추가. "CSV 임포트 추가", "2FA 로그인 추가"
• E: 기존 기능의 확장/개선. "로그인에 2FA 옵션 추가", "임포트 속도 3배 개선"
• R: 본격 구현 전 검증이 필요한 탐색. "라이브러리 A vs B 벤치마크", "Diffusion backbone 교체 타당성"

R은 구현 후 통상 F 또는 E로 승격된다. plan.md에는 "R01 → 후속 F02 생성 예정" 같은 전환 경로를 남긴다.

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

이 단계는 HARD GATE다. 건너뛰지 않는다. "단순한 요청"이라는 가정이 가장 큰 낭비를 만든다. 요청에 암묵적으로 들어 있는 결정점을 명시적으로 끌어내는 것이 이 단계의 유일한 목적이다. 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 스킬이 컨텍스트로 보게 된다):

brainstorming 통합 모드 (build-plan Phase 0)

1. docs/superpowers/specs/에 design doc을 작성하지 않는다. 합의된 design은 본 스킬의 작업 컨텍스트 안에 "의도 브리프"로만 보존되며, Step 7 plan.md의 "스펙 요약" 섹션에 통합된다.
2. writing-plans / superpowers:writing-plans를 호출하지 않는다. design 승인 게이트 통과 후 brainstorming은 종료되고, 즉시 본 스킬의 Step 1 (입력 수집 및 확인) 으로 복귀한다 — build-plan이 자체 plan.md 생성 흐름을 가지기 때문이다.

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

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

brainstorming 진행 중 다음 결정점이 모두 다뤄져야 한다 (해당 없으면 명시적으로 "해당 없음" 확인):

1. 진짜 목표 — 한 문장으로 "무엇을 / 누구를 위해 / 왜". 사용자 표현을 받아쓰지 말고 다시 표현해서 확인받는다.
2. 주 사용자 / 주 시나리오 — 누가 언제 이 기능을 트리거하는가.
3. 스코프 IN / OUT (Non-goals) — 반드시 포함 vs 명시적 제외.
4. 호환성·성능 제약 — 기존 인터페이스 보존 여부, 메모리/속도 한계, 의존성 추가 가능 여부.
5. 선호 접근법 유무 — 사용자가 이미 마음에 둔 라이브러리·패턴이 있는가, 자유로운 탐색을 원하는가.
6. R-spike 필요 여부 — 본격 구현 전 검증해야 할 미지수가 있는가.
7. 성공/실패 기준 — pass/fail로 판정 가능한 문장.

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

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

## 의도 브리프 (build-plan)
- 진짜 목표: {1-2문장}
- 주 사용자 / 시나리오: {서술}
- 스코프 IN: {목록}
- 스코프 OUT (Non-goals): {목록}
- 호환성·성능 제약: {목록}
- 선호 접근법: {있으면 / "자유 탐색"}
- R-spike 필요: {YES/NO + 사유}
- 성공/실패 기준: {pass/fail 판정 가능 문장}

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

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

이 의도 브리프는:

• Step 1~6 전체 흐름의 입력 컨텍스트로 사용된다
• Step 7에서 생성되는 plan.md의 "스펙 요약" 섹션 상단에 그대로 포함된다
• 추후 검증/리뷰의 기준선이 된다 — sagwan-agent가 plan.md를 따를 때 이 브리프를 참조해 스코프 크리프를 차단한다

Process

Step 1: 입력 수집 및 확인

사용자에게 다음을 확인한다. 불명확하면 추측 없이 질문한다.

• 무엇을 만들고 싶은가? (raw requirement, 자유 서술 허용)
• 대상 리포/브랜치 및 수정 범위
• 도메인 키워드 (폴더명, kebab-case. 예: auth-2fa, csv-importer)
• 프로젝트 접두어 (위 설정 참조)
• 선행 조사 결과가 있는가?
  • YES → 경로/위치를 받는다 (파일, 노트, 이전 research-breakthrough 산출물). 흡수 모드로 Step 2 진행
  • NO → 이 스킬 안에서 조사도 수행할지 확인. 실행 모드로 Step 2 진행

Step 2: 조사 단계

두 모드를 모두 지원한다.

흡수 모드 (선행 조사 있음):

• 사용자가 제공한 자료를 읽고 요약한다
• 주요 선택지·트레이드오프를 "후보 접근법 3~5개 + 장단점" 형태로 압축한다
• 자료에 부족한 부분이 있으면 제한적으로 WebSearch 보강 가능

실행 모드 (조사 필요):

• research-breakthrough 스킬의 핵심 원칙을 인라인 적용한다. 별도 디스패치가 아니라 하네스가 직접 수행한다.
• WebSearch로 관련 논문·SOTA·라이브러리·참고 구현을 찾는다
• 로컬 프로젝트 컨텍스트(현 코드베이스 스택, 제약)를 함께 고려해 "이 프로젝트에 적합한 후보"만 추린다
• 산출물: 후보 접근법 3~5개 + 장단점 + 참조 링크/논문

두 모드 모두 Step 3으로 넘어갈 때 정리된 후보 목록이 확보돼 있어야 한다.

Step 3: 조사 결과 반영 스펙 정제

Phase 0의 의도 브리프 + Step 2의 후보 목록을 교차 검토한다. 별도 brainstorming 루프가 아니라, 조사 결과가 의도 브리프의 결정을 흔드는지 확인하는 짧은 정합성 단계다.

다음을 점검한다:

• 새로 드러난 트레이드오프: Step 2 조사가 Phase 0에서 보지 못한 제약·대안을 보여줬는가
• 흔들리는 결정: Phase 0에서 사용자가 선택한 접근법이 조사 결과로 비현실적이 되었는가
• 새 열린 질문: 조사로 새로 발견된 결정점이 있는가

흔들리는 결정 또는 새 열린 질문이 발견되면 사용자에게 짧게 재확인한 뒤 의도 브리프를 갱신한다. 없으면 의도 브리프를 그대로 사용해 Step 4로 진행한다.

확정 산출물 (의도 브리프 + 조사 결과 반영):

• 기능 요구사항 (Functional)
• 비기능 요구사항 (성능·보안·호환성·관측성)
• Non-goals (의도 브리프의 스코프 OUT을 그대로 승계 — 임의 확장 금지)
• 열린 질문 (Phase 0 + Step 3에서 미결로 남은 항목)

Step 4: 선택지 정리 및 ADR

Step 2의 후보 목록과 Step 3의 스펙을 교차해 채택안을 결정한다.

산출물:

• 선택지 비교표 (접근법 / 장점 / 단점 / 복잡도 / 본 프로젝트와의 적합성)
• 채택안 + 선택 근거 (1~2문단)
• 기각안 + 기각 사유 (각 1~2문장)

이 섹션이 plan.md의 ADR(Architecture Decision Record) 미니 버전이 된다. 나중에 같은 논의를 반복하지 않기 위한 브레이크라인이다.

Step 5: 피처 분해 및 ID 부여

스펙을 F/E/R 단위로 분해한다.

분해 원칙:

• 각 피처는 독립적으로 테스트 가능해야 한다
• 각 피처는 **하나의 커밋(또는 작은 PR)**로 마무리될 수 있어야 한다
• 피처간 의존성이 있으면 depends_on: [F01] 메타로 명시한다 (순환 금지)

ID 부여:

형식: {PREFIX}-{카테고리}{2자리 번호}
예시: VCT-F01, VCT-E02, VCT-R01

번호는 카테고리별로 01부터 순차 부여한다.

우선순위 부여:

Step 5.5: [선택적] Codex Adversarial 스펙 검증

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

Step 5까지의 plan.md 초안을 Codex(codex:codex-rescue)에게 전달하여 도전적 검증을 수행한다.

프롬프트 핵심:
- 이 스펙에서 빠진 수용 기준이 있는가?
- 채택한 접근법이 놓친 엣지케이스·장애 모드는?
- 피처 분해가 과/소 분할된 것은? (독립 테스트 가능성 검증)
- 의존성 그래프에 순환이나 누락이 있는가?

Codex가 유효한 누락/오류를 지적하면 plan.md에 반영한다.

Step 6: Self-Review (하네스)

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

1. 커버리지: Step 3에서 합의된 모든 요구사항이 피처 섹션으로 존재하는가? Non-goals로 명시적 제외된 것 외에 누락이 없는가?
2. 수용 기준 테스트 가능성: 모든 "수용 기준"이 pass/fail을 객관적으로 판정할 수 있는 문장인가? "잘 동작한다", "빠르게 처리한다" 같은 주관 표현이 남아있지 않은가?
3. 의존성 정합성: depends_on이 실제로 존재하는 피처 ID를 가리키는가? 순환 의존성이 없는가?

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

Step 7: 문서 생성 및 저장

폴더 규칙:

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

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

예시: m_docs/build-plans/2026-04-24_VCT_auth-2fa/plan.md

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

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

## build-plan 완료

- 경로: m_docs/build-plans/{폴더명}/plan.md
- 피처: {N}개 (F:{n} / E:{n} / R:{n})
- 우선순위: P0:{n} / P1:{n} / P2:{n}
- 열린 질문: {n}개 (있으면 사용자 결정 필요)
- 다음 단계: sagwan-agent에게 plan.md 경로 전달
  예시: "@sagwan plan.md 기반으로 구현해줘: m_docs/build-plans/{폴더명}/plan.md"

plan.md 템플릿

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

# {작업명} 빌드 계획

| 항목 | 값 |
|------|-----|
| 날짜 | {YYYY-MM-DD} |
| 프로젝트 접두어 | {PREFIX} |
| 대상 브랜치 | {branch name} |
| 총 피처 | {N}개 (F:{n}, E:{n}, R:{n}) |
| 상태 | PLAN |

## 스펙 요약

**무엇을 만드는가** (1~2문장):
{요약}

**주 사용자 / 주 시나리오**:
{서술}

**기능 요구사항**:
- {항목}

**비기능 요구사항**:
- 성능: {지표}
- 보안: {요건}
- 호환성: {요건}
- 관측성: {로그·메트릭 요건}

**Non-goals (스코프 밖)**:
- {명시적 제외 항목 — "이번에는 안 한다"고 합의된 것}

## 선택지 및 채택안 (ADR)

| 후보 | 장점 | 단점 | 복잡도 | 채택 여부 |
|---|---|---|---|---|
| A. {이름} | {서술} | {서술} | L/M/H | ✅ 채택 |
| B. {이름} | {서술} | {서술} | L/M/H | ❌ 기각 |
| C. {이름} | {서술} | {서술} | L/M/H | ❌ 기각 |

**채택 근거**: {A를 고른 이유, 1~2문단}

**기각 사유**:
- B: {한 문장}
- C: {한 문장}

**참조 자료**:
- {URL 또는 논문/레포/문서 이름}

## 대상 파일 (예상)

- Create: `{새로 만들 파일 경로}`
- Modify: `{수정할 기존 파일 경로}`

---

## [{PREFIX}-F01] {피처 한줄 요약}

**카테고리**: 🆕 Feature
**우선순위**: 🔵 P0 MUST
**depends_on**: [] (또는 [{PREFIX}-F00, ...])

**스펙**: {이 피처가 제공해야 하는 동작. Behavior 중심}

**수용 기준** (Given-When-Then):
- **Given** {초기 상태} **When** {동작} **Then** {검증 가능한 결과}
- **Given** ... **When** ... **Then** ...

**구현 스케치**:
- 모듈 경계: `{파일 또는 모듈}` — {책임}
- 타입/인터페이스:
```{lang}
{핵심 타입 시그니처 또는 API 형태}
```
- 핵심 플로우: {간단한 의사코드 또는 단계 리스트}

**실행 체크리스트** (sagwan-agent용, TDD 순서):
- [ ] 수용 기준을 실패 테스트로 작성
- [ ] 테스트 실행 — 실패 확인
- [ ] 최소 구현 작성
- [ ] 테스트 실행 — 통과 확인
- [ ] 필요 시 리팩터 + 통합 테스트
- [ ] `feat({PREFIX}-F01): {요약}` 커밋

**커밋 규칙**: `feat({PREFIX}-F01): {요약}`

---

## [{PREFIX}-E01] {피처 한줄 요약}

**카테고리**: 🔧 Enhancement
**우선순위**: 🟢 P1 SHOULD
**depends_on**: [{PREFIX}-F01]
**대상 파일**: `{기존 파일 경로}`

**스펙**: {무엇을 어떻게 개선하는가. 변경 전/후 동작 차이 명시}

**수용 기준** (Given-When-Then):
- **Given** ... **When** ... **Then** ...

**구현 스케치**:
- 변경 포인트: `{파일}:{라인 추정}`
- 접근: {기존 구조에 어떻게 통합할지. 기존 인터페이스 보존 여부}
```{lang}
{핵심 변경 부분 스케치}
```

**실행 체크리스트** (sagwan-agent용):
- [ ] 기존 동작 보존 회귀 테스트 확인 (없으면 추가)
- [ ] 개선 동작에 대한 실패 테스트 작성
- [ ] 테스트 실행 — 실패 확인
- [ ] 구현 적용
- [ ] 전체 테스트 통과 확인
- [ ] 커밋

**커밋 규칙**: `feat({PREFIX}-E01): {요약}` (성능 개선은 `perf`, 구조만 변경이면 `refactor`)

---

## [{PREFIX}-R01] {연구 주제 한줄 요약}

**카테고리**: 🔬 Research Spike
**우선순위**: 🔵 P0 MUST
**depends_on**: []
**타임박스**: {예: 2시간, 반나절, 1일}

**질문**: {이 스파이크로 답하고자 하는 구체적 질문}

**성공 기준**: {어떤 데이터/결과가 나오면 "답을 얻음"인가 — 숫자나 관찰 가능한 조건}

**실험 설계**:
1. {단계}
2. {단계}
3. 결과 기록 위치: `{경로}` (예: `m_docs/build-plans/.../r01-results.md`)

**실행 체크리스트** (sagwan-agent용):
- [ ] 실험 환경 구축
- [ ] 실험 수행
- [ ] 결과를 지정 경로에 기록
- [ ] plan.md에 R01 결과 요약 추가
- [ ] 후속 피처(F/E) 승격 여부 판단 및 기록
- [ ] `chore({PREFIX}-R01): {요약}` 커밋 (실험 코드는 별도 브랜치 유지 가능)

**커밋 규칙**: `chore({PREFIX}-R01): research spike — {요약}`

**승격 경로**: {예: 결과가 긍정적이면 F02 "본격 구현" 추가 / 부정적이면 B안으로 우회 / 보류}

---

## 열린 질문

sagwan-agent 실행 **전에** 사람이 결정해야 할 항목. 결정 없이 진행하면 sagwan이 자의적 선택을 하게 된다.

| ID | 질문 | 영향 받는 피처 | 결정 필요 시점 |
|---|---|---|---|
| Q01 | {질문} | F01, E02 | F01 구현 전 |

## 패턴 정리

| 피처 ID | 배운 것 | 재사용 규칙 |
|---|---|---|
| F01 | {구현 중 얻은 인사이트} | {다음 유사 상황에서 적용할 규칙} |

---

## sagwan-agent 실행 가이드

1. 이 파일을 sagwan-agent에게 전달한다
2. **Step 0: 열린 질문 확인.** 결정되지 않은 질문이 있으면 사용자에게 먼저 묻고, 답을 plan.md에 반영한 뒤 구현을 시작한다.
3. **구현 순서**: 의존성 그래프를 위상 정렬 후, 같은 레벨 내에서는 P0 → P1 → P2
4. **각 피처마다 실행 체크리스트를 순서대로 틱오프한다.** TDD 순서(실패 테스트 → 구현 → 통과 확인)는 건너뛰지 않는다. 테스트가 명백히 무의미한 피처(예: 단순 설정 값 추가)는 체크리스트에 사유를 기재하고 스킵 가능.
5. **구현 스케치는 참고용**이다. 실제 코드는 현재 코드베이스의 문법·패턴·관습에 맞게 조정한다. 스케치를 verbatim 복사하지 않는다.
6. 각 피처의 **커밋 규칙**을 반드시 준수한다
7. 모든 구현 완료 후 같은 폴더에 `result.md`를 생성한다

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

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

# {작업명} 빌드 결과

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

## 구현 결과 요약

| 피처 ID | 카테고리 | 우선순위 | 상태 | 커밋 해시 | 커밋 메시지 |
|---|---|---|---|---|---|
| {PREFIX}-F01 | 🆕 | 🔵 P0 | ✅ 완료 | `abc1234` | `feat({PREFIX}-F01): 요약` |
| {PREFIX}-E01 | 🔧 | 🟢 P1 | ✅ 완료 | `def5678` | `feat({PREFIX}-E01): 요약` |
| {PREFIX}-R01 | 🔬 | 🔵 P0 | ✅ 완료 | `ghi9012` | `chore({PREFIX}-R01): ...` |

## 열린 질문 해결

| ID | 질문 | 결정 내용 | 근거 |
|---|---|---|---|
| Q01 | {질문} | {결정} | {근거} |

## 피처별 상세

### [{PREFIX}-F01] ✅ 완료
- **계획된 스펙**: {plan.md 스펙 요약}
- **실제 구현**: {실제 적용된 설계 요약}
- **차이점**: {계획과 다른 부분, 없으면 "계획대로 구현"}
- **수용 기준 검증**: {각 기준의 pass/fail과 근거}
- **커밋**: `feat({PREFIX}-F01): {메시지}` → `{full hash}`

## R 스파이크 결과 (있는 경우)

### [{PREFIX}-R01]
- **실험 결과**: {데이터/지표 요약}
- **판정**: ✅ 긍정 / ⚠️ 중립 / ❌ 부정
- **후속**: {승격 계획, 포기, 보류 등}

## 검증 결과

| 항목 | 결과 |
|---|---|
| 테스트 | ✅ 통과 / ❌ 실패 ({상세}) |
| 빌드 | ✅ 성공 / ❌ 실패 ({상세}) |
| 린트 | ✅ 통과 / ❌ 실패 ({상세}) |
| 수용 기준 | ✅ {n}/{N} 충족 |

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

## Git 추적 명령어
```bash
# 프로젝트 전체 빌드 이슈 추적
git log --grep="{PREFIX}-"

# 카테고리별
git log --grep="{PREFIX}-F"    # Feature만
git log --grep="{PREFIX}-E"    # Enhancement만
git log --grep="{PREFIX}-R"    # Research spike만

# 특정 피처
git log --grep="{PREFIX}-F01"
```

Git 커밋 규칙

피처 ID를 conventional commit 형식에 포함한다.

추적:

git log --grep="VCT-F01"      # 특정 피처
git log --grep="VCT-"         # 프로젝트 전체
git log --grep="VCT-F"        # Feature만
git log --grep="VCT-R"        # Research만

통합 스킬

• sagwan-agent — plan.md 기반 구현 실행 + result.md 생성
• superpowers:brainstorming — Step 3의 스펙 탐색 원칙 (인라인 적용)
• research-breakthrough — Step 2의 조사 원칙 (실행 모드에서 인라인 적용)
• codex:codex-rescue — [선택적] Step 5.5 adversarial 스펙 검증 엔진
• review-fix-plan — 대칭 스킬(버그 패치용). 같은 PREFIX 공유 시 VCT-C01(패치)과 VCT-F01(빌드)이 한 프로젝트에서 통합 추적된다.