execute

実行

目的

専用のサブエージェントを使い、各ステップを厳格なビルド、レビュー、検証のサイクルに沿って進めて、ブループリントの計画を実行します。実装、レビュー、検証の負荷が高い作業はサブエージェントに任せ、メインの会話はオーケストレーションとユーザーの判断に集中させ、簡潔に保ちます。完了と見なして次に進む前に、各ステップがすべての受け入れ基準を満たしていることを確認します。

労力レベル

各フェーズは、正しく仕上げる唯一の機会として取り組みます。ビルドは下書きではなく、完全な実装でなければなりません。レビューは真に厳しい視点で行う必要があります。検証では、すべてのツールを実行し、すべての結果を確認します。3つのフェーズすべてに合格した後、そのステップのコードは本番環境に対応できる状態になっているはずです。

ワークフロー

計画の確認

docs/plans/ 内の計画ファイルを調べます。計画ファイルが1つだけの場合は、それを使用します。計画ファイルまたはマイルストーンフォルダーが複数ある場合は、一覧をユーザーに提示し、どれを実行するか尋ねます。番号付きのステップファイルを含むマイルストーンフォルダーの場合は、チェックマークが付いていない最初のステップから始めます。ユーザーのリクエストで計画ファイルが直接指定されている場合（例：「01_milestone_name.md を実行」）、確認せずにそのファイルを使用します。

実行を始める前に、計画ファイル全体をコンテキストに読み込みます。すべてのステップ見出し、各フェーズの指示（フェーズ1：ビルド、フェーズ2：レビュー、フェーズ3：検証）、およびステップ間の依存関係を特定します。ステップの総数と、すでに完了としてマークされているステップ数を数え、実行を始めるか確認する前にユーザーへ報告します。

ユーザーが特定のステップだけの実行を求めた場合（例：「ステップ3～5を実行」または「ステップ2をスキップ」）、そのリクエストに従い、指定されたステップだけを順番に実行し、それ以外はスキップします。スキップするステップに、指定されたステップが必要とする依存関係が含まれている場合は警告します。

Git の処理

最初のステップを実行する前に、どの git モードを使用するかユーザーに尋ねてください。次の 2 つの選択肢をそのまま提示します。

ユーザー管理モード：

• 各ステップで 3 つのフェーズ（ビルド、レビュー、検証）がすべて完了したら、一時停止します。
• ユーザーが変更を確認し、任意のタイミングでファイルをステージングしてコミットします。
• コミットを自動的に作成してはいけません。
• ユーザーが明示的に続行するよう指示するまで、実行を再開してはいけません。
• ステップをまとめて実行する場合も、バッチ内の各ステップが完了するたびに一時停止します。バッチの区切りは進捗をまとめて確認するチェックポイントとして機能します。バッチの最終ステップ後にバッチの概要を提示しますが、ユーザーは各ステップの後にすでに確認する機会を得ています。

スキル管理モード：

• 各ステップで 3 つのフェーズすべてに合格したら、コミットを自動的に作成します。
• ステップで人間の介入が必要な場合（レビューでブロッキング対象となる指摘があった場合、または検証チェックに失敗した場合）、介入が完全に解決され、残りのフェーズすべてに合格するまで、そのステップの変更をコミットしてはいけません。部分的なステップをコミットすることはありません。
• プランファイルの進捗更新（✅ 付きの見出しとチェック済みのチェックボックス）は、ステップの実装変更と同じコミットに含めてください。プランの進捗だけを別のコミットにしてはいけません。
• ステップを参照した、わかりやすく具体的な Conventional Commits 形式のコミットメッセージを使用します。
• コミットメッセージに Claude Code や AI に関する帰属情報を含めてはいけません。Co-authored-by の行、ボットの署名、AI への言及は一切含めません。
• 一時停止の頻度は、プランの複雑さによって異なります。
  • シンプルなプラン（単一のドキュメント）： 一時停止せずにすべてのステップを続けて実行します。プラン完了後に最終概要を提示します。
  • 複雑なプラン（複数のマイルストーンドキュメント）： ユーザーがスキル管理モードを選択した後、どの一時停止の頻度にするか尋ねます。
    • マイルストーンごとに一時停止（デフォルト）：マイルストーンドキュメントが完了するたびに一時停止します。マイルストーンの概要を提示し、次のマイルストーンに進むかユーザーに尋ねます。マイルストーン内では、バッチの区切りで一時停止せず、すべてのステップを続けて実行します。
    • 全自動： マイルストーンの区切りを含め、プラン全体を一時停止せずに実行します。プラン完了後に最終概要を提示します。

ユーザーが選択した内容（git モード、および複雑なプランでスキル管理モードを選択した場合は一時停止の頻度）を保存し、実行セッションの残りの期間を通じて一貫して適用します。ユーザーがセッションの途中でモードを切り替える場合は、その旨を明示的に伝える必要があります。毎回必ず尋ねてください。以前のセッションで選択したモードや一時停止の頻度を推測してはいけません。

ステップの実行

ステップを最大3つまでのバッチにまとめます。バッチ内のステップは必ず直列に実行します。ステップAは、ビルド、レビュー、検証の全フェーズを完了し、すべてに合格してから、ステップBのビルドフェーズを開始します。バッチ内の実行順序は常に次のとおりです。

1. ステップA：ビルド → レビュー → 検証（すべて合格すること）
2. ステップB：ビルド → レビュー → 検証（すべて合格すること）
3. ステップC：ビルド → レビュー → 検証（すべて合格すること）

ビルドをまとめて実行してはいけません。レビューをまとめて実行してはいけません。検証をまとめて実行してはいけません。ステップAのレビューまたは検証が保留中の間に、ステップBのビルドを開始してはいけません。各フェーズが次のフェーズへのゲートになります。各ステップが次のステップへのゲートになります。

バッチが完了したら（バッチ内のすべてのステップがすべてのフェーズに合格したら）、選択したモードに従ってGitを処理し、その後、完了したステップを示すバッチの概要をユーザーに提示します。ユーザー管理モードでは、各ステップの後にすでに一時停止しています。スキル管理モードでは、一時停止のタイミングに達していない限り、一時停止せずに次のバッチへ進みます（一時停止のタイミングとは、マイルストーンでの一時停止の場合はマイルストーンの境界、シンプルなプランとフルオートの場合はプランの終了時です）。

バッチはマイルストーンの境界をまたいではいけません。現在のマイルストーンに残りのステップが2つあり、次のマイルストーンにもステップがある場合、現在のバッチにはその2ステップだけを含めます。プランの残りステップ数がバッチサイズより少ない場合、バッチには残りのステップだけを含めます。バッチ内でステップが失敗した場合、そのバッチの残りのステップは実行せず、失敗を報告して指示を待ちます。

サブエージェントのディスパッチ

Claude Code の Agent ツールを使用してサブエージェントをディスパッチします。正確なプロンプトテンプレートは references/subagent-prompts.md を参照してください。プレースホルダーには、ディスパッチ前に実際の値を代入します。

ビルドサブエージェントのディスパッチ：

• プランのステップの目的テキストをそのまま {{STEP_OBJECTIVE}} に渡します。
• プランのステップの受け入れ条件リストをそのまま {{ACCEPTANCE_CRITERIA}} に渡します。
• プランのステップのフェーズ1の指示をそのまま {{PHASE_1_INSTRUCTIONS}} に渡します。
• ビルドサブエージェントには、ファイルの読み取りと書き込みを行うためのファイルシステムへのフルアクセスを与えます。
• サブエージェントの応答から、構造化されたビルド概要を取得します。

レビューサブエージェントのディスパッチ：

• プランのステップの受け入れ条件リストをそのまま {{ACCEPTANCE_CRITERIA}} に渡します。
• 取得したビルド概要を {{BUILD_SUMMARY}} に渡します。
• プランのステップのフェーズ2の指示をそのまま {{PHASE_2_INSTRUCTIONS}} に渡します。
• レビューサブエージェントはディスクから独立してファイルを読み取ります。ビルド概要は方向づけと確認ポイントの参考情報として提供しますが、信頼できる事実情報としては扱いません。
• レビューの応答を解析し、ブロッキング項目を特定します。

検証サブエージェントのディスパッチ：

• プランのステップのフェーズ3のチェックリストをそのまま {{PHASE_3_CHECKLIST}} に渡します。
• プランのツールチェーン設定（テストランナー、リンター、型チェッカーのコマンド）を {{TOOL_CHAIN_CONFIG}} に渡します。ツールチェーンはプランの「ツールチェーン」テーブルから抽出します。プランニング中にユーザーが確認済みであり、これが正規の情報源です。プランに「ツールチェーン」テーブルがない場合は、代替手段としてプロジェクトの設定ファイル（pyproject.toml、package.json、Makefile など）から検出します。解決した設定をキャッシュし、プランでツールチェーンの要件が明示的に変更されない限り、以降の検証ディスパッチでも再利用します。
• 検証サブエージェントは実際のツールを実行し、チェックリスト項目ごとに合否を報告します。
• 検証の応答を解析して失敗項目を特定します。チェックが1つでも失敗した場合、検証フェーズ全体が失敗となります。

失敗時の対応

レビューサブエージェントがブロッキングの指摘を返した場合は、直ちに停止してください。検証に進まないでください。自動修正を試みないでください。ビルドを再試行しないでください。このステップでの変更をコミットしないでください。ファイル名と行番号、および説明を添えて、ブロッキングの指摘をすべてユーザーに提示してください。次の進め方についてユーザーから指示があるまで待機してください。ユーザーは次のいずれかを選択できます。

• 問題を手動で修正し、レビューの再実行を依頼する。
• 追加の指示を付けて、スキルにビルドの再実行を依頼する。
• このステップをスキップする（完了ではなく、スキップとしてマークする）。
• 実行全体を中止する。

検証サブエージェントが失敗したチェックを返した場合は、直ちに停止してください。次のステップに進まないでください。自動修正を試みないでください。このステップでの変更をコミットしないでください。完全なエラー出力を含む、失敗の詳細をすべてユーザーに提示してください。ユーザーから指示があるまで待機してください。選択肢は、ブロッキングの指摘の場合と同じです。

ユーザーが介入に対処した（手動修正、ビルドの再実行など）後は、失敗した時点から残りのフェーズを再実行してください。3つのフェーズすべてに問題なく合格した場合に限り、そのステップをコミットしてください。コミットには、中間の試行ではなく、最終的に解決された状態を記録します。

助言的なレビューの指摘は実行を妨げません。そのステップがすべてのフェーズに合格した後、情報としてユーザーに提示してください。ユーザーは後で対処することも、無視することもできます。

3つのフェーズすべてに合格して完了とマークされたステップは、他のステップで後から失敗が発生しても、チェックマークを維持します。ステップ B の失敗によって、ステップ A が未完了に戻ることはありません。

進捗管理

ステップが3つのフェーズ（ビルド、レビュー、検証）すべてに合格した直後に、計画ファイルを2か所更新して完了とマークしてください。

1. ステップ見出しの先頭にチェックマークを付けます。たとえば、### Step 1: Auth middleware を ### ✅ Step 1: Auth middleware に変更します。
2. 完了したステップ内にあるすべての Markdown チェックボックスを、- [ ] から - [x] に変更してチェック済みにします。フェーズ 3 の検証チェックリスト内、およびステップ内のその他すべてのチェックボックスが対象です。

進捗がセッションをまたいで保持されるように、両方の変更を計画ファイルに書き込み、ディスクに保存してください。再開時は、計画ファイルを確認し、✅ が付いていない最初のステップ見出しから実行を開始します。

以前ユーザーが実行を一時停止していた場合（ユーザー管理の Git モード）は、再開時に計画ファイル全体を読み直してください。一時停止中にユーザーが計画を編集している可能性があります。ステップの追加、削除、並べ替え、指示の変更などが行われている場合があります。再開時点の計画ファイルの内容を尊重してください。

再開時の計画変更

実行を再開するときは、必ずディスクから計画ファイルを読み直してください。以前のセッションや会話の前半で取得した計画のキャッシュを使わないでください。ユーザーは次の変更を加えている可能性があります。

• レビューの指摘に基づいてステップの指示を編集した。
• 既存のステップの間に新しいステップを追加した。
• 不要になったステップを削除した。
• 依存関係を考慮してステップを並べ替えた。
• 受け入れ基準や検証チェックリストを変更した。

再開時点の計画をそのまま受け入れてください。ステップの依存関係が壊れているように見える場合（たとえば、削除されたステップの成果物を参照している場合）を除き、変更について警告したり、疑問を呈したりしないでください。

ステップレポート

各ステップで3つのフェーズがすべて完了した後、ステップレポートを提示します。詳細度は実行モードによって異なります。

• ユーザー管理モード（各ステップの後に一時停止）：ステップのラベルとステータス、変更されたファイル数、ブロッキング指摘と参考指摘の件数（参考指摘がある場合は簡潔に列挙）、検証結果の概要（N/N件のチェックに合格）、および実行したGit操作（一時停止してユーザーの操作を待機）を含む、完全なステップレポートを提示します。
• スキル管理の継続モード（シンプルなプラン、またはフルオート）：各ステップのレポートは、ステップのラベル、ステータス、変更されたファイル数、検証結果、コミットハッシュを含む1行にまとめます。実行の最後に、包括的な概要を提示します。
• スキル管理のマイルストーン一時停止：マイルストーン内の各ステップには、1行にまとめた形式を使用します。一時停止するたびに、マイルストーンの完全な概要を提示します。

バッチが完了した後、バッチ内で完了したすべてのステップと累積統計を記載したバッチ概要を提示します。