ce:plan

技術計画の作成

注：現在の年は2026年です。 計画の日付を記載したり、最近のドキュメントを検索したりする際に、この情報を使用してください。

ce:brainstorm では、何を構築するかを定義します。ce:plan では、どのように構築するかを定義します。ce:work では、計画を実行します。事前のブレインストーミングは参考になりますが、必須ではありません。ce:plan は、要件ドキュメント、バグ報告、機能のアイデア、概要だけの説明など、あらゆる入力をもとに作業できます。

直接呼び出された場合は、必ず計画を立ててください。 直接の呼び出しを「計画タスクではない」と判断して、ワークフローを中断してはいけません。入力が不明瞭な場合は、確認の質問をするか、計画の開始手順（フェーズ0.4）を使って十分な背景を把握してください。ただし、必ず計画ワークフローを続けてください。

このワークフローでは、継続的に参照できる実装計画を作成します。コードの実装、テストの実行、実行時の結果からの学習は行いません。コードを変更して何が起きるかを確認しなければ答えが得られない場合は、ここではなくce:workで扱います。

対話方法

利用できる場合は、プラットフォームの質問ツールを使用してください。ユーザーに質問する際は、存在するならプラットフォームのブロッキング質問ツール（Claude CodeのAskUserQuestion、Codexのrequest_user_input、Geminiのask_user）を優先してください。それ以外の場合は、チャットで番号付きの選択肢を提示し、先に進む前にユーザーの返答を待ってください。

質問は一度に一つずつ行ってください。自然な選択肢がある場合は、簡潔な単一選択形式を優先してください。

機能の説明

<feature_description> #$ARGUMENTS </feature_description>

上記の機能の説明が空の場合は、ユーザーに次のように尋ねてください。「何を計画しますか？考えているタスク、目標、プロジェクトについて説明してください。」その後、返答があるまで待ってから続けてください。

入力があっても不明瞭、または情報が不足している場合は、作業を中断せず、確認の質問を1〜2件するか、フェーズ0.4の計画の開始手順に進んで、十分な背景を把握してください。目標は常にユーザーの計画を支援することであり、ワークフローを終了することではありません。

重要：計画書内のすべてのファイル参照には、絶対パス（例：/Users/name/Code/project/src/models/user.rb）ではなく、リポジトリ相対パス（例：src/models/user.rb）を使用してください。 これは、実装単位のファイル一覧、パターン参照、元ドキュメントへのリンク、文章中の言及など、あらゆる箇所に適用されます。絶対パスは、マシン、ワークツリー、チームメンバー間での可搬性を損ないます。

基本原則

1. 要件を唯一の基準とする - ce:brainstormで要件ドキュメントが作成されている場合は、動作を一から考え直すのではなく、それをもとに計画を立ててください。
2. コードではなく、判断を記録する - アプローチ、範囲、ファイル、依存関係、リスク、テストシナリオを記録してください。実装コードや、シェルコマンドを手順どおりに並べたものを事前に書いてはいけません。レビュー担当者が方針を検証するのに役立つ場合は、高水準の技術設計を伝える擬似コードのスケッチやDSLの文法を含めてもかまいません。ただし、実装仕様ではなく、方向性を示すガイダンスとして明示してください。
3. 構成を固める前に調査する - 計画を確定する前に、必要に応じてコードベース、組織内の知見、外部のガイダンスを調査してください。
4. 成果物の規模を適切にする - 小規模な作業には簡潔な計画を、大規模な作業にはより構造化された計画を作成してください。どの規模でも基本方針は変わりません。
5. 計画時の調査と実行時の発見を分ける - 計画段階で解決できる疑問はここで解決してください。実行時に判明する不確定要素は、実装時に確認するものとして明示的に先送りしてください。
6. 計画の可搬性を保つ - ツール固有の実行者向け指示を埋め込まず、進行中のドキュメント、レビュー用成果物、または課題本文として使える計画にしてください。
7. 必要な場合は、実行方針を簡潔に反映する - 依頼、元ドキュメント、またはリポジトリの状況から、テストファースト、特性テスト優先、その他の標準とは異なる実行方針が明確に示されている場合は、計画に簡潔な指標として反映してください。計画を逐次的な実行手順に変えてはいけません。

計画の品質基準

すべての計画には、以下を含める必要があります。

• 問題の明確な枠組みと対象範囲の境界
• 依頼または元の文書に遡れる、具体的な要件のトレーサビリティ
• 提案する作業のリポジトリ相対パス（絶対パスは不可。Planning Rules を参照）
• 機能を含む実装単位ごとの明示的なテストファイルパス
• タスクだけでなく、根拠を伴う判断
• 参考にすべき既存のパターンやコード参照
• 機能を含む各単位のテストシナリオの列挙。実装者が自分でテスト項目を考案せずに、何をテストすべきか正確に把握できる具体性が必要です
• 明確な依存関係と実施順序

実装者が、コードの書き方を計画に尋ねることなく、安心して着手できる状態になったら、計画の準備は完了です。

ワークフロー

フェーズ 0：再開、ソース、スコープ

0.1 既存の計画作業を適切な場合に再開する

ユーザーが既存の計画ファイルに言及している場合、または docs/plans/ に明らかに最近作成された対応する計画がある場合：

• その計画を読みます
• その計画をそのまま更新するか、新しい計画を作成するか確認します
• 更新する場合は、完了済みのチェックボックスを保持し、引き続き関連するセクションのみを修正します

意図を深掘りする： 計画に関する「deepen」（または「deepening」）という語が、深掘りの簡易フローを開始する主要なきっかけです。ユーザーが「計画を深掘りして」「自分の計画を深掘りして」「深掘りパスを実行して」などと言った場合、対象となる文書は要件文書ではなく、docs/plans/ にある計画です。ユーザーが示したパス、キーワード、文脈を使って、適切な計画を特定します。パスが示された場合は、それが実際に計画文書であることを確認します。該当するものが明確でない場合は、作業を進める前にユーザーに確認します。

「強化」「確信」「不足」「厳密さ」といった語だけでは、深掘りを開始するには不十分です。これらの語は通常の編集依頼（「図に関するセクションを強化して」「テストシナリオに不足があります」など）でも使われるため、計画全体にわたる深掘りを開始する理由にはなりません。依頼が計画全体を明確に対象とし、変更する特定のセクションや内容領域を指定していない場合に限り、深掘りの意図として扱います。その場合でも、深掘りのフローに入る前にユーザーへ確認することを優先します。

計画が特定され、完成している（主要セクションがすべてそろっており、実装単位が定義され、status: active である）場合：

• 計画に YAML フロントマターがない場合（ソフトウェア以外の計画ではフロントマターの代わりに # Title 見出しと Created: 日付を使用します）、フェーズ 5.3 ではなく、編集または深掘りのために references/universal-planning.md に進みます。ソフトウェア以外の計画では、ソフトウェア向けの確信度チェックは行いません。
• それ以外の場合は、インタラクティブモードでフェーズ 5.3（確信度チェックと深掘り）に直接進みます。これにより、計画ワークフロー全体を再実行せず、どの指摘を反映するかをユーザーが選べます。

通常の編集依頼（例：「テストシナリオを更新して」「新しい実装単位を追加して」「リスクのセクションを強化して」）では、簡易フローを開始してはいけません。標準の再開フローに従います。

計画に deepened: YYYY-MM-DD というフロントマターフィールドがすでにあり、明示的に再度深掘りするようユーザーから依頼されていない場合でも、簡易フローでは同じ確信度の不足評価を行います。深掘りを必須にするわけではありません。

0.1b タスクの領域を分類する

タスクがソフトウェアの構築、変更、または設計に関する場合（コード、リポジトリ、API、データベースへの言及、または構築・変更・デプロイの依頼を含む）、フェーズ 0.2 に進みます。

タスクがソフトウェア以外の領域に関するもので、計画に値する複数ステップの目標を示している場合は、references/universal-planning.md を読み、そのワークフローに従います。以降のフェーズはすべてスキップします。

本当に判断が難しい場合（例：「移行を計画して」とだけあり、ほかに文脈がない場合）は、どのフローに進むかをユーザーに確認します。

それ以外（簡単な質問、エラーメッセージ、事実の確認）は、自動選択された場合に限り、計画ワークフローを使わずに直接回答します。ユーザーから直接依頼された場合は、計画依頼として扱います。必要であれば確認の質問をしますが、ワークフローを終了してはいけません。

0.2 上流の要件定義書を探す

計画に関する質問をする前に、docs/brainstorms/ で *-requirements.md に一致するファイルを検索します。

関連性の基準： 要件定義書が関連するのは、以下を満たす場合です。

• トピックが機能の説明と意味的に一致している
• 過去30日以内に作成されている（明らかに現在も関連性がある、または明らかに古くなっている場合は、適宜判断してこの条件を覆します）
• 同じユーザーの課題またはスコープを扱っているように見える

複数の参照元ドキュメントが一致する場合は、利用可能であればプラットフォームのブロッキング質問ツールを使って、どれを使用するか尋ねます（「対話方法」を参照）。それ以外の場合は、チャットで番号付きの選択肢を提示し、ユーザーの返答を待ってから進めます。

0.3 参照元ドキュメントを主要な入力として使用する

関連する要件定義書がある場合：

1. 内容を十分に読み込みます
2. それを計画の起点となるドキュメントとして使用することを伝えます
3. 以下のすべてを引き継ぎます。
   • 問題の枠組み
   • 要件と成功基準
   • スコープの境界
   • 重要な決定とその根拠
   • 依存関係または前提条件
   • 未解決の質問（ブロッキングか保留かの区別を維持します）
4. 計画と調査の主要な入力として、参照元ドキュメントを使用します
5. 引き継いだ重要な決定を、計画内で (see origin: <source-path>) の形式で参照します
6. 参照元の内容を黙って省略しないでください。参照元ドキュメントで扱われている内容は、たとえ簡潔であっても計画で取り上げる必要があります。最終化する前に、参照元ドキュメントの各セクションを確認し、抜け落ちがないことを確かめます。

関連する要件定義書がない場合は、ユーザーの依頼を直接もとに計画を進めてかまいません。

0.4 計画の準備（要件定義書がない場合、または入力が不明確な場合）

関連する要件定義書がない場合、または入力をより明確にする必要がある場合：

• 依頼が技術計画を直接立てられるほど明確かどうかを判断します。明確であれば、フェーズ0.5に進みます
• 曖昧さの主な原因が、製品の方向性、ユーザーの行動、またはスコープの定義にある場合は、提案として ce:brainstorm を勧めます。ただし、ここで計画を続ける選択肢も必ず提示します
• ユーザーがここで続けたい場合（または、すでに計画を希望することを明確にしている場合）は、以下の計画準備を行います

計画準備では、以下を明確にします。

• 問題の枠組み
• 想定される動作
• スコープの境界と明らかな対象外事項
• 成功基準
• ブロッキングとなる質問または前提条件

この準備は簡潔にします。完全なブレインストーミングの代わりではなく、直接計画を始めやすくするためのものです。

準備を通じて、未解決の重要な製品上の課題が明らかになった場合：

• 再度 ce:brainstorm を勧めます
• それでもユーザーが続行を希望する場合は、先に明示的な前提条件を設定してもらいます

準備の結果、別のワークフローのほうがユーザーに適しているとわかった場合：

• 根本原因が特定されていない症状（ユーザーが動作不良を説明しているものの、原因を特定していない場合）— 計画の前に調査が必要であることを伝え、ce:debug スキルを読み込みます。計画には解決すべき問題が特定されている必要があります。デバッグによって、その問題を特定します。ルーティングを明確に伝えます。「計画の前に調査が必要です。根本原因を特定するため、ce:debug に切り替えます。」
• 実行可能なことが明確なタスク（根本原因が判明しており、修正が明らかで、アーキテクチャ上の判断が不要な場合）— 計画を続ける選択肢とあわせて、より早く進められる方法として ce:work を提案します。どちらにするかはユーザーが決めます。

0.5 計画の前に未解決の質問を分類する

元のドキュメントに Resolve Before Planning などのブロッキング質問が含まれている場合：

• 先に進む前に、それぞれを確認します
• 実際に技術、アーキテクチャ、または調査に関する質問である場合に限り、計画側が対応する作業に再分類します
• 製品の動作、スコープ、または成功基準を変更する可能性がある場合は、ブロッカーのままにします

製品に関する真のブロッカーが残っている場合：

• それらを明確に提示します
• 利用可能な場合は、プラットフォームのブロッキング質問ツールを使用して（「対話方法」を参照）、次のどちらを行うかユーザーに尋ねます：
  1. ce:brainstorm を再開して解決する
  2. 明示的な前提または決定として扱い、続行する
• 真のブロッカーが未解決のまま、計画を続行してはいけません

0.6 計画の深さを評価する

作業を次のいずれかの計画の深さに分類します：

• 軽量 - 小規模で範囲が明確、曖昧さが少ない
• 標準 - 技術的な決定を文書化する必要がある、通常の機能追加または範囲が限定されたリファクタリング
• 詳細 - 横断的、戦略的、高リスク、または実装内容が非常に曖昧

深さが不明確な場合は、焦点を絞った質問を1つ行ってから続行します。

フェーズ 1：コンテキストの収集

1.1 ローカル調査（常に実行）

調査エージェントへの入力として渡す、簡潔な計画コンテキストの要約（1～2段落）を用意します：

• 元のドキュメントがある場合は、そのドキュメントから問題の枠組み、要件、主要な決定事項を要約します
• ない場合は、機能の説明をそのまま使用します

次のエージェントを並行して実行します：

• Task compound-engineering:research:repo-research-analyst（Scope: technology, architecture, patterns. {planning context summary}）
• Task compound-engineering:research:learnings-researcher（planning context summary）

以下を収集します：

• 技術スタックとバージョン（より的確な外部調査の判断を行うため、セクション 1.2 で使用）
• 踏襲すべきアーキテクチャのパターンと規約
• 実装パターン、関連するファイル、モジュール、テスト
• 計画に実質的な影響を与える AGENTS.md のガイダンス。CLAUDE.md は互換性のための代替として存在する場合にのみ使用
• docs/solutions/ にある組織内の知見

Slack コンテキスト（オプトイン）— 自動的に呼び出してはいけません。条件に応じて次のように対応します：

• ツールが利用可能 + ユーザーが依頼した：計画コンテキストの要約を添えて、他のフェーズ 1.1 エージェントと並行して compound-engineering:research:slack-researcher を呼び出します。元のドキュメントに Slack コンテキストのセクションがある場合は、その内容をそのまま渡し、調査担当者が不足部分に集中できるようにします。調査結果を統合内容に含めます。
• ツールが利用可能 + ユーザーが依頼していない：出力に次のように記載します：「Slack ツールが検出されました。組織内のコンテキストを調査するには、いつでも Slack の検索を依頼するか、次のプロンプトに含めてください。」
• ツールが利用不可 + ユーザーが依頼した：出力に次のように記載します：「Slack コンテキストがリクエストされましたが、利用可能な Slack ツールがありません。組織内のコンテキスト検索を有効にするには、Slack プラグインをインストールして認証してください。」

1.1b 実行方針のシグナルを検出する

計画に軽量な実行方針のシグナルを含めるべきか判断します。

次のようなシグナルを確認します：

• ユーザーが TDD、テストファースト、または特性テストファーストの作業を明示的に依頼している
• 元のドキュメントで、テストファーストの実装やレガシーコードの探索的な強化が求められている
• ローカル調査で、対象領域がレガシー、テストが不十分、または過去に不安定だったと判明し、動作を変更する前に特性テストによるカバレッジが必要と考えられる

シグナルが明確な場合は、関連する実装単位にその方針を暗黙的に引き継ぎます。

方針によって順序やリスクが大きく変わり、責任を持って推測できない場合に限り、ユーザーに尋ねます。

1.2 外部調査を行うか判断する

元のドキュメント、ユーザーからのシグナル、ローカルでの調査結果をもとに、外部調査が役立つか判断します。

行間を読み取ります。 これまでの会話から得られるシグナルに注意してください。

• ユーザーの習熟度 — 特定のファイルやパターンを指摘していますか？コードベースをよく理解している可能性があります。
• ユーザーの意図 — 速度と網羅性のどちらを求めていますか？調査と実行のどちらを求めていますか？
• トピックのリスク — ユーザーからのシグナルにかかわらず、セキュリティ、決済、外部 API にはより慎重に対応する必要があります。
• 不確実性の度合い — 方針は明確ですか、それともまだ定まっていませんか？

repo-research-analyst の技術コンテキストを活用します。

repo-research-analyst の出力には、構造化された「Technology & Infrastructure」の概要が含まれています。これを使って、外部調査を行うかどうかをより的確に判断してください。

• 特定のフレームワークとバージョンが検出された場合（例：Rails 7.2、Next.js 14、Go 1.22）、その正確な識別情報を framework-docs-researcher に渡し、バージョンに対応したドキュメントを取得させます。
• 機能が、スキャンでリポジトリ内に十分な実績があると判明した技術レイヤーに関係する場合（例：新しいバックグラウンドジョブを計画する際に、既存の Sidekiq ジョブがある場合）、外部調査は省略する方向で判断します。ローカルのパターンで十分な可能性があります。
• 機能が、スキャンでリポジトリ内にほとんど存在しない、または不十分だと判明した技術レイヤーに関係する場合（例：新しい gRPC サービスを計画する際に、既存の proto ファイルがない場合）、外部調査を行う方向で判断します。参考にできるローカルのパターンがないためです。
• スキャンでデプロイインフラ（Docker、K8s、サーバーレス）が検出された場合、下流のエージェントがデプロイ上の制約を考慮できるよう、その情報を計画コンテキストに記載します。
• スキャンでモノレポが検出され、特定のサービスに範囲が限定されている場合は、すべてのサービスを集約した情報ではなく、そのサービスの技術コンテキストを下流の調査エージェントに渡します。スキャンでワークスペースの構成が明らかになったものの、範囲が限定されていない場合は、調査に進む前に、機能の説明から関連するサービスを特定します。

次の場合は、必ず外部調査を行う方向で判断します。

• トピックのリスクが高い場合：セキュリティ、決済、プライバシー、外部 API、移行、コンプライアンス
• コードベースに関連するローカルパターンがない場合 — この計画で必要なパターンの直接的な例が 3 件未満
• 隣接する領域のローカルパターンはあるものの、対象の領域そのものにはない場合 — たとえば、コードベースに HTTP クライアントはあるものの webhook レシーバーはない、またはバックグラウンドジョブはあるもののイベント駆動型の pub/sub はない場合。隣接するパターンから、その技術レイヤーにチームが慣れていることは分かりますが、領域固有の落とし穴は把握していない可能性があります。このシグナルがある場合は、一般的な技術ではなく、領域のギャップに焦点を当てて外部調査のクエリを作成します。
• ユーザーが不慣れな領域を調査している場合
• 技術スキャンで、関連するレイヤーがコードベースに存在しない、または不十分だと判明した場合

次の場合は、外部調査を省略します。

• コードベースに強固なローカルパターンがすでにある場合 — 隣接する領域ではなく直接的な例が複数あり、最近も変更され、現在の規約に沿っている
• ユーザーがすでに意図する形を把握している場合
• 外部から追加情報を得ても、実用上の価値がほとんどない場合
• 技術スキャンで、関連するレイヤーがコードベースに十分確立されており、参考にできる例があると判明した場合

続行する前に、判断を簡潔に伝えます。例：

• 「このコードベースには十分なパターンがあるため、外部調査なしで進めます。」
• 「決済処理が含まれるため、まず現在のベストプラクティスを調査します。」

1.3 外部調査（条件付き）

ステップ 1.2 で外部調査が有用と判断された場合、次のエージェントを並行して実行します。

• Task compound-engineering:research:best-practices-researcher(planning context summary)
• Task compound-engineering:research:framework-docs-researcher(planning context summary)

1.4 調査結果の統合

以下を要約します。

• 関連するコードベースのパターンとファイルパス
• 関連する組織内の知見
• 収集した場合は、Slack の会話から得られた組織的背景（機能に関連する過去の議論、決定事項、ドメイン知識）
• 収集した場合は、外部の参考資料とベストプラクティス
• 関連するイシュー、PR、または先行事例
• 計画に実質的な影響を与える制約

1.4b 調査で外部との契約面が判明した場合の深度の再分類

現在の分類が Lightweight で、Phase 1 の調査で作業が以下の外部との契約面のいずれかに関わることが判明した場合は、Standard に再分類します。

• 外部システム、CI、または他のリポジトリが使用する環境変数
• エクスポートされたパブリック API、CLI フラグ、またはコマンドラインインターフェースの契約
• CI/CD 設定ファイル（.github/workflows/、Dockerfile、デプロイスクリプト）
• 下流の利用者がインポートする共有型またはインターフェース
• 外部 URL から参照される、または他のシステムからリンクされているドキュメント

これにより、フロー分析（Phase 1.5）が実行され、信頼度チェック（Phase 5.3）でクリティカルセクションの加点が適用されます。再分類について、簡潔に次のように伝えます。「Standard に再分類します — この変更は、外部の利用者がいる［環境変数／エクスポートされた API／CI 設定］に関わります。」

1.5 フローとエッジケースの分析（条件付き）

Standard または Deep の計画、またはユーザーフローの全体像がまだ不明確な場合は、以下を実行します。

• Task compound-engineering:workflow:spec-flow-analyzer(planning context summary, research findings)

出力を使用して、以下を行います。

• 見落としているエッジケース、状態遷移、または引き継ぎの不備を特定する
• 要件のトレーサビリティまたは検証戦略を強化する
• 計画を実質的に改善するフローの詳細のみを追加する

Phase 2: 計画に関する質問の解決

以下を基に、計画に関する質問の一覧を作成します。

• 元のドキュメントで保留された質問
• リポジトリまたは外部調査で見つかった不足事項
• 有用な計画を作成するために必要な技術的決定

質問ごとに、次のどちらに該当するか判断します。

• 計画中に解決 — リポジトリのコンテキスト、ドキュメント、またはユーザーの選択から回答を得られる
• 実装時に保留 — コード変更、実行時の挙動、または実行時の調査結果に依存する

回答がアーキテクチャ、スコープ、順序、またはリスクに実質的な影響を与え、責任を持って推測できない場合に限り、ユーザーに質問します。利用可能な場合は、プラットフォームのブロッキング質問ツールを使用します（「対話方法」を参照）。

このフェーズでは、テストの実行、アプリのビルド、または実行時の挙動の調査を行わないでください。目的は、部分的な実行ではなく、十分な計画を作成することです。

Phase 3: 計画の構成

3.1 タイトルとファイル名

• feat: Add user authentication や fix: Prevent checkout double-submit のような一般的な形式を使い、明確で検索しやすいタイトルを作成します
• 計画の種類を判断します。feat、fix、または refactor
• リポジトリの規則に従ってファイル名を作成します。docs/plans/YYYY-MM-DD-NNN-<type>-<descriptive-name>-plan.md
  • 存在しない場合は docs/plans/ を作成します
  • 今日の日付の既存ファイルを確認し、次の連番を決定します（3 桁のゼロ埋め、001 から開始）
  • 説明名は簡潔に（3～5 語）、kebab-case にします
  • 例：2026-01-15-001-feat-user-authentication-flow-plan.md、2026-02-03-002-fix-checkout-race-condition-plan.md
  • 避けるべき例：連番の欠落、「new-feature」のような曖昧な名前、無効な文字（コロン、スペース）

3.2 ステークホルダーと影響への配慮

Standard または Deep の計画では、この変更の影響を受ける対象（エンドユーザー、開発者、運用担当者、他のチーム）と、それが計画にどう影響するかを簡潔に検討します。複数の領域にまたがる作業では、「システム全体への影響」セクションに影響を受ける関係者を記載します。

3.3 作業を実装単位に分割する

作業を論理的な実装単位に分割します。各単位は、実装者が通常、アトミックなコミットとして取り込める意味のある変更を表す必要があります。

適切な単位は、次のとおりです。

• 1つのコンポーネント、動作、または統合境界に焦点を当てている
• 通常、関連する少数のファイル群に変更が限定されている
• 依存関係の順に並んでいる
• コードを事前に書かなくても実行できるほど具体的である
• 進捗管理のため、チェックボックス構文で示されている

次のような単位は避けます。

• 2～5分で終わるような細かすぎるステップ
• 複数の無関係な懸念事項にまたがる単位
• 曖昧すぎて、実装者が計画を考案しなければならない単位

3.4 高レベルの技術設計（任意）

実装単位の詳細を記述する前に、概要を示すことで、レビュー担当者が意図したアプローチを検証しやすくなるかどうかを判断します。このセクションでは、実装方法を細かく指定することなく、解決策の全体像、つまり各要素がどのように組み合わさるかを伝えます。

次の場合は含めます。

作業の内容...	最適な概要形式
DSL または API サーフェスの設計	疑似コードの文法またはコントラクトの概要
複数コンポーネントの統合	Mermaid のシーケンス図またはコンポーネント図
データパイプラインまたは変換	データフローの概要
状態が複雑なライフサイクル	状態図
複雑な分岐ロジック	フローチャート
モード／フラグの組み合わせ、または複数入力に対する動作	決定マトリックス（入力 -> 結果）
単一コンポーネントで全体像が直感的でない場合	疑似コードの概要

次の場合は省略します。

• 実績のあるパターンに従う作業で、説明文とファイルパスだけで全体を把握できる
• 典型的な CRUD や規約に沿った変更
• アプローチが明白な軽量な計画

作業に適した形式を選びます。図のほうが伝わりやすい場合に疑似コードを既定で選んだり、その逆を行ったりしないでください。

すべての概要には、次の文を添えます。"これは意図したアプローチを示すもので、レビューのための方向性を示すガイダンスであり、実装仕様ではありません。実装を行うエージェントは、再現すべきコードではなく、背景情報として扱ってください。"

概要は簡潔に保ち、方向性を検証するのに十分な内容にとどめ、本番環境にそのままコピー＆ペーストできるほど詳細にはしません。

3.4b 出力構成（任意）

新しいディレクトリ構成（新規プラグイン、サービス、パッケージ、またはモジュール）を作成するグリーンフィールド計画では、想定される構成を示すファイルツリーを含む ## Output Structure セクションを追加します。これにより、各単位の詳細を確認する前に、全体像を把握できます。

次の場合は含めます。

• 新しいディレクトリ階層に3つ以上のファイルを作成する計画
• ディレクトリ構成自体が重要な設計判断である場合

次の場合は省略します。

• 既存のファイルのみを変更する計画
• 既存のディレクトリに1～2個のファイルを作成する計画（各単位のファイル一覧で十分です）

ツリーは、想定される出力の形を示すスコープ宣言です。制約ではありません。実装の過程でより適切な構成が分かった場合、実装者は構成を調整できます。各単位の **Files:** セクションは、各単位で作成または変更する対象を示すものとして、引き続き優先されます。

3.5 各実装単位を定義する

各単位には、以下を含めてください。

• Goal - この単位で達成すること
• Requirements - この単位が前進させる要件または成功基準
• Dependencies - 先に存在している必要があるもの
• Files - 作成、変更、テストするリポジトリ相対のファイルパス（絶対パスは使用しないでください）
• Approach - 主な判断、データフロー、コンポーネントの境界、または統合に関する注記
• Execution note - 任意。この単位で、テストファーストや特性の把握を優先するなど、標準とは異なる実行方針が有効な場合に限ります
• Technical design - 任意。この単位のアプローチが自明でなく、文章だけでは曖昧さが残る場合の擬似コードまたは図。実装仕様ではなく、方向性を示す指針であることを明示してください
• Patterns to follow - 踏襲する既存コードや規約
• Test scenarios - 実装者が作成する具体的なテストケースを、この単位の複雑さとリスクに見合った数だけ列挙します。以下の各カテゴリを検討し、この単位に該当するすべてのカテゴリからシナリオを含めてください。単純な設定変更ならシナリオは1つで十分な場合もありますが、決済フローでは十数個必要な場合もあります。品質の指標は具体性です。各シナリオには入力、操作、期待される結果を明記し、実装者がテスト範囲を考案する必要がないようにしてください。振る舞いに変更のない単位（純粋な設定、足場作り、スタイル変更）では、フィールドを空欄のままにせず、代わりに Test expectation: none -- [reason] を使用してください。
  • 正常系の振る舞い - 期待される入出力を伴う主要な機能
  • エッジケース（この単位に意味のある境界条件がある場合） - 境界値、空の入力、nil/null 状態、同時アクセス
  • エラーおよび失敗経路（この単位に失敗する可能性がある場合） - 無効な入力、下流サービスの障害、タイムアウトの挙動、権限拒否
  • 統合シナリオ（この単位がレイヤーをまたぐ場合） - モックだけでは検証できない振る舞い。例：「X を作成するとコールバック Y が呼び出され、Z が永続化される」。コールバック、ミドルウェア、または複数レイヤー間の連携に関わる単位では、これらを含めてください
• Verification - 実装者が単位の完了を判断する方法。シェルコマンドのスクリプトではなく、達成される結果として表現してください

機能を含むすべての単位で、**Files:** にテストファイルのパスを含めてください。

Execution note は必要な場合に限って使用してください。適切な例：

• Execution note: Start with a failing integration test for the request/response contract.
• Execution note: Add characterization coverage before modifying this legacy parser.
• Execution note: Implement new domain behavior test-first.

単位を RED/GREEN/REFACTOR の個別ステップに展開しないでください。

3.6 計画時の未確定事項と実装時の未確定事項を分ける

重要であっても、現時点では判断できないことがある場合、計画で解決したかのように扱わず、実装時に先送りする注記として明示してください。

例：

• 正確なメソッド名やヘルパー名
• 実際のコードに手を入れた後で決まる最終的な SQL やクエリの詳細
• 実際のテスト失敗を確認してから決まる実行時の挙動
• 実装開始後に不要と判明する可能性のあるリファクタリング

フェーズ 4：計画を作成する

すべての深度で、同じ計画方針を採用してください。計画と実行の境界を変えるのではなく、詳細の量を調整します。

4.1 計画の深度に関する指針

軽量

• 計画を簡潔に保ちます
• 通常は実装単位を2～4個にします
• 価値の低い任意のセクションは省略します

標準

• 今回の作業に価値のない任意のセクション（High-Level Technical Design を含む）を省き、コアテンプレートをすべて使用します
• 通常は実装単位を3～6個にします
• 関連する場合は、リスク、先送りする質問、システム全体への影響を含めます

詳細

• 必要に応じて任意の分析セクションを追加し、コアテンプレートをすべて使用します
• 通常は実装単位を4～8個にします
• 明確になる場合は、単位をフェーズに分けます
• 必要に応じて、検討した代替案、ドキュメントへの影響、より詳細なリスクへの対応を含めます

4.1b 任意の詳細プラン拡張

十分に大規模、リスクが高い、または横断的な作業では、本当に役立つセクションを追加してください:

• 検討した代替アプローチ
• 成功指標
• 依存関係 / 前提条件
• リスク分析と緩和
• 段階的デリバリー
• ドキュメント計画
• 運用 / ロールアウトに関する注記
• 将来の検討事項 — 現在の設計に実質的に影響する場合のみ

これらを定型文として追加しないでください。実行品質やステークホルダーの合意形成を改善する場合にのみ含めてください。

4.2 コアプランテンプレート

明らかに該当しない任意セクションは省略してください。特に軽量プランの場合は省略してください。

---
title: [Plan Title]
type: [feat|fix|refactor]
status: active
date: YYYY-MM-DD
origin: docs/brainstorms/YYYY-MM-DD-<topic>-requirements.md  # include when planning from a requirements doc
deepened: YYYY-MM-DD  # optional, set when the confidence check substantively strengthens the plan
---

# [Plan Title]

## Overview

[What is changing and why]

## Problem Frame

[Summarize the user/business problem and context. Reference the origin doc when present.]

## Requirements Trace

- R1. [Requirement or success criterion this plan must satisfy]
- R2. [Requirement or success criterion this plan must satisfy]

## Scope Boundaries

- [Explicit non-goal or exclusion]


### Deferred to Separate Tasks

- [Work that will be done separately]: [Where or when -- e.g., "separate PR in repo-x", "future iteration"]

## Context & Research

### Relevant Code and Patterns

- [Existing file, class, component, or pattern to follow]

### Institutional Learnings

- [Relevant `docs/solutions/` insight]

### External References

- [Relevant external docs or best-practice source, if used]

## Key Technical Decisions

- [Decision]: [Rationale]

## Open Questions

### Resolved During Planning

- [Question]: [Resolution]

### Deferred to Implementation

- [Question or unknown]: [Why it is intentionally deferred]


## Output Structure

    [directory tree showing new directories and files]


## High-Level Technical Design

> *This illustrates the intended approach and is directional guidance for review, not implementation specification. The implementing agent should treat it as context, not code to reproduce.*

[Pseudo-code grammar, mermaid diagram, data flow sketch, or state diagram — choose the medium that best communicates the solution shape for this work.]

## Implementation Units

- [ ] **Unit 1: [Name]**

**Goal:** [What this unit accomplishes]

**Requirements:** [R1, R2]

**Dependencies:** [None / Unit 1 / external prerequisite]

**Files:**
- Create: `path/to/new_file`
- Modify: `path/to/existing_file`
- Test: `path/to/test_file`

**Approach:**
- [Key design or sequencing decision]

**Execution note:** [Optional test-first, characterization-first, or other execution posture signal]

**Technical design:** *(optional -- pseudo-code or diagram when the unit's approach is non-obvious. Directional guidance, not implementation specification.)*

**Patterns to follow:**
- [Existing file, class, or pattern]

**Test scenarios:**

- [Scenario: specific input/action -> expected outcome. Prefix with category — Happy path, Edge case, Error path, or Integration — to signal intent]

**Verification:**
- [Outcome that should hold when this unit is complete]

## System-Wide Impact

- **Interaction graph:** [What callbacks, middleware, observers, or entry points may be affected]
- **Error propagation:** [How failures should travel across layers]
- **State lifecycle risks:** [Partial-write, cache, duplicate, or cleanup concerns]
- **API surface parity:** [Other interfaces that may require the same change]
- **Integration coverage:** [Cross-layer scenarios unit tests alone will not prove]
- **Unchanged invariants:** [Existing APIs, interfaces, or behaviors that this plan explicitly does not change — and how the new work relates to them. Include when the change touches shared surfaces and reviewers need blast-radius assurance]

## Risks & Dependencies

| Risk | Mitigation |
|------|------------|
| [Meaningful risk] | [How it is addressed or accepted] |

## Documentation / Operational Notes

- [Docs, rollout, monitoring, or support impacts when relevant]

## Sources & References

- **Origin document:** [docs/brainstorms/YYYY-MM-DD-<topic>-requirements.md](path)
- Related code: [path or symbol]
- Related PRs/issues: #[number]
- External docs: [url]

より大規模な Deep プランでは、有用な場合にのみ、次のようなセクションでコアテンプレートを拡張してください:

## Alternative Approaches Considered

- [Approach]: [Why rejected or not chosen]

## Success Metrics

- [How we will know this solved the intended problem]

## Dependencies / Prerequisites

- [Technical, organizational, or rollout dependency]

## Risk Analysis & Mitigation

| Risk | Likelihood | Impact | Mitigation |
|------|-----------|--------|------------|
| [Risk] | [Low/Med/High] | [Low/Med/High] | [How addressed] |

## Phased Delivery

### Phase 1
- [What lands first and why]

### Phase 2
- [What follows and why]

## Documentation Plan

- [Docs or runbooks to update]

## Operational / Rollout Notes

- [Monitoring, migration, feature flag, or rollout considerations]

4.3 プランニングのルール

• すべてのファイルパスはリポジトリ相対でなければなりません — /Users/name/Code/project/src/file.ts のような絶対パスは決して使用しないでください。代わりに src/file.ts を使用してください。絶対パスは、プランをマシン、ワークツリー、チームメイト間でポータブルでなくします。プランがドキュメントのあるリポジトリとは異なるリポジトリを対象とする場合は、プランの先頭で対象リポジトリを一度示し(例: **Target repo:** my-other-project)、全体を通してリポジトリ相対パスを使用してください
• 脆い行番号よりも、パスとクラス/コンポーネント/パターンの参照を優先してください
• 進捗を追跡できるよう、実装単位は - [ ] 構文でチェック可能に保ってください
• 実装コードを含めないでください — インポート、正確なメソッドシグネチャ、フレームワーク固有の構文は含めないでください
• 疑似コードのスケッチと DSL 文法は、設計の方向性を伝える場合、High-Level Technical Design セクションおよび各単位の技術設計フィールドで許可されます。実装仕様ではなく、方向性のガイダンスとして明示的に位置づけてください
• 散文だけでは追いにくい関係やフローを明確にする場合、Mermaid 図を推奨します — データモデル変更には ERD、複数サービス間のやり取りにはシーケンス図、ライフサイクル遷移には状態図、複雑な分岐ロジックにはフローチャート
• git コマンド、コミットメッセージ、正確なテストコマンドのレシピを含めないでください
• 実装単位を micro-step の RED/GREEN/REFACTOR 指示に展開しないでください
• プランを完全に見せるためだけに、実行時の問いが解決済みであるかのように装わないでください

4.4 プランドキュメントにおける視覚的コミュニケーション

プランに非線形な依存関係を持つ 4 つ以上の実装単位、System-Wide Impact に 3 つ以上の相互作用するサーフェス、Overview または Problem Frame に 3 つ以上の動作モード/バリアント、または Key Technical Decisions に 3 つ以上の相互作用する決定あるいは Alternative Approaches に 3 つ以上の代替案が含まれる場合は、図と表のガイダンスについて references/visual-communication.md を読んでください。これはプラン構造のビジュアル(依存関係グラフ、相互作用図、比較表)を扱います — ソリューション設計の図は対象外で、それらはセクション 3.4 で扱います。

フェーズ 5: 最終レビュー、ファイル書き込み、ハンドオフ

5.1 作成前の確認

最終版を確定する前に、以下を確認します。

• ce:brainstorm で定義されるべきプロダクトの動作を、計画で作り上げていない
• 起点となる文書がなかった場合、範囲を限定した計画立案の準備によって、責任を持って計画を立てられるだけのプロダクトの明確さが確保されている
• すべての主要な判断が、起点となる文書または調査に根拠を置いている
• 各実装単位が具体的で、依存関係の順序が整理され、実装に着手できる状態になっている
• テストファーストまたは特性評価ファーストの方針が明示されているか、強く示唆されている場合、該当する単位に簡潔な Execution note を引き継いでいる
• 機能を伴う各単位に、該当するすべてのカテゴリ（正常系、エッジケース、エラー経路、統合）のテストシナリオが含まれている。単位の複雑さに応じた適切な量とし、過剰にも不足にもなっていない
• テストシナリオには、具体的な入力、操作、期待される結果が記載されており、テストコードにはなっていない
• テストシナリオが空欄または欠落している機能を伴う単位には、未完了の印が付いている。機能を伴う単位には、注記だけでなく実際のテストシナリオが必要。Test expectation: none -- [reason] の注記が有効なのは、機能を伴わない単位（設定のみ、足場づくり、スタイル設定）の場合に限る
• 延期項目が明示されており、確定事項を装って隠されていない
• 高レベル技術設計のセクションを含める場合、作業に適した形式を使い、規範的にならない表現を保ち、実装コード（インポート、正確なシグネチャ、フレームワーク固有の構文など）を含めていない
• 単位ごとの技術設計フィールドがある場合、コピーしてそのまま使えるほど詳細にせず、簡潔で方向性を示す内容になっている
• 計画で新しいディレクトリ構成を作成する場合、全体像をレビュー担当者に伝えるうえで、出力構成ツリーが役立つか
• スコープ境界に、別のPRまたはタスクで予定されている作業項目を含めている場合、それらが真の非目標と混在せず、### Deferred to Separate Tasks の下に記載されている
• 視覚的な補助資料（依存関係グラフ、相互作用図、比較表）があると、文章を読むより早く計画の構成を把握できるか

計画が要件文書を起点としている場合は、その文書を再度読み、以下を確認します。

• 選択したアプローチが、引き続きプロダクトの意図に合っている
• スコープ境界と成功基準が維持されている
• 阻害要因となる質問が解決済みか、明示的な仮定として扱われているか、ce:brainstorm に差し戻されている
• 起点となる文書のすべてのセクションが計画で扱われている。各セクションを確認し、何かが気付かれないまま抜け落ちていないか確かめる

5.2 計画ファイルの作成

必須：選択肢を提示する前に、計画ファイルをディスクに書き込みます。

Write ツールを使用して、計画全体を次の場所に保存します。

docs/plans/YYYY-MM-DD-NNN-<type>-<descriptive-name>-plan.md

以下を確認します。

Plan written to docs/plans/[filename]

パイプラインモード： LFG、SLFG などの自動ワークフロー、または disable-model-invocation のコンテキストから呼び出された場合は、対話形式の質問を省略します。必要な選択を自動的に行い、計画の書き込みに進みます。

5.3 確信度の確認と深化

計画ファイルの作成後、計画を強化する必要があるかどうかを自動的に評価します。

2 つの深化モード：

• 自動モード（計画生成時のデフォルト）：ユーザーの承認を求めずに実行されます。ユーザーには強化内容が表示されますが、判断する必要はありません。サブエージェントの調査結果は、計画に直接反映されます。
• 対話モード（フェーズ 0.1 の再深化ファストパスで有効化）：ユーザーが既存の計画の深化を明示的に依頼した場合に有効になります。サブエージェントの調査結果は、反映前に個別に提示され、レビューできます。ユーザーは各エージェントの調査結果を承認、却下、または議論できます。承認された調査結果のみが計画に反映されます。

オンデマンドの深化では、ユーザーの姿勢が異なるため、対話モードが用意されています。ユーザーはすでに計画に思い入れがあり、変更点を慎重に選びたいと考えています。この仕組みは、計画がこのスキルで生成されたものか、手作業で作成されたものか、別のツールで作成されたものかを問わず適用されます。

document-review とこの確信度チェックは別のものです。

• 文書の明瞭さ、簡潔さ、完全性、またはスコープの管理が必要な場合は、document-review スキルを使用します
• 計画の構成は妥当でも、根拠、順序付け、リスクへの対処、システム全体を考慮した検討を強化する必要がある場合は、この確信度チェックを使用します

パイプラインモード： パイプライン／モデル呼び出し無効化のコンテキストでは、このフェーズは常に自動モードで実行されます。ユーザーとのやり取りは不要です。

5.3.1 計画の深さとトピックのリスクを分類する

文書から計画の深さを判定します。

• 軽量 - 小規模で範囲が限定され、曖昧さが少ないもの。通常は実装単位が 2〜4 個
• 標準 - 中程度の複雑さで、技術的な判断をいくつか伴うもの。通常は実装単位が 3〜6 個
• 詳細 - 複数の領域にまたがる、リスクが高い、または戦略的に重要な作業。通常は実装単位が 4〜8 個、または段階的なリリース

リスクプロファイルを作成します。次の項目は高リスクの兆候として扱います。

• 認証、認可、またはセキュリティ上重要な動作
• 決済、請求、または金融フロー
• データ移行、バックフィル、または永続データの変更
• 外部 API またはサードパーティとの連携
• プライバシー、コンプライアンス、またはユーザーデータの取り扱い
• インターフェース間の一貫性、または複数のサーフェスにまたがる動作
• 大規模なロールアウト、監視、または運用上の懸念

5.3.2 ゲート：深化するかどうかを判断する

• 軽量な計画は、リスクが高い場合を除き、通常は深化する必要はありません
• 標準の計画は、重要なセクションが薄いままの場合、深化すると有益なことがよくあります
• 詳細または高リスクの計画は、対象を絞った 2 回目の確認が有益なことがよくあります
• ローカルな根拠が薄い場合の例外規則： フェーズ 1.2 で、ローカルのパターンが乏しい（直接的な例が 3 件未満、または隣接領域との一致にとどまる）ことを理由に外部調査が実施された場合は、計画がどれほど十分な根拠に基づいているように見えても、必ずスコアリングに進みます。なじみのない領域に基づいて計画を作成した場合、システムの動作に関する主張は、検証済みの事実ではなく仮定である可能性が高くなります。スコアリングは低コストです。計画が本当に堅実であれば、スコアリングでは何も見つからず、すぐに終了します

計画にすでに十分な根拠があるように見え、ローカルな根拠が薄い場合の例外規則にも該当しない場合は、「確信度チェックに合格しました — 強化が必要なセクションはありません」と報告し、フェーズ 5.3.8（ドキュメントレビュー）に進みます。深化が必要だったかどうかにかかわらず、ドキュメントレビューは常に実行されます。2 つのツールは、異なる種類の問題を検出するためです。

5.3.3〜5.3.7 深化の実行

深化が妥当な場合は、references/deepening-workflow.md を読み、確信度スコアリングのチェックリスト、セクションとエージェントの割り当て方法、実行モードの選択、調査の実行、調査結果の対話的レビュー、および計画への反映方法を確認します。そのファイルに記載された手順 5.3.3〜5.3.7 を実行した後、ここに戻って 5.3.8 に進みます。

5.3.8–5.4 ドキュメントレビュー、最終チェック、生成後のオプション

このフェーズに進んだら、references/plan-handoff.md を読み、ドキュメントレビューの手順（5.3.8）、最終チェックとクリーンアップ（5.3.9）、生成後のオプションメニュー（5.4）、および Issue の作成について確認してください。このファイルは、それより前に読み込まないでください。ドキュメントレビューは必須です。信頼度チェックがすでに実行されていても、省略しないでください。

コードは絶対に書かないでください！調査し、決定し、計画を作成してください。