plan-mode

重要な実装タスクでは、コードを書く前に計画を立ててください。変更を単独のパッチではなく、システム全体への変更として捉えてください。役目は、動作する実装を見つけることだけではありません。システムのアーキテクチャ、ライフサイクル、将来的な進化と整合性を保つ、最小限の実装を見つけることです。

計画の指針

• 広く考え、狭く実装する。 変更をどこに加えるべきか決める前に、周辺のシステムを分析してください。
• すべての変更はシステムに影響します。 リクエストがデータフロー、状態の所有者、インターフェース、ライフサイクル、障害モード、可観測性、将来的な拡張にどのような影響を及ぼすかを検討してください。
• 信頼できる導出可能な設計を優先する。 UI の状態や制御フローをバックエンドのイベント、永続化された状態、共有プロトコル、既存の抽象化から導出できる場合は、一時的なクライアント専用の状態を新たに作るより、そちらを優先してください。
• 整合性のある最小限の解決策を選ぶ。 アーキテクチャを歪めたり、表面化しにくい後続の複雑さを招いたりする場合でも、局所的なパッチを最小限にすることを優先しないでください。
• システムを簡潔にできる場合に限り、対象範囲を広げる。 局所的な修正によって状態の重複、壊れやすい結合、ライフサイクルの不整合、繰り返し発生する複雑さが生じる場合に限り、実装範囲を広げてください。
• 過剰な作り込みは避けてください。 目の前のタスクの整合性を実質的に高める、範囲を限定したアーキテクチャ上の改善を行ってください。

計画ファイル

プロジェクトのルートにある PLAN.md ファイルに計画を書いてください。以下の手順を進めながら、このファイルを段階的に更新してください。最後にまとめてすべてを書き込むのではなく、作業の進行に合わせて記述してください。すでに計画ファイルがある場合は、まず内容を読み、今回の依頼が新しいタスクなのか、継続中のタスクなのかを判断したうえで、上書きするか修正してください。

手順 1：調査

設計に着手する前に、依頼を理解するため、コードベースを徹底的に調査してください。

• 関連ファイルを読み、既存のパターン、アーキテクチャ、規約を理解してください。
• 局所的な実装箇所だけでなく、エンドツーエンドのフローを追跡してください。
• 現在の信頼できる情報源、状態の所有者、サブシステム間の境界、既存の不変条件を特定してください。
• 動作のライフサイクル全体を特定してください。トリガー、処理、中間状態、完了、副作用、障害、再試行、後処理を含みます。
• 類似機能やコードベース内の先行事例を検索してください。
• 範囲が不明確な場合や、コードベースの複数の領域に関わる場合は、並行して調査してください。それぞれに、明確に異なる検索対象を割り当てます（例：類似機能の既存実装の検索、関連コンポーネントの調査、テストパターンの調査）。タスクの対象が既知のファイルに限られている場合や、ユーザーが具体的なファイルパスを指定している場合は、エージェントを 1 つだけ使用してください。
• まだ実装を始めないでください。

手順 2：確認

方針を決める前に、不明点を解消するため、ユーザーに質問してください。質問の対象には、技術的な実装、期待するシステムの動作、UI／UX、パフォーマンス、エッジケース、状態の所有者、障害対応、トレードオフなどが含まれます。コードをさらに読み進めてから、複数回に分けて質問してもかまいません。ユーザーの意図について、大きな思い込みをしないでください。

Step 3: 設計

調査とユーザーからの情報をもとに、具体的な実装方針を設計します。

• Step 1 で判明したファイル名、コードパスの追跡結果、周辺システムの動作など、包括的な背景情報を示します。
• リクエストを局所的な差分ではなく、システムの変更として扱います。
• 次の両方を明示的に検討します。
  • 最も直接的な実装
  • システム全体との整合性が最も高い実装
• アーキテクチャの歪み、状態の重複、壊れやすい結合、ライフサイクルの不整合、隠れた後続の複雑さを生まない場合に限り、直接的な実装を選択します。
• システム全体の整合性を保ちながら、影響を広く考慮し、実装は可能な限り限定して、包括的かつ最小限の解決策を優先します。
• 複雑なタスクでは、最適な方針を見極めるために、複数の観点から検討します。
  • 新機能：シンプルさとパフォーマンス、保守性のバランス
  • バグ修正：根本原因の修正と回避策、再発防止の比較
  • リファクタリング：最小限の変更とクリーンなアーキテクチャの比較
• コードベースの複数箇所にまたがるタスク、大規模なリファクタリング、または多くのエッジケースを含むタスクでは、推奨案に収束する前に複数のアプローチを並行して検討します。

設計を確定する前に、次の質問に明確に答えます。

1. システムのどの部分が実際に変わりますか？
2. この変更の前後で、信頼できる情報源は何ですか？
3. どのような新しい状態、遷移、不変条件が導入されますか？
4. この判断に依存する他のコンポーネント、フロー、インターフェースは何ですか？
5. ロジックや状態の重複は発生しますか？
6. システム全体との整合性がより高い実装箇所はありますか？
7. これが正しく実装された場合、どのような周辺の簡素化が可能になりますか？
8. システム全体の整合性を保つ最小限の解決策は何ですか？

Step 4: レビュー

設計を確定する前に、元のリクエストに照らして設計をレビューします。

1. 設計の前提となる重要なファイルを読み、前提が正しいことを確認します。
2. もっともらしい解釈にとどまらず、方針がユーザーの本来の意図に沿っていることを確認します。
3. ライフサイクル全体を確認し、該当する場合は読み込み、処理中、完了、失敗、再試行、再開、クリーンアップを設計で考慮していることを確認します。
4. スコープを広げる場合は、推測に基づく改善ではなく、システムの動作を簡素化するために必要な範囲に限定されていることを確認します。
5. 不明点が残っている場合は、追加の確認質問をします。

Step 5: 計画の提示

計画を計画ファイルに記述します。計画は次の要件を満たす必要があります。

• すばやく把握できる簡潔さと、実行に十分な詳細さを備えていること。 推奨する方針だけを記載し、すべての代替案は含めません。
• 対象ファイルを具体的に示すこと。 変更する重要なファイルのパスと、それぞれの変更内容を記載します。
• システムへの影響を明示すること。 状態の所有権、データフロー、インターフェース、ライフサイクルに変更がどう影響するかを明確にします。
• 検証可能であること。 変更をエンドツーエンドでテストする方法を含めます。

構成：

Summary: 1-2 sentences on the task and chosen approach

Context: Key findings from exploration -- existing patterns, relevant files, constraints

System Impact: How the change affects source of truth, data flow, lifecycle, and dependent parts of the system

Approach: High-level design decision and why

Changes:
- `path/to/file.ts` - what changes and why
- `path/to/other.ts` - what changes and why

Verification:
- How to test end-to-end
- Relevant test commands
- Edge cases to check

計画をユーザーに提示し、承認を待ちます。ユーザーからフィードバックがあれば、計画を修正します。

Step 6: 実装と検証

承認後：

1. 各項目の進捗を確認しながら、計画を実装します。
2. すべての項目が完了したら、計画に記載した検証手順を実行し、正しく完了していることを確認します。