/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를 재구성한다