---
name: planning-and-task-breakdown
description: "작업을 순서가 있는 작업으로 나눕니다. 스펙이나 명확한 요구사항이 있어 구현 가능한 작업으로 나눠야 할 때 사용하세요. 작업이 너무 커서 시작하기 어렵거나, 범위를 가늠해야 하거나, 병렬 작업이 가능할 때 사용하세요."
---

# Planning and Task Breakdown

## 개요

명시적인 인수 기준이 있는 작고 검증 가능한 작업으로 일을 분해하세요. 작업 분해가 잘되면 에이전트는 일을 안정적으로 끝내고, 잘못되면 엉킨 결과를 냅니다. 모든 작업은 한 번의 집중된 세션에서 구현하고, 테스트하고, 검증할 수 있을 만큼 작아야 합니다.

## 언제 사용하나

- 스펙이 있어 구현 가능한 단위로 나눠야 할 때
- 작업이 너무 크거나 모호해서 시작하기 어려울 때
- 여러 에이전트나 세션에 일을 병렬로 나눠야 할 때
- 사람에게 범위를 전달해야 할 때
- 구현 순서가 분명하지 않을 때

**사용하지 말아야 할 때:** 범위가 분명한 파일 하나짜리 변경, 또는 스펙에 이미 잘 정의된 작업이 있을 때.

## 계획 프로세스

### 1단계: 계획 모드로 들어가기

코드를 쓰기 전에 읽기 전용으로 작업하세요.

- 스펙과 관련 코드베이스 부분을 읽으세요
- 기존 패턴과 관례를 파악하세요
- 컴포넌트 사이의 의존성을 그리세요
- 위험과 미지수를 적으세요

**계획 중에는 코드를 쓰지 마세요.** 산출물은 `tasks/plan.md`에 저장하는 계획 문서와, 작업 목록 대상에 기록하는 작업 목록입니다 (출력 파일을 보세요. 기본값은 `tasks/todo.md`). 구현이 아닙니다.

### 2단계: 의존성 그래프 파악

무엇이 무엇에 의존하는지 그리세요.

```
데이터베이스 스키마
    │
    ├── API 모델/타입
    │       │
    │       ├── API 엔드포인트
    │       │       │
    │       │       └── 프론트엔드 API 클라이언트
    │       │               │
    │       │               └── UI 컴포넌트
    │       │
    │       └── 검증 로직
    │
    └── 시드 데이터 / 마이그레이션
```

구현 순서는 의존성 그래프를 아래에서 위로 따릅니다. 기반을 먼저 만드세요.

### 3단계: 수직으로 자르기

데이터베이스 전부, 그다음 API 전부, 그다음 UI 전부를 만들지 마세요. 한 번에 완전한 기능 경로를 하나씩 만드세요.

**나쁨 (수평 슬라이스):**
```
작업 1: 데이터베이스 스키마 전체를 만든다
작업 2: API 엔드포인트 전부를 만든다
작업 3: UI 컴포넌트 전부를 만든다
작업 4: 모든 것을 연결한다
```

**좋음 (수직 슬라이스):**
```
작업 1: 사용자가 계정을 만들 수 있다 (가입용 스키마 + API + UI)
작업 2: 사용자가 로그인할 수 있다 (인증 스키마 + API + 로그인 UI)
작업 3: 사용자가 작업을 만들 수 있다 (작업 스키마 + API + 생성 UI)
작업 4: 사용자가 작업 목록을 볼 수 있다 (쿼리 + API + 목록 UI)
```

각 수직 슬라이스는 동작하고 테스트 가능한 기능을 전달합니다.

### 4단계: 작업 작성

각 작업은 이 구조를 따릅니다. 마크다운 작업 목록에 두든, 외부 트래커의 항목으로 두든 같습니다 (출력 파일을 보세요).

```markdown
## 작업 [N]: [짧은 설명 제목]

**설명:** 이 작업이 무엇을 이루는지 한 단락으로 설명합니다.

**인수 기준:**
- [ ] [구체적이고 테스트 가능한 조건]
- [ ] [구체적이고 테스트 가능한 조건]

**검증:**
- [ ] 테스트 통과: [저장소의 집중 테스트 명령]
- [ ] 빌드 성공: [저장소의 빌드 명령]
- [ ] 수동 확인: [무엇을 확인할지 설명]

**의존성:** [이 작업이 의존하는 작업 번호, 또는 "없음"]

**건드릴 가능성이 있는 파일:**
- `src/path/to/file.ts`
- `tests/path/to/test.ts`

**예상 범위:** [작음: 파일 1-2개 | 중간: 파일 3-5개 | 큼: 파일 5개 이상]
```

### 5단계: 순서와 체크포인트

작업이 다음을 만족하도록 배열하세요.

1. 의존성이 충족된다 (기반을 먼저 만든다)
2. 각 작업이 시스템을 동작하는 상태로 남긴다
3. 검증 체크포인트가 작업 2-3개마다 온다
4. 위험이 큰 작업이 앞에 온다 (빨리 실패한다)

작업 목록 대상에 명시적인 체크포인트를 추가하세요.

```markdown
## 체크포인트: 작업 1-3 이후
- [ ] 모든 테스트가 통과한다
- [ ] 애플리케이션이 오류 없이 빌드된다
- [ ] 핵심 사용자 흐름이 끝까지 동작한다
- [ ] 진행하기 전에 사람과 함께 리뷰한다
```

## 작업 크기 지침

| 크기 | 파일 | 범위 | 예시 |
|------|-------|-------|---------|
| **XS** | 1 | 함수 하나 또는 설정 변경 | 검증 규칙 추가 |
| **S** | 1-2 | 컴포넌트 하나 또는 엔드포인트 | 새 API 엔드포인트 추가 |
| **M** | 3-5 | 기능 슬라이스 하나 | 사용자 가입 흐름 |
| **L** | 5-8 | 여러 컴포넌트에 걸친 기능 | 필터와 페이지네이션이 있는 검색 |
| **XL** | 8+ | **너무 큼. 더 나누세요** | — |

작업이 L 이상이면 더 작은 작업으로 나누세요. 에이전트는 S와 M 작업에서 가장 잘합니다.

**작업을 더 나눌 때:**
- 집중된 세션이 하나보다 더 필요할 때 (에이전트 작업으로 대략 2시간 이상)
- 인수 기준을 글머리 기호 3개 이하로 적을 수 없을 때
- 서로 독립적인 하위 시스템을 둘 이상 건드릴 때 (예: 인증과 결제)
- 작업 제목에 "and"(그리고)를 쓰게 될 때 (작업이 두 개라는 신호입니다)

## 출력 파일

- **계획 문서:** 구현 계획을 `tasks/plan.md`에 저장하세요. 이것은 항상 마크다운 파일입니다. 설계 결정, 위험, 열린 질문은 트래커 이슈 하나에 깨끗하게 대응하지 않습니다.
- **작업 목록:** 각 작업을 **작업 목록 대상**(아래 정의)에 기록하세요.

`tasks/` 디렉터리가 없으면 만드세요.

**끝나지 않은 계획을 덮어쓰지 마세요.** `tasks/plan.md`나 `tasks/todo.md`를 쓰기 전에, 파일이 이미 있고 아직 체크되지 않은 작업을 담고 있는지 확인하세요.

- 같은 일을 다시 계획하는 경우 (사용자가 이 계획을 고치거나 확장해 달라고 한 경우) → 기존 파일을 그 자리에서 업데이트하세요.
- 다른 일인 경우 → **멈추고 물어보세요.** 체크되지 않은 작업이 다른 세션에서 빌드 중일 수 있습니다. 기존 파일을 마음대로 삭제하거나, 덮어쓰거나, 이름을 바꾸지 마세요. 충돌을 제시하고 사용자가 결정하게 하세요 (이전 계획을 먼저 끝내기, 명시적으로 버리기, 또는 새 계획을 어디에 둘지 알려 주기).

같은 규칙이 외부 작업 목록 대상에도 적용됩니다. 새 항목을 넣을 자리를 만들려고 다른 계획의 열린 트래커 항목을 일괄로 닫거나 삭제하지 마세요.

### 작업 목록 대상

작업 목록 대상은 작업과 체크포인트를 기록하는 곳입니다. 여기서 한 번만 정의합니다. 이 스킬의 다른 모든 참조는 이것을 따릅니다.

- **기본값: `tasks/todo.md`의 체크리스트형 마크다운 파일.** `/build` 명령과 그 뒤의 도구가 기대하는 관례입니다. 프로젝트가 달리 말하지 않는 한 이것을 사용하세요.
- **외부 트래커:** 프로젝트의 에이전트 규칙(`CLAUDE.md`, `AGENTS.md` 등)이나 사용자가 이슈 트래커를 지정하면 (예: GitHub Issues, Jira, Linear, `bd`/beads) `tasks/todo.md`를 쓰는 대신 작업마다 트래커 항목을 하나씩 만드세요. 4단계 구조를 트래커 필드에 대응시키세요. 인수 기준과 검증 단계는 항목 본문에, 의존성은 트래커의 연결 방식으로 (`bd dep add`, "blocked by" 등). 5단계 체크포인트도 트래커 항목으로 기록하거나, 트래커에 자연스러운 대응이 없으면 계획 문서의 체크리스트로 기록하세요.

외부 트래커를 쓸 때는 `tasks/plan.md`에 그 사실을 적으세요 (예: "작업은 Linear 프로젝트 FOO에서 추적합니다"). 이후 단계와 미래 세션이 어디를 볼지 알게 됩니다. 계획 문서의 작업 목록 절은 체크리스트를 복제하지 말고, 트래커 항목 ID나 링크의 순서 있는 색인으로 유지하세요.

## 계획 문서 템플릿

```markdown
# 구현 계획: [기능/프로젝트 이름]

## 개요
[만들려는 것을 한 단락으로 요약]

## 아키텍처 결정
- [핵심 결정 1과 근거]
- [핵심 결정 2와 근거]

## 작업 목록

### 단계 1: 기반
- [ ] 작업 1: ...
- [ ] 작업 2: ...

### 체크포인트: 기반
- [ ] 테스트 통과, 빌드가 깨끗함

### 단계 2: 핵심 기능
- [ ] 작업 3: ...
- [ ] 작업 4: ...

### 체크포인트: 핵심 기능
- [ ] 엔드투엔드 흐름이 동작함

### 단계 3: 다듬기
- [ ] 작업 5: ...
- [ ] 작업 6: ...

### 체크포인트: 완료
- [ ] 모든 인수 기준을 충족함
- [ ] 리뷰 준비가 됨

## 위험과 완화
| 위험 | 영향 | 완화 |
|------|------|------|
| [위험] | [높음/중간/낮음] | [전략] |

## 열린 질문
- [사람의 입력이 필요한 질문]
```

작업이 외부 트래커에 있으면, 위의 작업 목록 절을 체크리스트 복제 대신 트래커 항목 ID나 링크의 순서 있는 색인으로 유지하세요.

## 병렬화 기회

여러 에이전트나 세션을 쓸 수 있을 때:

- **병렬화해도 안전함:** 독립적인 기능 슬라이스, 이미 구현된 기능의 테스트, 문서
- **반드시 순차적으로:** 데이터베이스 마이그레이션, 공유 상태 변경, 의존성 사슬
- **조율이 필요함:** API 계약을 공유하는 기능 (먼저 계약을 정의한 다음 병렬화하세요)

## 흔한 합리화

| 합리화 | 현실 |
|---|---|
| "하다가 보면 알게 된다" | 그렇게 하면 엉킨 결과와 재작업으로 끝납니다. 10분의 계획이 몇 시간을 아낍니다. |
| "작업은 뻔하다" | 그래도 적으세요. 명시적인 작업이 숨은 의존성과 놓친 엣지 케이스를 드러냅니다. |
| "계획은 오버헤드다" | 계획 자체가 작업입니다. 계획 없는 구현은 그저 타이핑일 뿐입니다. |
| "전부 머리에 담을 수 있다" | 컨텍스트 창은 유한합니다. 글로 된 계획은 세션 경계와 압축을 견딥니다. |
| "예전 `tasks/plan.md`는 낡았으니 그냥 바꾸겠다" | 체크되지 않은 작업이 다른 세션에서 빌드 중일 수 있습니다. 덮어쓰면 다른 곳에는 없는 작업 상태가 사라집니다. 멈추고 물어보세요. |

## 레드 플래그

- 글로 된 작업 목록 없이 구현을 시작함
- 다른 일의 체크되지 않은 작업이 남아 있는 `tasks/plan.md`나 `tasks/todo.md`를 묻지 않고 덮어씀
- 프로젝트가 외부 트래커를 지정했는데 `tasks/todo.md`를 작성함 (또는 양쪽에 작업을 흩뿌림)
- 인수 기준 없이 "기능을 구현한다"라고만 적힌 작업
- 계획에 검증 단계가 없음
- 모든 작업이 XL 크기임
- 작업 사이에 체크포인트가 없음
- 의존성 순서를 고려하지 않음

## 검증

구현을 시작하기 전에 확인하세요.

- [ ] 모든 작업에 인수 기준이 있다
- [ ] 모든 작업에 검증 단계가 있다
- [ ] 작업 의존성을 찾고 올바르게 정렬했다
- [ ] 작업을 작업 목록 대상에 기록했다 (기본값 `tasks/todo.md`)
- [ ] 사용자의 명시적 확인 없이 기존의 미완료 계획을 덮어쓰지 않았다
- [ ] 어떤 작업도 파일을 약 5개보다 많이 건드리지 않는다
- [ ] 주요 단계 사이에 체크포인트가 있다
- [ ] 사람이 계획을 리뷰하고 승인했다

## 참고

인수 기준은 작업마다 있으며 "올바른 것을 만들었는가?"에 답합니다. 이것은 프로젝트 전체의 완료 정의 위에 있습니다. 완료 정의는 작업이 완료로 인정되기 전에 모든 작업이 넘어야 하는 상시 기준입니다. `../../references/definition-of-done.md`를 보세요.