plan

計画

プロジェクトの原則に基づいた実装計画を作成します。計画は brain/plans/ に記述してください。実装は一切行わないでください。成果物は計画のみです。

自律セッションモード

このスキルが非対話型の Noodle 実行セッション（例：Cook、Oops、Repair）で実行される場合：

• ステップ 2（AskUserQuestion）をスキップします。範囲は最初のプロンプトですでに明確に定義されています。
• ステップ 6 の一時停止をスキップします。計画を作成してコミットし、stage_yield を出力して（ステップ 6 を参照）、セッションを終了します。人間によるレビューを待たないでください。
• ステップ 4（find-skills）では、確認を求めずにスキルをインストールします。

その他のステップはすべて通常どおり進めます。

進捗の追跡には Tasks を使用してください。 各ステップのタスクを作成し（TaskCreate）、開始時に in_progress、完了時に completed に設定します（TaskUpdate）。各ステップの完了後に TaskList を確認してください。

ステップ 0 — 複雑さのトリアージ

計画ワークフロー全体を実行する前に、このタスクに本当に計画が必要かどうかを評価してください。

非常に小規模（1～2 ファイル、実装方法が明白）： このタスクに計画は不要であり、計画スキルを使わずに直接実装することを提案してください。ここで終了してください。実装はしないでください。

計画が必要（ステップ 1 に進む）：

• 変更対象が 3 ファイル以上にわたる、または新しいアーキテクチャを導入する
• 有効なアプローチが複数あり、ユーザーの意見が必要
• 範囲が不明確、または複数の領域にまたがる懸念事項がある
• ユーザーが明示的に計画を求めている

ステップ 1 — 原則を読み込む

brain/principles.md を読みます。すべての [[wikilink]] をたどり、リンク先の原則ファイルをそれぞれ読んでください。これらの原則は計画に関するすべての判断を導くものです。計画の概要とフェーズファイルでは、原則名を挙げてください。

このステップを省略しないでください。記憶している原則の内容を使わず、必ず最新の内容を読み込んでください。 ステップ 5b のセルフチェックで、引用が存在することを確認します。

ステップ 2 — 範囲と制約を定義する

コードベースを調査する前に、AskUserQuestion を使って曖昧な点を解消してください。

• 対象範囲と、明示的に対象外とする範囲は何ですか？
• 制約（依存関係、プラットフォーム要件、維持すべき既存のパターンなど）はありますか？
• 何をもって「完了」としますか？

具体的な選択肢を示して質問してください。依頼がすでに明確な場合は、範囲の境界を簡潔に確認して先に進んでください。

ステップ 3 — サブエージェントでコンテキストを調査する

必ず Task ツールを使ってサブエージェントに調査を委任してください。メインコンテキストで大規模なコードベース調査を行ってはいけません。

調査エージェント（subagent_type: Explore）を起動して、以下を行ってください。

• 影響を受ける領域の既存コードを読む
• パターン、規約、依存関係を特定する
• 変更に関連するアーキテクチャを把握する
• テスト、型、関連するインフラストラクチャを見つける

独立した領域を調査する場合は、複数のエージェントを並行して実行してください。大規模な調査では、チームを使用してください。

ステップ 4 — ドメインスキルを集める

インストール済みのスキルを照合し、不足しているスキルを見つけてください。ルーティング表と検索ワークフローについては、references/domain-skills.md を参照してください。

ステップ 5 — 計画を作成する

ファイルツールを使って計画を作成してください。ディレクトリ構成、概要／フェーズファイルの形式、検証戦略、CLI のスキャフォールディング手順については、references/templates.md を参照してください。

フェーズの規模

• フェーズごとに 関数／型 1 つとテスト、または バグ修正 1 件 とします。「ファイル 1 つ」や「コンポーネント 1 つ」ではありません（規模にばらつきが大きいため）。
• 可能な限り、フェーズごとの変更ファイル数は 2～3 個までにします。
• 大きなフェーズを 3～4 個設けるより、小さなフェーズを 8～10 個設けることを優先します。小さなフェーズにすることで、今後の選択肢を保ちやすくなります。
• 1 つのフェーズでテストケースが 5 件を超える場合、または関数が 3 つを超える場合は、フェーズを分割してください。

再設計の確認

既存コードに手を加える変更では、第一原理に基づく再設計を検討してください。

「この要件を前提にゼロから構築するなら、何を作るだろうか？」

既存の設計に変更を継ぎ足すのではなく、全体として再設計してください。

代替案の確認

アーキテクチャ上の判断では、概要の「制約」セクションに 2～3 個のアプローチを簡潔に示してください。どの案を選んだか、その理由も記載してください。これにより、早まった決定を防ぎ、検討した設計の選択肢を記録できます。brain/principles/exhaust-the-design-space.md を参照してください。

計画インデックスとToDoを更新する

計画を書き込んだ後、両方の項目が存在することを確認します。

• brain/plans/index.md に - [[plans/NN-plan-name/overview]] がある
• brain/todos.md のToDo項目に計画のwikilinkがある

新しいToDo：を読み、N. [ ] description [[plans/NN-plan-name/overview]] を追記し、next-idをインクリメントします。brain/index.md` は編集しないでください。自動インデックスフックが管理します。

完了した計画をアーカイブする

ディレクトリを brain/archive/plans/ に移動し、brain/plans/index.md を更新して、todo スキルを使ってToDoを完了済みにします。

ステップ 5b — セルフチェック

すべての計画ファイルを書き込んだ後、次に進む前に以下の3つの制約を確認します。違反があれば修正してください。

原則の引用： 概要では、少なくとも2つのbrainの原則を [[wikilink]] で参照する必要があります。参照がない場合は、brain/principles.md を再読し、設計上の判断に最も関連する原則を概要に追加します。

フェーズの規模： 各フェーズを確認します。3ファイルを超えて変更するフェーズ、または5件を超えるテストケースを列挙するフェーズがある場合は、より小さなフェーズに分割します。「Changes」に記載されたファイル数を数え、3を超えている場合、そのフェーズは大きすぎます。

フェーズにコードを含めない： フェーズのファイルにGo／TS／Pythonのコードブロックを含めてはいけません。型や関数の名前は挙げてもかまいませんが、その定義は記述しないでください。フェーズは差分や実装仕様ではなく、シニアエンジニア向けの簡潔な指示書として読める内容にします。コードブロックがあれば、意図する構成を説明する文章に置き換えてください。

ステップ 6 — 提示して引き継ぐ

計画を要約し、フェーズ、対象範囲の境界、適用するスキル、検証方法を列挙します。ユーザーに brain/plans/ 内の計画ファイルを確認するよう依頼します。

成果物が完成したことを示すため、stage_yield を出力します。

noodle event emit --session $NOODLE_SESSION_ID stage_yield --payload '{"message": "Plan written to brain/plans/NN-slug-name/overview.md"}'

これにより、エージェントのプロセスがまだ終了していなくても、Noodleバックエンドにステージの作業完了を伝えます。これがない場合、ステージはプロセスが正常終了したときにのみ完了します。

ここで停止します。 実装を開始しないでください。計画をいつ、どのように実行するかはユーザーが決定します。