rpi-plan

実装計画

対話的かつ反復的なプロセスを通じて、詳細な実装計画を作成することが求められます。懐疑的かつ綿密に取り組み、ユーザーと協力して質の高い技術仕様を作成してください。

初期設定

ユーザーがこのコマンドとともにタスクの説明、ファイルパス、またはトピックをすでに提示している場合は、以下のステップ 1 に進んでください。コンテキストがまったく提示されていない場合に限り、次のように応答してください。

I'll help you create a detailed implementation plan. Let me start by understanding what we're building.

Please provide:
1. A description of what you want to build or change
2. Any relevant context, constraints, or specific requirements
3. Pointers to related files or previous research

I'll analyze this information and work with you to create a comprehensive plan.

その後、ユーザーの入力を待ってください。

プロセスのステップ

ステップ 1：コンテキストの収集とブレインストーミング

1. 言及されているすべてのファイルを直ちに、全文読み込んでください：

   • ユーザーが参照したファイル（ドキュメント、調査資料、コードなど）
   • 重要：Read ツールを使う際は、limit/offset パラメーターを指定せず、ファイル全体を読み込んでください
   • 最重要：メインコンテキストで自分自身がこれらのファイルを読む前に、サブタスクを開始してはいけません
   • 絶対にファイルを部分的に読んではいけません。ファイルが言及されている場合は、全文を読み込んでください

2. 調査がすでに存在するか確認してください：

   • ユーザーが調査ドキュメント（例：docs/agents/research/ のもの）を提示した場合は、その内容を信頼できる情報源として扱ってください。ドキュメントがすでに扱っているトピックを再調査してはいけません。調査結果、ファイル参照、アーキテクチャ分析を、そのまま計画の基礎として使用してください。
   • **提示済みの調査を繰り返したり、やり直したりしてはいけません。**計画段階では、すでにある情報を集めるのではなく、それを実行可能な実装手順に落とし込みます。
   • 調査ドキュメントが提示されていない場合は、関連する調査ドキュメントを見つけるためにサブエージェントを起動してください。
     • サブエージェントは、まず調査フォルダーをファイル名と YAML フロントマターで素早く確認し、関連するドキュメントを探します
     • 次に、その調査が計画に関連するか確認します
     • ドキュメントが関連する場合は、作成後の変更をすべて確認し、最新の状態か検証します
     • ドキュメントが古くなっている場合は、サブエージェントが最新情報を十分に把握し、ドキュメントを更新するようにしてください

3. 不足している情報を補うためにサブエージェントを起動してください：

   • 調査ドキュメントですでに扱われている内容を再発見するために、サブエージェントを起動してはいけません
   • タスクに関連する追加ファイルを探すため、対象を絞ったサブエージェントを起動してください（利用可能な場合は、たとえばエクスプローラーのサブエージェント）
   • サブエージェントの役割は、長い回答を返すことではなく、関連ファイルのパスと行番号を調べて報告することです
   • 各サブエージェントには、広範な調査ではなく、具体的で範囲を絞った質問を割り当ててください
   • 使用するサードパーティーのインターフェースを十分に理解する必要があります：
     • ソースコード（例：node_modules）にアクセスできる場合は、関連箇所を調べるサブエージェントを起動してください
     • それ以外の場合は、サブエージェントとして、またはウェブ検索ツールがサブエージェントのように機能する場合は直接、ウェブ検索を実施してください
   • その機能に関連するドキュメントをすべて特定し、更新計画を立てる必要があります
   • 次のステップに進んだり、メインエージェントで追加調査を行ったりする前に、サブエージェントの作業が完了するのを必ず待ってください

4. 特に関連性の高いファイルをメインコンテキストで直接読み込んでください：

   • 調査結果、ユーザー入力、サブエージェントの報告に基づいて、該当タスクに最も関連するソースファイルを特定してください
   • Read ツールを使って、これらのファイルを自分で読み込んでください。サブエージェントに任せてはいけません。正確な計画を書くために、これらのファイルを自分のコンテキストに取り込む必要があります。
   • 変更対象のファイル、または従うべきインターフェースやパターンを定義しているファイルを優先してください

5. 分析し、理解を検証してください：

   • 要件を実際のコード（および提示された場合は調査ドキュメント）と照合してください
   • 食い違いや誤解を特定してください
   • 検証が必要な前提を記録してください
   • コードベースの実態に基づいて、実際の作業範囲を判断してください

6. 十分な情報に基づいて理解を示し、ユーザーと対話を重ねます：

   • 質問する前に、関連するコードベースの現在の状態を要約します。
   • ASCII 図、ツリー、フローチャートを使って、現在のアーキテクチャや処理の流れを説明します。
   • 重要なファイル、コンポーネント、データフロー、制約事項、および該当する file:line 形式の参照を含めます。
   • 提案する解決策を示したり、明言されていない前提を置いたりしないでください。
   • その後、推奨する回答を添えて、一度に1つの質問をします。
   • ユーザーの回答ごとに、次の質問をする前に、更新された理解を簡潔に言い直します。
   • 各Q&Aのやり取りは --- で区切ります。

   計画のあらゆる側面について、共通認識に達するまでユーザーに徹底的に質問してください。設計ツリーの各分岐をたどり、依存関係のある判断を1つずつ解決します。異なる選択肢を提示し、どれが最適かをユーザーに判断してもらいます。

   視覚的に示す：UI/UX の設計やアーキテクチャに関する判断では、ASCII のモックアップやツリーを使ってください。ユーザーが質問の内容を直感的に理解しやすくなります。

   重要：ユーザーはその分野の専門家であり、下す判断に責任を持ちます。

   やり取りの中で述べた事実や主張は、コードベース、依存関係の確認、またはウェブ検索によって検証してください。

   コードベースを調べれば答えられる質問は、コードベースを調査してください。

Step 2: 計画の構成を策定する

重要な判断がすべて明確になったら、ブレインストーミングから受け入れ基準を抽出し、決定事項と計画のフェーズを明確に要約して、ユーザーが分割案を改善できるようにします。 各フェーズは、テスト可能な垂直スライスにしてください。 それが適さない場合は、フェーズを少数の大きな単位にまとめてください。

Acceptance criteria:
- [Specific behavior or outcome the implementation must satisfy]
- [Another required outcome]

Key decisions:
1. **<Specific decision>:** <chosen direction>.
   - Why: <short reason>
   - Impact: <main implementation consequence>

Planned phases:
1. ...
2. ...
3. ...

Reply "create plan" and I will write the plan.

機能ごとの垂直スライスにしてください。テストやドキュメントの更新を独立したフェーズとして切り出さないでください。関連する動作を実装するフェーズに、テストとドキュメントも含めます。

Step 3: 詳細な計画を記述する

ユーザーから明示的な承認を得た後：

1. メタデータを収集する：

   • python3 <skill_directory>/scripts/metadata.py を実行して、日付、コミット、ブランチ、リポジトリ情報を取得します
   • 出力ファイル名を決定します：docs/agents/plans/YYYY-MM-DD-description.md
     • YYYY-MM-DD は本日の日付です
     • description は簡潔な kebab-case の説明です
     • 例：2025-01-08-improve-error-handling.md
     • 出力先フォルダー（docs/agents/plans/）は、プロジェクトの AGENTS.md または CLAUDE.md の指示で変更できます

2. 計画を docs/agents/plans/YYYY-MM-DD-description.md に記述する

   • <skill_dir>/references/plan-template.md で定義されたテンプレート構成を使用します
   • docs/agents/plans/ ディレクトリが存在することを確認し、必要であれば作成します
   • 実行可能な項目にはすべてチェックボックスを付けます（- [ ]）。これにより、実装中に進捗を追跡できます。各タスクと各検証手順も対象です。
   • 検証に関する指針：
     • 自動化できる検証はすべて「自動検証」に記載します。
     • 「手動検証」には、まだ合理的に自動化できないユーザー向けの動作だけを記載します。
     • 手動で確認する項目がない場合は、「手動検証」セクション自体を省略します。「なし」などのプレースホルダー用チェックボックスは追加しないでください。
     • テストやスクリプトで対応できる場合は、手動での git diff の確認や、一時的に不具合を発生させてから元に戻す確認を記載しないでください。

ステップ 4：レビューと反復

1. サブエージェントが利用可能な場合は、まず計画をレビューするよう依頼してください。利用できない場合は、自分でレビューしてください。一貫性やその他のよくある誤りに重点を置いてください。

2. 該当する指摘を直接修正してください

3. 計画の下書きの場所を提示してください：

   I've created the initial implementation plan at:
   `docs/agents/plans/YYYY-MM-DD-description.md`
   
   Please review it and let me know:
   - Are the phases properly scoped?
   - Are the success criteria specific enough?
   - Any technical details that need adjustment?
   - Missing edge cases or considerations?
   
   Confirm if you are happy with the plan.
   

4. フィードバックに基づいて反復してください - 次の対応ができるようにしてください：

   • 不足しているフェーズを追加する
   • 技術的なアプローチを調整する
   • 成功基準（自動と手動の両方）を明確にする
   • スコープ項目を追加または削除する

5. ユーザーが納得したら、計画のステータスを ready に設定してください。コミットするかユーザーに確認してください（計画が gitignore 対象でない場合に限ります）。

   次のステップについて、ユーザーにヒントを提示してください。

   Next step: implement the plan.
   
   Start a fresh session:
   /new
   
   Then run:
   /rpi-implement @<path-to-plan>
   

重要なガイドライン

1. 批判的に考える：

   • 曖昧な要件に疑問を投げかける
   • 起こり得る問題を早期に特定する
   • 「なぜ」「ほかには何があるか」を尋ねる
   • 推測せず、コードで確認する

2. 対話的に進める：

   • 計画を一度にすべて書かない
   • 主要な各ステップで合意を得る
   • 途中で軌道修正できるようにする
   • 協力して進める

3. 徹底しつつ、重複を避ける：

   • 提供された調査結果はそのまま使用してください。すでに記録されている内容を再調査しないでください
   • サブエージェントを使って重要なファイルをすばやく見つけてください
   • 重要なソースファイルはサブエージェントに任せず、自分のコンテキストに直接読み込んでください
   • 自動と手動の区別を明確にし、測定可能な成功基準を記述してください

4. 視覚的に伝える：

   • 変更にユーザー向けのインターフェース（Web UI、CLI 出力、ターミナル UI、フォーム、ダッシュボードなど）が含まれる場合は、計画に ASCII モックアップを含めてください
   • モックアップは意図する結果をすぐに理解できるようにし、早期に誤解を発見するのに役立ちます
   • モックアップを作成する前に、現在の UI を調査してください
   • 既存の UI を変更する場合は、現在の状態と提案する状態の両方を示してください
   • レイアウト、主要な要素、インタラクションが伝わる程度に、モックアップはシンプルかつ正確にしてください

5. 実用的に進める：

   • 段階的でテスト可能な変更に重点を置く
   • 移行とロールバックを検討する
   • 関連するドキュメントの更新がすべて計画に含まれていることを確認する
   • エッジケースを考慮する

6. 最終計画に未解決の質問を残さない：

   • 計画中に未解決の質問が生じた場合は、作業を停止してください
   • すぐに調査するか、確認を求めてください
   • 未解決の質問を残したまま計画を書かないでください
   • 実装計画は完全で、実行可能なものでなければなりません
   • 最終決定の前に、すべての判断を確定してください

成功基準のガイドライン

成功基準は必ず次の 2 つのカテゴリに分けてください：

1. 自動検証（エージェントが実行可能）：

   • 実行可能なコマンド：テストスイート、リンター、型チェッカー
   • 存在すべき特定のファイル
   • コードのコンパイル／型チェック

2. 手動検証（人によるテストが必要）：

   • 作業中の機能をユーザーが操作できる場合に限り、手動検証を追加してください（例：UI を開く、コマンドを実行する、ワークフローを起動する）。
   • 「コードをレビューする」または「実装を確認する」を検証ステップにしてはいけません。
   • 内部フェーズ（リファクタリング、ユーティリティ、型、エントリーポイントのないバックエンド）に手動検証を追加してはいけません。代わりに自動検証を使用してください。
   • ユーザー向け機能が完成するマイルストーンに、手動検証を配置することを推奨します。
   • 例：UI／UX の機能、実環境でのパフォーマンス、自動化が難しいエッジケース、ユーザー受け入れ基準。

よくあるパターン

データベースの変更の場合：

• スキーマ／マイグレーションから始める
• ストアメソッドを追加する
• ビジネスロジックを更新する
• API 経由で公開する
• クライアントを更新する

新機能の場合：

• まず既存のパターンを調査する
• データモデルから始める
• バックエンドロジックを構築する
• API エンドポイントを追加する
• 最後に UI を実装する

リファクタリングの場合：

• 現在の動作を記録する
• 段階的な変更を計画する
• 後方互換性を維持する
• 移行戦略を含める