/plan-first

작업 시작 전 3가지 문서를 먼저 만들고, 사용자 검토 후 실행하는 작업 방법론 스킬.

비유: 건축에서 설계도(계획서) + 시방서(맥락노트) + 공정표(체크리스트)를 먼저 만든 뒤 공사를 시작하는 것과 같다.

저장 구조

[프로젝트 루트]/.plan/[작업명]-YYYY-MM-DD/
  ├── plan.md        ← 계획서 (무엇을, 어떻게)
  ├── context.md     ← 맥락노트 (왜, 관련 자료 위치)
  └── checklist.md   ← 체크리스트 (진행 추적)

작업명은 한글 또는 영문 kebab-case로 짧게 짓는다. (예: 입금매칭-자동화, flip-send-system)

실행 흐름

Phase 1: 현황 분석

사용자 요청을 받으면, 코드를 쓰기 전에 먼저 충분히 탐색한다.

수행할 것:

요청 파악 — 사용자가 원하는 최종 결과물이 무엇인지 정리
현재 상태 탐색 — Glob, Grep, Read로 관련 파일·코드·시스템 현황 파악
범위 확정 — 포함/미포함 항목 명확화
의존성 확인 — 필요한 API, 라이브러리, 외부 시스템 체크

탐색에 충분한 시간을 들인다. 서두르지 않는다.

Phase 2: 3문서 초안 작성

분석 결과를 바탕으로 3개 문서를 화면에 먼저 표시한다. 파일 저장은 아직 하지 않는다. 사용자가 화면에서 직접 확인할 수 있게 마크다운으로 출력한다.

문서 1: 계획서 (plan.md)

# 계획서: [작업명]

> 생성일: YYYY-MM-DD
> 상태: 초안 / 승인됨 / 실행 중 / 완료

## 목표
이 작업이 완료되면 어떤 상태가 되는지 1-2문장으로.

## 현재 상황
지금 상태 요약. 무엇이 있고, 무엇이 없는지.

## 범위
### 포함
- 이번에 만들/고칠 것

### 미포함
- 이번에 하지 않는 것 (추후 과제)

## 단계별 작업
### 1단계: [이름]
- 무엇을 하는지
- 예상 산출물

### 2단계: [이름]
- ...

### N단계: [이름]
- ...

## 예상 결과물
- 생성/수정될 파일 목록
- 최종 산출물 형태

## 리스크 & 주의사항
- 알려진 위험 요소
- 실패 시 대응 방안

문서 2: 맥락노트 (context.md)

# 맥락 노트: [작업명]

> 생성일: YYYY-MM-DD
> 마지막 업데이트: YYYY-MM-DD HH:MM

## 현재 상황 분석
기존 시스템/코드가 어떻게 되어 있는지 상세 기술.

## 관련 파일 & 자료
| 파일/자료 | 위치 | 역할 |
|-----------|------|------|
| ... | `path/to/file` | 설명 |

## 결정 사항
| 결정 | 이유 | 기각한 대안 |
|------|------|-------------|
| ... | ... | ... |

## 의존성
- 외부 API, 라이브러리, 사전 작업 등

## 참고 메모
작업 중 발견한 사항, 추가 맥락 등을 자유롭게 기록.
(Phase 5 실행 중에도 계속 추가한다)

문서 3: 체크리스트 (checklist.md)

# 체크리스트: [작업명]

> 생성일: YYYY-MM-DD
> 마지막 업데이트: YYYY-MM-DD HH:MM
> 진행률: 0/N (0%)

## 진행 상황

### 1단계: [이름]
- [ ] 세부 작업 1-1
- [ ] 세부 작업 1-2

### 2단계: [이름]
- [ ] 세부 작업 2-1
- [ ] 세부 작업 2-2

### N단계: [이름]
- [ ] ...

## 완료 조건
이 작업이 "완료"로 간주되려면:
- [ ] 조건 1
- [ ] 조건 2

## 이슈 로그
| 발생 시점 | 이슈 | 해결 방법 | 상태 |
|-----------|------|-----------|------|
| (실행 중 기록) | | | |

Phase 3: 사용자 검토

3개 문서를 화면에 출력한 뒤, 사용자에게 검토를 요청한다.

출력 형식:

---
📋 계획서 (plan.md)
[계획서 내용]

📝 맥락 노트 (context.md)
[맥락노트 내용]

✅ 체크리스트 (checklist.md)
[체크리스트 내용]
---

3개 문서를 확인해주세요.
- 수정할 부분이 있으면 말씀해주세요.
- 승인하시면 파일 저장 후 실행합니다.

사용자가 수정을 요청하면 해당 문서를 수정하고 다시 보여준다. 사용자가 승인하면 Phase 4로 진행한다.

Phase 4: 문서 저장

승인된 3개 문서를 .plan/ 폴더에 저장한다.

저장 경로: [프로젝트 루트]/.plan/[작업명]-YYYY-MM-DD/

저장 후 확인 메시지:

문서 저장 완료:
  .plan/[작업명]-YYYY-MM-DD/plan.md
  .plan/[작업명]-YYYY-MM-DD/context.md
  .plan/[작업명]-YYYY-MM-DD/checklist.md

실행을 시작합니다.

Phase 5: 실행 + 실시간 업데이트

체크리스트를 보면서 단계별로 실행한다.

체크리스트 업데이트 규칙:

각 세부 작업이 완료되면 즉시 checklist.md를 Edit 도구로 업데이트한다.

체크 기호:

- [ ] → - [x] : 완료
- [ ] → - [!] : 이슈 발생 (이슈 로그에도 기록)
- [ ] → - [-] : 건너뜀/해당없음

진행률도 함께 업데이트:

> 진행률: 3/8 (37%)

맥락노트 업데이트 규칙:

실행 중 새로운 발견이나 결정 사항이 생기면 context.md의 "참고 메모" 또는 "결정 사항" 섹션에 추가한다.

완료 시:

모든 체크리스트 항목이 처리되면 최종 상태를 보고한다:

작업 완료!

진행률: 8/8 (100%)
  완료: 7건
  이슈: 1건 (이슈 로그 참조)
  건너뜀: 0건

결과 파일:
  .plan/[작업명]-YYYY-MM-DD/plan.md      (상태: 완료)
  .plan/[작업명]-YYYY-MM-DD/context.md   (업데이트됨)
  .plan/[작업명]-YYYY-MM-DD/checklist.md (100%)

핵심 원칙

코드 전에 문서 — 키보드에 손대기 전에 3문서부터 만든다
사용자 검토 필수 — AI가 혼자 해석해서 진행하지 않는다. 반드시 승인 후 실행
실시간 추적 — 체크리스트는 각 단계마다 즉시 업데이트
맥락 보존 — 작업 중 발견한 것은 맥락노트에 바로 기록
이슈 투명성 — 문제가 생기면 숨기지 않고 이슈 로그에 기록

주의사항

.plan/ 폴더가 없으면 자동 생성한다
같은 날 같은 작업명이 있으면 -2, -3 등 접미사를 붙인다
3문서는 작업 중 언제든 Read 도구로 다시 읽어서 맥락을 확인할 수 있다
Phase 5 중 사용자가 방향을 바꾸면, plan.md를 먼저 수정하고 checklist.md를 재구성한다