plan-first

/plan-first

A work methodology skill that first creates three documents before starting work, then executes after user review.

Metaphor: It is like creating a blueprint (plan) + specifications (context note) + schedule (checklist) before starting construction in architecture.

Storage Structure

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

Name the task briefly in Korean or English kebab-case. (e.g., 입금매칭-자동화, flip-send-system)

Execution Flow

Phase 1: Current State Analysis

When receiving a user request, before writing code, first explore sufficiently.

What to do:

Understand the request — Clarify what final deliverable the user wants
Explore the current state — Understand related files, code, and system status with Glob, Grep, and Read
Confirm scope — Clarify included/excluded items
Check dependencies — Check required APIs, libraries, and external systems

Spend enough time exploring. Do not rush.

Phase 2: Draft the 3 Documents

Based on the analysis results, first display the 3 documents on screen. Do not save the files yet. Output them in Markdown so the user can check them directly on screen.

Document 1: Plan (plan.md)

# 계획서: [작업명]

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

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

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

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

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

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

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

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

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

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

Document 2: Context Note (context.md)

# 맥락 노트: [작업명]

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

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

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

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

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

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

Document 3: Checklist (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: User Review

After displaying the 3 documents on screen, ask the user to review them.

Output Format:

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

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

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

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

If the user requests modifications, revise the relevant document and show it again. If the user approves, proceed to Phase 4.

Phase 4: Save Documents

Save the 3 approved documents in the .plan/ folder.

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

Confirmation message after saving:

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

실행을 시작합니다.

Phase 5: Execution + Real-Time Updates

Execute step by step while referring to the checklist.

Checklist Update Rules:

When each detailed task is completed, immediately checklist.mdupdate it with the Edit tool.

Check symbols:

- [ ] → - [x] : Completed
- [ ] → - [!] : Issue occurred (also record in the issue log)
- [ ] → - [-] : Skipped/Not applicable

Also update progress:

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

Context Note Update Rules:

If new discoveries or decisions arise during execution, add them to the context.md's "Reference Notes" or "Decisions" section.

Upon Completion:

When all checklist items have been handled, report the final status:

작업 완료!

진행률: 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%)

Core Principles

Documents before code — Before touching the keyboard, create the 3 documents first
User review required — AI does not interpret and proceed on its own. It must be executed after approval
Real-time tracking — The checklist is updated immediately at each step
Context preservation — Anything discovered during work is recorded right away in the context note
Issue transparency — If a problem arises, do not hide it; record it in the issue log

Precautions

.plan/ If the folder does not exist, it is created automatically
If there is a task with the same name on the same day, -2, -3 a suffix such as this is appended
The 3 documents can be read again at any time during work with the Read tool to check the context
If the user changes direction during Phase 5, modify plan.md first and restructure checklist.md