---
description: コードベース分析とパターン抽出を伴う包括的な機能実装計画を作成する
argument-hint: <機能の説明 | path/to/prd.md>
---

> PRPs-agentic-eng by Wirasm から適応。PRPワークフローシリーズの一部。

# PRP Plan

単一パスで機能を実装するために必要なすべてのコードベースパターン、規約、コンテキストを捉えた詳細で自己完結型の実装計画を作成します。

**基本理念**: 優れた計画には、追加の質問なしに実装するために必要なすべてが含まれています。すべてのパターン、すべての規約、すべての注意点が一度捕捉され、全体を通して参照されます。

**黄金ルール**: 実装中にコードベースを検索する必要がある場合、その知識を今すぐ計画に取り込んでください。

---

## フェーズ 0 — DETECT（検出）

`$ARGUMENTS` から入力タイプを判定します:

| 入力パターン | 検出 | アクション |
|---|---|---|
| `.prd.md` で終わるパス | PRDへのファイルパス | PRDを解析し、次の保留中のフェーズを見つける |
| "Implementation Phases" を含む `.md` へのパス | PRDに類似した文書 | フェーズを解析し、次の保留中を見つける |
| その他のファイルへのパス | 参照ファイル | コンテキストのためにファイルを読み、自由形式として扱う |
| 自由形式テキスト | 機能の説明 | フェーズ1に直接進む |
| 空白 / ブランク | 入力なし | ユーザーに計画する機能を尋ねる |

### PRD解析（入力がPRDの場合）

1. `cat "$PRD_PATH"` でPRDファイルを読み込む
2. **Implementation Phases** セクションを解析する
3. ステータスでフェーズを検索する:
   - `pending`（保留中）のフェーズを探す
   - 依存関係チェーンを確認する（あるフェーズは先行フェーズが `complete` であることに依存する場合がある）
   - **次の適格な保留中フェーズ** を選択する
4. 選択したフェーズから以下を抽出する:
   - フェーズ名と説明
   - 受け入れ基準
   - 先行フェーズへの依存関係
   - スコープに関する注記や制約
5. フェーズの説明を計画する機能として使用する

保留中のフェーズが残っていない場合、すべてのフェーズが完了していることを報告します。

---

## フェーズ 1 — PARSE（解析）

機能要件を抽出し明確化します。

### 機能の理解

入力（PRDフェーズまたは自由形式の説明）から以下を特定します:

- **何を** 構築するのか（具体的な成果物）
- **なぜ** 重要なのか（ユーザー価値）
- **誰が** 使うのか（対象ユーザー/システム）
- **どこに** 位置するのか（コードベースのどの部分）

### ユーザーストーリー

以下の形式で記述します:
```
As a [ユーザーのタイプ],
I want [機能],
So that [メリット].
```

### 複雑さの評価

| レベル | 指標 | 典型的なスコープ |
|---|---|---|
| **Small** | 単一ファイル、独立した変更、新しい依存関係なし | 1-3ファイル、100行未満 |
| **Medium** | 複数ファイル、既存パターンに従う、軽微な新概念 | 3-10ファイル、100-500行 |
| **Large** | 横断的関心事、新しいパターン、外部統合 | 10+ファイル、500+行 |
| **XL** | アーキテクチャ変更、新サブシステム、マイグレーションが必要 | 20+ファイル、分割を検討 |

### 曖昧さゲート

以下のいずれかが不明確な場合、**続行する前にユーザーに確認してください**:

- コアの成果物が曖昧
- 成功基準が未定義
- 複数の有効な解釈が存在する
- 技術的アプローチに大きな未知数がある

推測しないでください。質問してください。仮定に基づいて構築された計画は実装時に失敗します。

---

## フェーズ 2 — EXPLORE（探索）

深いコードベースインテリジェンスを収集します。以下の各カテゴリについてコードベースを直接検索します。

### コードベース検索（8カテゴリ）

各カテゴリについて、grep、find、ファイル読み込みを使用して検索します:

1. **類似の実装** — 計画している機能に似た既存の機能を見つけます。類似のパターン、エンドポイント、コンポーネント、またはモジュールを探します。

2. **命名規約** — コードベースの関連エリアでファイル、関数、変数、クラス、エクスポートがどのように命名されているかを特定します。

3. **エラーハンドリング** — 類似のコードパスでエラーがどのようにキャッチ、伝播、ログ記録、ユーザーへの返却されるかを見つけます。

4. **ログパターン** — 何がログに記録され、どのレベルで、どの形式で記録されるかを特定します。

5. **型定義** — 関連する型、インターフェース、スキーマ、およびそれらの構成方法を見つけます。

6. **テストパターン** — 類似の機能がどのようにテストされているかを見つけます。テストファイルの場所、命名、セットアップ/ティアダウンパターン、アサーションスタイルに注目します。

7. **設定** — 関連する設定ファイル、環境変数、フィーチャーフラグを見つけます。

8. **依存関係** — 類似の機能で使用されているパッケージ、インポート、内部モジュールを特定します。

### コードベース分析（5つのトレース）

関連ファイルを読み込んでトレースします:

1. **エントリポイント** — リクエスト/アクションはどのようにシステムに入り、変更対象のエリアに到達するか？
2. **データフロー** — データは関連するコードパスをどのように流れるか？
3. **状態変更** — どの状態が変更され、どこで変更されるか？
4. **コントラクト** — どのインターフェース、API、プロトコルを遵守する必要があるか？
5. **パターン** — どのアーキテクチャパターンが使用されているか（リポジトリ、サービス、コントローラーなど）？

### 統合ディスカバリーテーブル

発見事項を単一のリファレンスにまとめます:

| カテゴリ | ファイル:行 | パターン | 主要スニペット |
|---|---|---|---|
| 命名 | `src/services/userService.ts:1-5` | キャメルケースのサービス、パスカルケースの型 | `export class UserService` |
| エラー | `src/middleware/errorHandler.ts:10-25` | カスタム AppError クラス | `throw new AppError(...)` |
| ... | ... | ... | ... |

---

## フェーズ 3 — RESEARCH（調査）

機能が外部ライブラリ、API、または馴染みのない技術を含む場合:

1. 公式ドキュメントをウェブで検索する
2. 使用例とベストプラクティスを見つける
3. バージョン固有の注意点を特定する

各発見事項を以下の形式で記述します:

```
KEY_INSIGHT: [学んだこと]
APPLIES_TO: [計画のどの部分に影響するか]
GOTCHA: [警告やバージョン固有の問題]
```

機能がよく理解された内部パターンのみを使用する場合、このフェーズをスキップし、「外部調査不要 — 機能は確立された内部パターンを使用」と記載します。

---

## フェーズ 4 — DESIGN（設計）

### UX変換（該当する場合）

変更前後のユーザー体験を文書化します:

**変更前:**
```
┌─────────────────────────────┐
│  [現在のユーザー体験]        │
│  現在のフローを示す、        │
│  ユーザーが見る/行うこと     │
└─────────────────────────────┘
```

**変更後:**
```
┌─────────────────────────────┐
│  [新しいユーザー体験]        │
│  改善されたフローを示す、    │
│  ユーザーにとって何が変わるか│
└─────────────────────────────┘
```

### インタラクションの変更

| タッチポイント | 変更前 | 変更後 | 備考 |
|---|---|---|---|
| ... | ... | ... | ... |

機能が純粋にバックエンド/内部的でUXの変更がない場合、「内部変更 — ユーザー向けのUX変換なし」と記載します。

---

## フェーズ 5 — ARCHITECT（アーキテクチャ設計）

### 戦略的設計

実装アプローチを定義します:

- **アプローチ**: ハイレベルな戦略（例: 「既存のリポジトリパターンに従って新しいサービスレイヤーを追加」）
- **検討した代替案**: 他にどのようなアプローチが評価され、なぜ却下されたか
- **スコープ**: 構築する内容の具体的な境界
- **構築しないもの**: スコープ外であることの明示的なリスト（実装中のスコープクリープを防止）

---

## フェーズ 6 — GENERATE（生成）

以下のテンプレートを使用して完全な計画文書を作成します。`.claude/PRPs/plans/{kebab-case-feature-name}.plan.md` に保存します。

ディレクトリが存在しない場合は作成します:
```bash
mkdir -p .claude/PRPs/plans
```

### 計画テンプレート

````markdown
# Plan: [機能名]

## 概要
[2-3文の概要]

## ユーザーストーリー
As a [ユーザー], I want [機能], so that [メリット].

## 問題 → 解決策
[現在の状態] → [望ましい状態]

## メタデータ
- **複雑さ**: [Small | Medium | Large | XL]
- **ソースPRD**: [パスまたは "N/A"]
- **PRDフェーズ**: [フェーズ名または "N/A"]
- **推定ファイル数**: [数]

---

## 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: [file:lines]
[命名パターンを示す実際のコードスニペット]

### ERROR_HANDLING
// SOURCE: [file:lines]
[エラーハンドリングを示す実際のコードスニペット]

### LOGGING_PATTERN
// SOURCE: [file:lines]
[ログを示す実際のコードスニペット]

### REPOSITORY_PATTERN
// SOURCE: [file:lines]
[データアクセスを示す実際のコードスニペット]

### SERVICE_PATTERN
// SOURCE: [file:lines]
[サービスレイヤーを示す実際のコードスニペット]

### TEST_STRUCTURE
// SOURCE: [file:lines]
[テストセットアップを示す実際のコードスニペット]

---

## 変更対象ファイル

| ファイル | アクション | 根拠 |
|---|---|---|
| `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
# 型チェッカーを実行
[プロジェクト固有の型チェックコマンド]
```
EXPECT: 型エラーゼロ

### ユニットテスト
```bash
# 影響を受けるエリアのテストを実行
[プロジェクト固有のテストコマンド]
```
EXPECT: すべてのテストが合格

### フルテストスイート
```bash
# 完全なテストスイートを実行
[プロジェクト固有のフルテストコマンド]
```
EXPECT: リグレッションなし

### データベース検証（該当する場合）
```bash
# スキーマ/マイグレーションを検証
[プロジェクト固有のDBコマンド]
```
EXPECT: スキーマが最新

### ブラウザ検証（該当する場合）
```bash
# 開発サーバーを起動して検証
[プロジェクト固有の開発サーバーコマンド]
```
EXPECT: 機能が設計通りに動作

### 手動検証
- [ ] [ステップバイステップの手動検証チェックリスト]

---

## 受け入れ基準
- [ ] すべてのタスクが完了
- [ ] すべての検証コマンドが合格
- [ ] テストが作成され合格
- [ ] 型エラーなし
- [ ] リントエラーなし
- [ ] UXデザインと一致（該当する場合）

## 完了チェックリスト
- [ ] コードが発見されたパターンに従っている
- [ ] エラーハンドリングがコードベースのスタイルに一致
- [ ] ログがコードベースの規約に従っている
- [ ] テストがテストパターンに従っている
- [ ] ハードコードされた値がない
- [ ] ドキュメントが更新されている（必要な場合）
- [ ] 不要なスコープの追加がない
- [ ] 自己完結型 — 実装中に質問不要

## リスク
| リスク | 可能性 | 影響 | 軽減策 |
|---|---|---|---|
| ... | ... | ... | ... |

## 備考
[追加のコンテキスト、決定事項、または所見]
```

---

## 出力

### 計画の保存

生成した計画を以下に書き込みます:
```
.claude/PRPs/plans/{kebab-case-feature-name}.plan.md
```

### PRDの更新（入力がPRDの場合）

この計画がPRDフェーズから生成された場合:
1. フェーズのステータスを `pending` から `in-progress` に更新する
2. フェーズに計画ファイルのパスを参照として追加する

### ユーザーへの報告

```
## 計画作成完了

- **ファイル**: .claude/PRPs/plans/{kebab-case-feature-name}.plan.md
- **ソースPRD**: [パスまたは "N/A"]
- **フェーズ**: [フェーズ名または "standalone"]
- **複雑さ**: [レベル]
- **スコープ**: [Nファイル、Mタスク]
- **主要パターン**: [発見された上位3つのパターン]
- **外部調査**: [調査したトピックまたは "不要"]
- **リスク**: [最大のリスクまたは "特定なし"]
- **信頼度スコア**: [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を作成する
````
