execute-plan

計画の実行

概要

事前承認済みの計画を、スコープ、順序、検証を厳守して実行します。計画は実行中の進捗、調査結果、決定事項、成果を記録する生きたドキュメントとして扱います。

入力の例：execute-plan docs/.plans/YYMMDD-HHmm-<plan-slug>/SUMMARY.md

実行中に計画を再設計してはいけません。曖昧な点や障害が生じた場合は、作業を中断して確認してください。

ワークフロー

ステップ 1：初期化

1. 計画を特定する

   • 計画のパスが存在し、読み取り可能であることを確認します。
   • ディレクトリが指定されている場合は、その中にある SUMMARY.md を探します。

2. 実行コンテキストを読み込む

   • 計画に関連するプロジェクトのコンテキストのみを読み込みます。
     • docs/SUMMARY.md が存在する場合は、最初に読みます。
     • タスクに関連する詳細ドキュメントのみを読み込みます。
     • 実装規約については、Code Standard ドキュメントを優先します。
     • ドキュメントがコードやユーザーの意図と矛盾する場合は、広範な変更を行う前に、利用可能な入力や質問をもとに判断します。
   • 計画のフェーズファイル、コンテキスト／オリエンテーションのメモ、依存関係、受け入れ基準、冪等性／復旧に関するメモ、決定ログ、未解決の質問を確認します。
   • 古い計画に生きた計画に必要なセクション（Progress、Surprises & Discoveries、Decision Log、Outcomes & Retrospective）がない場合、計画の内容が明確であれば、実行前にこれらのセクションを追加します。

3. 実行モードを選択する（明示的なルール）

   • デフォルトのモード：Batch
   • 次のいずれかに該当する場合は、Interactive を使用します。
     • リスクの高い変更（認証、決済、移行、セキュリティ上重要なロジック）
     • 取り消せない操作（データ移行、破壊的なスクリプト）
     • 受け入れ基準が不明確
     • ユーザーがチェックポイントを明示的に要求している
   • モードが不明確な場合は、一度だけ確認し、ユーザーの選択に従って進めます。

4. 次の未完了フェーズを見つける

   • 最初の [ ] フェーズ
   • 該当するものがなければ、最初の [-] フェーズ
   • 未完了または進行中のフェーズが残っていない場合は、最終検証に進みます。

5. 計画の重要な整合性を確認する

   • 各フェーズに次の内容があることを確認します。
     • 明確な目標
     • 対象ファイル
     • 検証コマンド
     • 観測可能な受け入れ基準
   • 明示されたフェーズの検証内容と終了基準から推測できる場合は、観測可能な受け入れ基準が欠けていても、実行前にフェーズへ追加します。
   • 重要な詳細が欠けている、または矛盾している場合は、作業を中断して確認を求めます。

ステップ 2：フェーズごとのループを実行する

各フェーズを順番に実行します。

1. 完了済みのフェーズをスキップする

   • ステータスが [x] の場合は、次のフェーズに進みます。

2. 進行中にする

   • 変更を加える前に、フェーズのステータスを [-] に更新します。
   • SUMMARY.md に、フェーズの開始を説明するタイムスタンプ付きの Progress エントリーを追加します。

3. 厳密に実行する

   • そのフェーズで定義されたタスクのみを実装します。
   • 承認なしにスコープを拡大しないでください。
   • フェーズの要件を満たす最小限のコードを記述します。推測に基づく機能、単一用途のコードに対する抽象化、起こり得ないシナリオへのエラー処理は追加しないでください。以下の シンプルさ優先 と 外科的な変更 のルールを参照してください。
   • 実装中に重大な想定外の事実が判明した場合は、SUMMARY.md の Surprises & Discoveries に記録します。
   • スコープ内に留まるために判断が必要な場合は、続行する前に判断とその理由を Decision Log に記録します。

4. フェーズを検証する

   • 計画に記載された、そのフェーズ固有の検証コマンドを実行します。
   • 最低限、変更したファイルに関連するテストやチェックを実行します。
   • 簡潔な検証結果を SUMMARY.md の Progress またはフェーズで指定された証跡の記録先に記録します。

5. 失敗に対処する

   • 検証に失敗した場合：
     • フェーズのスコープ内で、対象を絞った修正を試みます。
     • 検証を再実行します。
   • それでも失敗する場合、または根本原因がスコープ外にある場合は、停止してブロッカーを報告します。

6. 完了にする

   • 検証に合格した後に限り、フェーズのステータスを [x] に更新します。
   • 検証結果と、そのフェーズで変更したファイルを記載したタイムスタンプ付きの Progress エントリーを追加します。

7. 進捗を報告する

   • 対話モード： 報告し、次のフェーズに進む前に確認を待ちます。
   • バッチモード： 簡潔に報告し、直ちに続行します。

ステップ 3：最終検証

すべてのフェーズが完了した後：

1. プロジェクト全体の検証

   • 全体のリント／型チェック一式を実行します。
   • 関連するすべてのテスト（または計画で求められている場合はテスト一式）を実行します。
   • 該当する場合はビルド検証を実行します。

2. 安定化

   • 実行中に発生したリグレッションを修正します。
   • すべてのチェックに合格するか、ブロックされるまで、失敗したチェックを再実行します。

3. 手動検証の確認

   • ユーザーによる手動 QA が必要な場合は、明示的に依頼して一時停止します。
     • Verified で承認
     • または、次の反復に向けたフィードバックを提供

4. 成果を更新する

   • 最終結果、検証の概要、承認済みの逸脱、フォローアップを含め、SUMMARY.md の Outcomes & Retrospective を完成させます。

ステップ 4：完了時の成果物

1. ドキュメントを同期する

   • 動作／アーキテクチャ／コードベースの想定が変わった場合は、docs の成果物を更新します。

2. 実行レポートを作成する

   • ファイル：docs/.plans/YYMMDD-HHmm-<plan-slug>/EXECUTION-REPORT.md
   • 以下の必須セクションをすべて含めます。

3. 最終確認に備える

   • ユーザーの最終確認前にアーカイブしてはいけません。ユーザーが Need verify を選択することがあり、その場合は同じ計画パスを使って実行を続ける必要があります。

ステップ 5：最終確認ゲート

完了時の成果物が整った後、入力／質問ツールを使って、次の選択肢をこのとおりに提示し、ユーザーに最終確認を求めます。

• Confirm: End session
• Need verify

選択された内容に応じて、次のように対応します。

1. Confirm: End session

   • 計画フォルダーを docs/.plans/archived/ にアーカイブします。
   • 次のとおり通知します：Execution complete. Report archived at docs/.plans/archived/YYMMDD-HHmm-<plan-slug>/EXECUTION-REPORT.md.
   • 実行セッションを終了します。

2. Need verify

   • ユーザーから検証のフィードバック／詳細を受け取ります。
   • アーカイブはしません。
   • フィードバックに対応する実行ループを続け、その後、必要に応じて検証と完了手順を再実行します。

実行レポートの標準

EXECUTION-REPORT.md は次のテンプレートを使用する必要があります：references/execution-report-template.md

ルール

• プロジェクトの規約を尊重する：docs/ および関連するプロジェクトドキュメントに従います。
• 計画を厳守する：範囲を黙って変更しません。
• ブロッカーが発生したら停止する：依存関係の不足、指示の矛盾、または原因不明の失敗がある場合は停止します。
• 推測しない：不明な点があれば確認を求めます。
• 完了前に検証する：チェックに合格するまでは、フェーズを完了としません。
• 計画を常に最新に保つ：実行の進行に合わせて、進捗、発見事項、決定事項、結果をSUMMARY.mdに更新します。重要な実行状態をチャット履歴だけに頼らないでください。
• 冪等性：安全に再実行できる操作を優先します。
• シンプルさを優先する：フェーズの完了条件を満たす最小限のコードを実装します。計画にない機能は追加しません。1回しか使わないコードに抽象化を導入しません。要求されていない設定機能は追加しません。200行書いて50行で済むなら、書き直します。
• 変更は必要最小限にする：フェーズに必要な箇所だけを変更します。隣接するコード、コメント、書式を「改善」しません。問題のないコードをリファクタリングしません。別の方法を好む場合でも、既存のスタイルに合わせます。変更によって使われなくなったインポート、変数、関数だけを削除します。計画で求められていない限り、既存の未使用コードは削除しません。変更したすべての行がフェーズのタスクに紐づくようにします。
• 成果物は、現在のセッションと同じ言語で作成します。