PRP 계획

언제 쓰나

새로운 기능 구현을 위해 기존 코드베이스 분석 및 패턴 추출을 통한 상세 계획이 필요할 때.

---
description: 코드베이스 분석 및 패턴 추출을 통해 포괄적인 기능 구현 계획을 생성합니다.
argument-hint: <기능 설명 | path/to/prd.md>
---

> Wirasm의 PRPs-agentic-eng에서 각색되었습니다. PRP 워크플로 시리즈의 일부입니다.

# PRP 계획

단일 패스로 기능을 구현하는 데 필요한 모든 코드베이스 패턴, 규칙 및 컨텍스트를 담은 상세하고 독립적인 구현 계획을 생성합니다.

**핵심 철학**: 훌륭한 계획은 추가 질문 없이 구현하는 데 필요한 모든 것을 포함합니다. 모든 패턴, 모든 규칙, 모든 예상치 못한 문제 — 한 번 캡처하여 전체적으로 참조합니다.

**황금률**: 구현 중에 코드베이스를 검색해야 할 경우, 그 지식을 지금 계획에 캡처하세요.

---

## Phase 0 — DETECT (감지)

`$ARGUMENTS`에서 입력 유형을 결정합니다.

| 입력 패턴 | 감지 | 조치 |
|--- |--- |--- |
| `.prd.md`로 끝나는 경로 | PRD 파일 경로 | PRD를 파싱하고 다음 보류 중인 단계를 찾습니다. |
| "Implementation Phases"를 포함하는 `.md` 경로 | PRD와 유사한 문서 | 단계를 파싱하고 다음 보류 중인 단계를 찾습니다. |
| 다른 모든 파일 경로 | 참조 파일 | 컨텍스트를 위해 파일을 읽고 자유 형식으로 처리합니다. |
| 자유 형식 텍스트 | 기능 설명 | Phase 1으로 직접 진행합니다. |
| 비어 있음 / 공백 | 입력 없음 | 사용자에게 어떤 기능을 계획할지 묻습니다. |

### PRD 파싱 (입력이 PRD인 경우)

1.  `cat "$PRD_PATH"`를 사용하여 PRD 파일을 읽습니다.
2.  **Implementation Phases** 섹션을 파싱합니다.
3.  상태별 단계를 찾습니다:
    -   `pending` 단계를 찾습니다.
    -   의존성 체인을 확인합니다 (단계는 이전 단계가 `complete`되어야 할 수 있습니다).
    -   **다음으로 진행할 수 있는 보류 중인 단계**를 선택합니다.
4.  선택된 단계에서 다음을 추출합니다:
    -   단계 이름 및 설명
    -   승인 기준
    -   이전 단계에 대한 의존성
    -   모든 범위 노트 또는 제약 조건
5.  단계 설명을 계획할 기능으로 사용합니다.

남아있는 보류 중인 단계가 없으면 모든 단계가 complete되었음을 보고합니다.

---

## Phase 1 — PARSE (파싱)

기능 요구사항을 추출하고 명확히 합니다.

### 기능 이해

입력 (PRD 단계 또는 자유 형식 설명)에서 다음을 식별합니다:

-   **무엇**을 구축하는가 (구체적인 결과물)
-   **왜** 중요한가 (사용자 가치)
-   **누가** 사용하는가 (대상 사용자/시스템)
-   **어디에** 적합한가 (코드베이스의 어느 부분)

### 사용자 스토리

다음과 같이 형식화합니다:
```
As a [type of user],
I want [capability],
So that [benefit].
```

### 복잡도 평가

| 수준 | 지표 | 일반적인 범위 |
|--- |--- |--- |
| **Small** | 단일 파일, 독립적인 변경, 새로운 의존성 없음 | 1-3개 파일, <100줄 |
| **Medium** | 여러 파일, 기존 패턴 따름, 사소한 새 개념 | 3-10개 파일, 100-500줄 |
| **Large** | 교차 문제, 새로운 패턴, 외부 통합 | 10개 이상 파일, 500+줄 |
| **XL** | 아키텍처 변경, 새 하위 시스템, 마이그레이션 필요 | 20개 이상 파일, 분할 고려 |

### 모호성 게이트

다음 중 하나라도 불분명하면, 진행하기 전에 **STOP하고 사용자에게 질문하세요**:

-   핵심 결과물이 모호함
-   성공 기준이 정의되지 않음
-   여러 가지 유효한 해석이 존재함
-   기술적 접근 방식에 주요 미확인 사항이 있음

추측하지 마세요. 질문하세요. 가정에 기반한 계획은 구현 중에 실패합니다.

---

## Phase 2 — EXPLORE (탐색)

심층적인 코드베이스 정보를 수집합니다. 아래 각 범주에 대해 코드베이스를 직접 검색합니다.

### 코드베이스 검색 (8개 범주)

grep, find, 파일 읽기를 사용하여 각 범주에 대해 검색합니다:

1.  **유사한 구현** — 계획된 기능과 유사한 기존 기능을 찾습니다. 유사한 패턴, 엔드포인트, 구성 요소 또는 모듈을 찾습니다.

2.  **명명 규칙** — 코드베이스의 관련 영역에서 파일, 함수, 변수, 클래스 및 익스포트가 어떻게 명명되는지 식별합니다.

3.  **오류 처리** — 유사한 코드 경로에서 오류가 어떻게 포착되고, 전파되고, 기록되고, 사용자에게 반환되는지 찾습니다.

4.  **로깅 패턴** — 무엇이, 어떤 수준으로, 어떤 형식으로 기록되는지 식별합니다.

5.  **타입 정의** — 관련 타입, 인터페이스, 스키마 및 조직 방식을 찾습니다.

6.  **테스트 패턴** — 유사한 기능이 어떻게 테스트되는지 찾습니다. 테스트 파일 위치, 명명, 설정/해체 패턴 및 어설션 스타일을 기록합니다.

7.  **구성** — 관련 구성 파일, 환경 변수 및 기능 플래그를 찾습니다.

8.  **의존성** — 유사한 기능에서 사용되는 패키지, 임포트 및 내부 모듈을 식별합니다.

### 코드베이스 분석 (5가지 추적)

관련 파일을 읽고 다음을 추적합니다:

1.  **진입점** — 요청/액션이 시스템에 어떻게 진입하여 수정할 영역에 도달하는가?
2.  **데이터 흐름** — 데이터가 관련 코드 경로를 통해 어떻게 이동하는가?
3.  **상태 변경** — 어떤 상태가 어디에서 수정되는가?
4.  **계약** — 어떤 인터페이스, API 또는 프로토콜이 준수되어야 하는가?
5.  **패턴** — 어떤 아키텍처 패턴이 사용되는가 (repository, service, controller 등)?

### 통합 검색 테이블

발견한 내용을 단일 참조로 컴파일합니다:

| 범주 | 파일:줄 | 패턴 | 핵심 스니펫 |
|--- |--- |--- |--- |
| Naming | `src/services/userService.ts:1-5` | camelCase services, PascalCase types | `export class UserService` |
| Error | `src/middleware/errorHandler.ts:10-25` | Custom AppError class | `throw new AppError(...)` |
| ... | ... | ... | ... |

---

## Phase 3 — RESEARCH (연구)

기능이 외부 라이브러리, API 또는 익숙하지 않은 기술을 포함하는 경우:

1.  공식 문서를 웹에서 검색합니다.
2.  사용 예시 및 모범 사례를 찾습니다.
3.  버전별 예상치 못한 문제를 식별합니다.

각 발견 사항은 다음과 같이 형식화합니다:

```
KEY_INSIGHT: [학습한 내용]
APPLIES_TO: [이 계획의 어느 부분에 영향을 미치는지]
GOTCHA: [모든 경고 또는 버전별 문제]
```

기능이 잘 이해된 내부 패턴만 사용하는 경우, 이 단계를 건너뛰고 다음과 같이 메모합니다: "외부 연구 필요 없음 — 기능은 확립된 내부 패턴을 사용합니다."

---

## Phase 4 — DESIGN (설계)

### UX 변환 (해당하는 경우)

전후 사용자 경험을 문서화합니다:

**이전:**
```
┌─────────────────────────────┐
│  [현재 사용자 경험]  │
│  현재 흐름,                 │
│  사용자가 보고/하는 것을 보여줍니다.    │
└─────────────────────────────┘
```

**이후:**
```
┌─────────────────────────────┐
│  [새로운 사용자 경험]      │
│  개선된 흐름,                 │
│  사용자에게 변경되는 사항을 보여줍니다. │
└─────────────────────────────┘
```

### 상호작용 변경

| 접점 | 이전 | 이후 | 참고 |
|--- |--- |--- |--- |
| ... | ... | ... | ... |

기능이 UX 변경이 없는 순수한 백엔드/내부인 경우, 다음과 같이 메모합니다: "내부 변경 — 사용자 대면 UX 변환 없음."

---

## Phase 5 — ARCHITECT (아키텍처)

### 전략적 설계

구현 접근 방식을 정의합니다:

-   **접근 방식**: 고수준 전략 (예: "기존 저장소 패턴을 따르는 새 서비스 계층 추가")
-   **고려된 대안**: 어떤 다른 접근 방식이 평가되었고 왜 거부되었는지
-   **범위**: 구축될 것의 구체적인 경계
-   **미구축**: 범위 외 항목의 명시적 목록 (구현 중 범위 확장을 방지)

---

## Phase 6 — GENERATE (생성)

아래 템플릿을 사용하여 전체 계획 문서를 작성합니다. `.claude/PRPs/plans/{kebab-case-feature-name}.plan.md`에 저장합니다.

디렉토리가 없으면 생성합니다:
```bash
mkdir -p .claude/PRPs/plans
```

### 계획 템플릿

````markdown
# 계획: [기능 이름]

## 요약
[2-3문장 개요]

## 사용자 스토리
[사용자]로서, [기능]을 원합니다. [이점]을 위해서.

## 문제 → 해결
[현재 상태] → [원하는 상태]

## 메타데이터
- **Complexity**: [Small | Medium | Large | XL]
- **Source PRD**: [경로 또는 "N/A"]
- **PRD Phase**: [단계 이름 또는 "N/A"]
- **Estimated Files**: [개수]

---

## UX 설계

### 이전
[ASCII 다이어그램 또는 "N/A — 내부 변경"]

### 이후
[ASCII 다이어그램 또는 "N/A — 내부 변경"]

### 상호작용 변경
| 접점 | 이전 | 이후 | 참고 |
|---|---|---|---|

---

## 필수 읽기

구현 전에 반드시 읽어야 할 파일:

| 우선순위 | 파일 | 줄 | 이유 |
|---|---|---|---|
| P0 (매우 중요) | `path/to/file` | 1-50 | 따라야 할 핵심 패턴 |
| P1 (중요) | `path/to/file` | 10-30 | 관련 타입 |
| P2 (참조) | `path/to/file` | all | 유사한 구현 |

## 외부 문서

| 주제 | 출처 | 핵심 내용 |
|---|---|---|---|
| ... | ... | ... |

---

## 따를 패턴

코드베이스에서 발견된 코드 패턴입니다. 이들을 정확히 따르세요.

### NAMING_CONVENTION
// SOURCE: [파일:줄]
[명명 패턴을 보여주는 실제 코드 스니펫]

### ERROR_HANDLING
// SOURCE: [파일:줄]
[오류 처리를 보여주는 실제 코드 스니펫]

### LOGGING_PATTERN
// SOURCE: [파일:줄]
[로깅을 보여주는 실제 코드 스니펫]

### REPOSITORY_PATTERN
// SOURCE: [파일:줄]
[데이터 액세스를 보여주는 실제 코드 스니펫]

### SERVICE_PATTERN
// SOURCE: [파일:줄]
[서비스 계층을 보여주는 실제 코드 스니펫]

### TEST_STRUCTURE
// SOURCE: [파일:줄]
[테스트 설정을 보여주는 실제 코드 스니펫]

---

## 변경할 파일

| 파일 | 조치 | 정당화 |
|---|---|---|---|
| `path/to/file.ts` | CREATE | 기능 위한 새 서비스 |
| `path/to/existing.ts` | UPDATE | 새 메서드 추가 |

## 미구축

- [범위 외 명시적 항목 1]
- [범위 외 명시적 항목 2]

---

## 단계별 작업

### 작업 1: [이름]
- **ACTION**: [할 일]
- **IMPLEMENT**: [작성할 특정 코드/로직]
- **MIRROR**: [따를 '따를 패턴' 섹션의 패턴]
- **IMPORTS**: [필수 임포트]
- **GOTCHA**: [피해야 할 알려진 함정]
- **VALIDATE**: [이 작업이 올바른지 확인하는 방법]

### 작업 2: [이름]
- **ACTION**: ...
- **IMPLEMENT**: ...
- **MIRROR**: ...
- **IMPORTS**: ...
- **GOTCHA**: ...
- **VALIDATE**: ...

[모든 작업에 대해 계속...]

---

## 테스트 전략

### 단위 테스트

| 테스트 | 입력 | 예상 출력 | 엣지 케이스? |
|---|---|---|---|
| ... | ... | ... | ... |

### 엣지 케이스 체크리스트
- [ ] 빈 입력
- [ ] 최대 크기 입력
- [ ] 유효하지 않은 타입
- [ ] 동시 액세스
- [ ] 네트워크 오류 (해당하는 경우)
- [ ] 권한 거부

---

## 유효성 검사 명령

### 정적 분석
```bash
# Run type checker
[project-specific type check command]
```
EXPECT: 타입 오류 없음

### 단위 테스트
```bash
# Run tests for affected area
[project-specific test command]
```
EXPECT: 모든 테스트 통과

### 전체 테스트 스위트
```bash
# Run complete test suite
[project-specific full test command]
```
EXPECT: 회귀 없음

### 데이터베이스 유효성 검사 (해당하는 경우)
```bash
# Verify schema/migrations
[project-specific db command]
```
EXPECT: 스키마 최신 상태

### 브라우저 유효성 검사 (해당하는 경우)
```bash
# Start dev server and verify
[project-specific dev server command]
```
EXPECT: 기능이 의도대로 작동함

### 수동 유효성 검사
- [ ] [단계별 수동 확인 체크리스트]

---

## 승인 기준
- [ ] 모든 작업 완료
- [ ] 모든 유효성 검사 명령 통과
- [ ] 테스트 작성 및 통과
- [ ] 타입 오류 없음
- [ ] 린트 오류 없음
- [ ] UX 설계와 일치 (해당하는 경우)

## 완료 체크리스트
- [ ] 코드가 발견된 패턴을 따름
- [ ] 오류 처리가 코드베이스 스타일과 일치함
- [ ] 로깅이 코드베이스 규칙을 따름
- [ ] 테스트가 테스트 패턴을 따름
- [ ] 하드코딩된 값 없음
- [ ] 문서 업데이트됨 (필요한 경우)
- [ ] 불필요한 범위 추가 없음
- [ ] 독립적 — 구현 중 질문 필요 없음

## 위험 요소
| 위험 | 가능성 | 영향 | 완화 |
|---|---|---|---|
| ... | ... | ... | ... |

## 참고 사항
[모든 추가 컨텍스트, 결정 또는 관찰 사항]
````

---

## 출력

### 계획 저장

생성된 계획을 다음 위치에 작성합니다:
```
.claude/PRPs/plans/{kebab-case-feature-name}.plan.md
```

### PRD 업데이트 (입력이 PRD인 경우)

이 계획이 PRD 단계에서 생성된 경우:
1.  단계 상태를 `pending`에서 `in-progress`로 업데이트합니다.
2.  계획 파일 경로를 단계에 참조로 추가합니다.

### 사용자에게 보고

```
## 계획 생성됨

- **File**: .claude/PRPs/plans/{kebab-case-feature-name}.plan.md
- **Source PRD**: [경로 또는 "N/A"]
- **Phase**: [단계 이름 또는 "standalone"]
- **Complexity**: [수준]
- **Scope**: [N개 파일, M개 작업]
- **Key Patterns**: [상위 3개 발견된 패턴]
- **External Research**: [연구된 주제 또는 "필요 없음"]
- **Risks**: [상위 위험 또는 "식별된 위험 없음"]
- **Confidence Score**: [1-10] — 단일 패스 구현 가능성

> 다음 단계: `/prp-implement .claude/PRPs/plans/{name}.plan.md`를 실행하여 이 계획을 실행하세요.
```

---

## 검증

최종 확정 전에 다음 체크리스트에 대해 계획을 검증합니다:

### 컨텍스트 완전성
- [ ] 모든 관련 파일 발견 및 문서화됨
- [ ] 명명 규칙이 예시와 함께 캡처됨
- [ ] 오류 처리 패턴이 문서화됨
- [ ] 테스트 패턴 식별됨
- [ ] 의존성 목록화됨

### 구현 준비 상태
- [ ] 모든 작업에 ACTION, IMPLEMENT, MIRROR 및 VALIDATE가 있음
- [ ] 어떤 작업도 추가적인 코드베이스 검색을 요구하지 않음
- [ ] 임포트 경로가 지정됨
- [ ] GOTCHA가 해당하는 경우 문서화됨

### 패턴 충실도
- [ ] 코드 스니펫은 실제 코드베이스 예시임 (고안된 것이 아님)
- [ ] SOURCE 참조는 실제 파일 및 줄 번호를 가리킴
- [ ] 패턴은 명명, 오류, 로깅, 데이터 액세스 및 테스트를 포함함
- [ ] 새로운 코드가 기존 코드와 구별할 수 없어야 함

### 유효성 검사 범위
- [ ] 정적 분석 명령 지정됨
- [ ] 테스트 명령 지정됨
- [ ] 빌드 유효성 검사 포함됨

### UX 명확성
- [ ] 전후 상태 문서화됨 (또는 N/A로 표시됨)
- [ ] 상호작용 변경 목록화됨
- [ ] UX의 엣지 케이스 식별됨

### 사전 지식 없음 테스트
이 코드베이스에 익숙하지 않은 개발자는 이 계획만 사용하여 코드베이스를 검색하거나 질문하지 않고 기능을 구현할 수 있어야 합니다. 그렇지 않은 경우, 누락된 컨텍스트를 추가하세요.

---

## 다음 단계

- `/prp-implement <plan-path>`를 실행하여 이 계획을 실행하세요.
- `/plan`을 실행하여 아티팩트 없이 빠른 대화형 계획을 수립하세요.
- 범위가 불분명한 경우 먼저 `/prp-prd`를 실행하여 PRD를 생성하세요.

1. 1

   SKILL.md 저장

   아래 버튼으로 복사 → 다음 경로로 저장.

   SKILL.md 복사

   macOSLinuxWindows

   ~/.claude/skills/everything-claude-code-prp/SKILL.md경로 복사
2. 2

   호출

   Claude Code 채팅창에서 자연어로 부르면 자동 발동:

   예) 새로운 기능 구현을 위해 기존 코드베이스 분석 및 패턴 추출을 통한 상세 계획이 필요할 때

   트리거가 안 잡히면 SKILL.md의 description 줄에 더 구체적인 한국어 키워드를 추가해보세요.