# Plan First

> 작업 시작 전 계획서·맥락노트·체크리스트 3문서를 먼저 만들고, 검토 후 실행하는 스킬. 건축의 설계도·시방서·공정표처럼 맥락을 잃지 않고 작업한다. "/plan", "/plan-first", "계획 세워줘", "작업 계획", "시작 전에 정리" 요청에 사용.

- Skill: `eoash/plan-first` (Agent Skill)
- Install (CLI): `npx skillmds@latest add eoash/plan-first`
- Raw SKILL.md: https://api.skillmd.com/api/skills/eoash/plan-first/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: eoash (https://skillmd.com/u/eoash)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/eoash/plan-first

---


# /plan-first

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

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

---

## 저장 구조

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

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

---

## 실행 흐름

### Phase 1: 현황 분석

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

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

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

### Phase 2: 3문서 초안 작성

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

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

```markdown
# 계획서: [작업명]

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

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

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

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

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

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

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

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

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

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

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

```markdown
# 맥락 노트: [작업명]

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

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

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

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

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

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

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

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

> 생성일: 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%)
```

---

## 핵심 원칙

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

---

## 주의사항

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