---
name: work-on-prd
description: >
  PRD를 읽고 인간과 대화하며 구현 계획을 함께 정의한다.
  계획 파일을 작성하고 인간의 "승인(Approved)" 확인을 받은 뒤에만 코드를 작성한다.
  절대로 승인 전에 코드를 한 줄도 짜지 않는다.
  "PRD 작업해줘", "PRD 보고 구현해줘", "이 PRD대로 진행해줘",
  "work-on-prd", PRD URL이나 파일 경로를 주며 작업 요청할 때 이 스킬을 사용할 것.
argument-hint: "<PRD 파일 경로 또는 노션 URL>"
allowed-tools: Read, Glob, Grep, Bash, Edit, Write, TaskCreate, TaskList, TaskUpdate, TaskGet, mcp__claude_ai_Notion__search, mcp__claude_ai_Notion__notion-update-page, mcp__claude_ai_Notion__fetch
---

## 입력

```
$ARGUMENTS
```

---

## 핵심 원칙

> **승인(Approved) 전에는 코드를 한 줄도 작성하지 않는다.**
> 이 스킬의 목적은 "좋은 계획을 인간과 함께 만드는 것"이다.
> 계획이 확정되고 인간이 명시적으로 승인해야만 구현 단계로 넘어간다.

---

## Phase 1 — PRD 파악 [STOP]

### 1-1. PRD 읽기

`$ARGUMENTS`로 전달된 PRD를 읽는다.

- 파일 경로면: `Read` 툴로 읽는다
- 노션 URL이면: `mcp__claude_ai_Notion__fetch`로 읽는다
- 인자가 없으면: 사용자에게 PRD 경로 또는 URL을 요청한다

### 1-2. PRD 구조 파악

읽은 PRD에서 아래 항목을 추출한다:

- **제목 / 코드**: PRD 식별자 (예: PRD-C)
- **목표**: 이 PRD가 해결하려는 문제
- **사용자 시나리오**: 실제 사용 흐름
- **제외 항목 / 제약 사항**: 범위 밖 내용
- **검증 기준**: 완료 판단 기준
- **구현 상세**: 명시된 구현 내용이 있으면 추출 (없으면 빈 칸)

### 1-3. PRD 요약 출력 [STOP]

아래 형식으로 출력한 뒤 반드시 멈추고 사용자의 응답을 기다린다:

```
## 📄 PRD 파악 완료: <PRD 제목>

### 목표
<한 줄 요약>

### 사용자 시나리오
<시나리오별 1줄 요약>

### 검증 기준
<체크리스트 항목들>

### 구현 상세
<PRD에 명시된 구현 내용 — 없으면 "명시된 구현 내용 없음">

---
이 PRD를 구현하려면 **구현 계획**을 먼저 작성해야 합니다.
계획 작성을 시작할까요? (네 / 아니오)
```

사용자가 "아니오"라고 하면 멈춘다.
사용자가 "네" 또는 시작 의사를 밝히면 Phase 2로 진행한다.

---

## Phase 2 — 코드베이스 탐색 & 대화형 계획 수립 [STOP]

### 2-1. 코드베이스 탐색

PRD의 목표와 검증 기준을 기반으로 관련 파일을 적극적으로 탐색한다:

- Glob/Grep을 사용해 관련 파일을 찾는다
- 핵심 파일들을 Read하여 기존 구조와 패턴을 파악한다
- 특히 다음을 파악한다:
  - PRD와 직접 관련된 화면/컴포넌트
  - 기존 유사한 패턴이 있는 파일
  - 영향받을 수 있는 주변 파일

### 2-2. 구현 방식 제안 및 대화

탐색 결과를 바탕으로 구현 방식을 제안하고 사용자와 대화한다.

아래 형식으로 출력한다:

```
## 🔍 코드베이스 탐색 결과

### 관련 파일
| 파일 | 역할 |
|------|------|
| <경로> | <이 파일이 PRD와 관련된 이유> |
...

### 구현 방식 제안

<구현 접근법을 구체적으로 설명>
- 어떤 파일을 수정/생성할지
- 어떤 패턴을 사용할지 (기존 코드 패턴 참조)
- 작업 단위를 어떻게 나눌지

### 결정이 필요한 사항

1. <결정 항목 1>
   - 옵션 A: <설명>
   - 옵션 B: <설명>
   - 추천: <이유와 함께 추천안>

2. <결정 항목 2>
   ...
```

각 결정 항목에 대해 사용자의 응답을 기다린다. [STOP]

사용자가 답변하면:
- 결정을 기록한다
- 추가 질문이 있으면 계속 묻는다
- 모든 결정이 내려지면 Phase 3으로 진행한다

미결 사항이 남아있으면 해소될 때까지 대화를 이어간다.

---

## Phase 3 — 계획 파일 작성 [STOP]

### 3-1. 계획 파일 작성

Phase 2의 탐색과 대화 결과를 바탕으로 계획 파일을 작성한다.

파일 위치: `dev/active/<prd-code>-<kebab-case-title>/plan.md`

계획 파일 형식:

```markdown
# <PRD 제목> 구현 계획

## PRD 요약
- **코드**: <PRD 코드>
- **목표**: <목표>
- **브랜치**: <브랜치명>

## 작업 목록

| # | 제목 | 영향 파일 | 예상 작업 |
|---|------|-----------|-----------|
| 1 | ... | ... | ... |
...

## 작업별 상세 계획

### 작업 1: <제목>

**목적**: <이 작업이 필요한 이유>

**구현 방식**:
<구체적인 구현 접근법 — 클래스/함수/패턴 수준>

**영향 파일**:
- `경로/파일명` — 수정/생성, <변경 내용>

**테스트 계획**:
- <이 작업에서 검증해야 할 시나리오 목록>
- 테스트 불필요 시: "UI 전용 / 단순 연결 작업으로 테스트 생략"

**주의사항**:
- <기존 코드와의 충돌, 사이드이펙트, 아키텍처 고려사항>

**결정된 사항**:
- <Phase 2 대화에서 결정된 내용>

---

### 작업 2: <제목>
...

## 검증 기준 (PRD 원문)
<PRD의 검증 기준 그대로>

> **검증 기준 작성 형식 가이드**
> - 코드 상태 검증 (import 없음, 필드 삭제 등): 체크리스트 형식
>   - `- [ ] AudioController.kt domain 인터페이스에 android.net.Uri import가 없다`
> - 런타임 동작 검증 (재생, UI 표시 등): Given/When/Then 형식
>   - `- [ ] Given 음악을 재생하면, Then 정상 재생된다`
> - 두 형식을 혼용해도 된다. 억지로 Given/When/Then으로 맞추지 않는다.

## 제외 항목
<PRD의 제외 항목 그대로>
```

### 3-2. 계획 검토 요청 [STOP]

계획 파일을 작성한 후 아래 형식으로 출력하고 반드시 멈춘다:

```
## 📋 구현 계획 작성 완료

계획 파일: `dev/active/<폴더명>/plan.md`

### 작업 요약
| # | 제목 | 영향 파일 수 |
|---|------|-------------|
| 1 | ... | ... |
...

---
계획을 검토해주세요.
수정이 필요하면 말씀해주세요.
계획대로 진행하려면 **"승인(Approved)"** 이라고 입력해주세요.
```

사용자가 수정을 요청하면:
- 계획 파일을 수정한다
- 수정된 내용을 설명하고 다시 [STOP]한다

사용자가 **"승인"** 또는 **"Approved"** 를 입력하면 Phase 4로 진행한다.
그 외의 응답은 수정 요청으로 간주하고 계획을 업데이트한다.

---

## Phase 4 — 구현 [승인 후에만 진행]

> 이 단계는 반드시 사용자의 "승인(Approved)" 확인 후에만 시작한다.

### 4-0. 브랜치 전환

계획 파일의 브랜치 정보를 확인한다.

**브랜치 값이 있는 경우:**

```bash
git branch --list <브랜치명>
```

- 브랜치가 이미 존재하면: `git checkout <브랜치명>`
- 브랜치가 없으면: `git checkout -b <브랜치명>`

**브랜치 값이 없는 경우:**

PRD 코드와 제목을 기반으로 제안한다.
형식: `feature/<prd-code>-<kebab-case-title>` (예: `feature/prd-c-persistent-mini-player`)

```
브랜치 정보가 없습니다. 아래 브랜치명으로 생성할까요?

  <제안 브랜치명>

"확인"으로 제안 브랜치를 사용하거나 직접 입력하세요.
```

[STOP] — 사용자 확인 후 브랜치 생성 및 전환.

### 4-1. Task 등록

계획 파일의 작업 목록을 Claude Code Task에 등록한다:

- TaskCreate 툴로 각 작업을 개별 Task로 생성
- Task 제목: `[N] <작업 제목>` 형식
- Task 설명: 계획 파일의 해당 작업 상세 내용
- 등록 후 TaskList로 확인

### 4-2. 작업 단위별 구현 루프

계획 파일의 작업 목록을 **하나씩** 순서대로 구현한다.

각 작업마다 아래 사이클을 반복한다:

---

**[2-1] 작업 안내**

```
---
### 🔨 [N/<전체>] <작업 제목>

**변경 내용 요약**
- <계획 파일 기반 2~4줄 요약>

**영향 파일**
| 파일 | 작업 |
|------|------|
| 경로/파일명 | 수정 / 생성 |
```

**[2-2] 구현**

- 계획 파일의 해당 작업 상세 계획을 바탕으로 구현한다
- 파일 수정 전 반드시 Read
- 코드 언급 시 `파일경로:라인번호` 형식으로 위치 명시
- 구현 완료 후 다음 단계로 이동 (멈추지 않음)

**[2-3] 테스트 작성**

`android:write-test` 스킬을 사용하여 테스트를 작성한다.

- 계획 파일의 **테스트 계획** 항목을 스킬에 전달한다
- 계획 파일에 "테스트 생략" 명시된 작업(UI 전용, 단순 연결 등)은 이 단계를 건너뛴다

**[2-4] 리뷰 + 검증**

`android:review-code` 스킬의 출력 형식을 따라 방금 구현한 변경사항을 리뷰하고, 연속으로 검증을 실행한다.

**리뷰:**

- git diff 기준으로 이번 작업 범위만 리뷰
- 문제가 없으면 바로 검증으로 진행
- 수정이 필요하면 [STOP]하고 아래 형식으로 보고:

```
⚠️ 리뷰 이슈 발견

- <파일경로:라인번호> — <문제 설명>
...

수정 후 진행할까요? 직접 수정하시겠다면 말씀해주세요.
```

사용자 확인 후 수정하고 재리뷰한다.

**검증:**

```bash
python scripts/check.py format
python scripts/check.py full
```

두 명령을 순서대로 실행하고 결과를 출력한다.

- **통과 시:** 바로 커밋으로 진행
- **실패 시:**

```
❌ 검증 실패

<실패 원인 요약>
<관련 파일:라인번호>

수정 후 다시 검증을 실행하겠습니다.
```

실패 원인 분석 후 수정하고 재검증. 2회 이상 실패 시 사용자에게 보고하고 판단을 요청한다.

**[2-5] 커밋**

`common:commit` 스킬을 사용하여 커밋한다.

커밋 완료 후 남은 작업이 있으면 바로 다음 작업(2-1)으로 진행:

```
✅ [N/<전체>] <작업 제목> 완료 — 다음 작업: <다음 작업 제목>
```

모든 작업 완료 시 Phase 5로 진행. [STOP]

---

## Phase 5 — 전체 완료

### 5-1. 전체 코드 리뷰

`android:review-code` 스킬을 사용하여 이번 PRD에서 변경된 전체 범위를 리뷰한다.

- `git diff main..HEAD` 기준으로 전체 변경사항 리뷰
- 수정이 필요한 사항이 있으면 수정 후 재리뷰
- 리뷰 통과 후 다음 단계로 진행

### 5-2. 노션 PRD 상태 업데이트 & 완료 처리 [STOP]

노션 PRD DB(`collection://e084c105-6138-4c91-8d02-3e953acd7611`)에서 해당 PRD 코드로 페이지를 검색하여 `상태` 속성을 `완료`로 업데이트한다.

계획 파일을 `dev/active/`에서 삭제하고, 완료 보고서를 `dev/report/<prd-code>-YYYY-MM-DD.md`에 작성한다.

보고서 형식:

```markdown
# <PRD 제목> 완료 보고서

## 검증 기준 체크
- [x] <PRD 검증 기준 항목들>

## 변경 파일 요약
- <파일 목록>

## AI가 제시한 선택지
| 결정 항목 | 제시한 옵션 | 선택한 것 | 선택 근거 |
|-----------|------------|-----------|-----------|
| <항목>    | A: ... / B: ... | A | <이유> |

## 결정되지 않고 AI가 직접 판단한 것
- <항목>: <판단 내용> — <이유>
```

보고서 작성 후 아래 형식으로 출력:

```
## PRD 전체 완료: <PRD 제목>

### 검증 기준 체크
- [x] <PRD 검증 기준 항목들>
...

### 변경 파일 요약
- <파일 목록>

✅ 노션 PRD DB 상태 → 완료
✅ 보고서 저장: dev/report/<파일명>

PR을 생성할까요?
```