exec-plan

ExecPlan — ライフサイクル管理

開始時に宣言: "Using the exec-plan skill."

ExecPlan とは

新しいエージェントセッションが、目に見える動作を実現するために参照できる、自己完結型の更新され続けるドキュメントです。docs/exec-plans/ に保存します。形式は docs/PLANS.md の仕様に従います。

ExecPlan は ToDo リストではありません。変更の背景、現在のコードベースの状態、変更後のあるべき姿、そして変更が機能したことを証明する方法を伝えるストーリーです。

このスキルを使う場面

• 複数のステップやファイルにまたがる作業、新機能、リファクタリング、または完了までにおよそ 1 時間以上かかると見込まれるタスクでは必須です。
• 簡単な修正では任意ですが、相応の規模のタスクで省略する場合は、その理由を明記してください。
• 前回のセッションから作業を再開する場合は必ず使ってください。

3 つのモード

モード 1：新しい計画を作成する

新しい複数ステップの作業を始めるとき：

1. テンプレートと要件を確認するため、docs/PLANS.md を読みます。
2. docs/exec-plans/active/{descriptive-kebab-name}.md に計画を作成します。
3. テンプレートのすべてのセクションを記入します。必須のセクションは次のとおりです。
   • Purpose / Big Picture — 変更後にユーザーが見たり、実行したりできること
   • Progress — 各マイルストーンの未チェックボックス
   • Surprises & Discoveries — (none yet) から始める
   • Decision Log — (none yet) から始める
   • Outcomes & Retrospective — (fill when complete) から始める
   • Context and Orientation — 完全なファイルパス、用語の定義、現在の状態
   • Plan of Work — 目標 → 作業 → 結果 → 検証という流れで記述したマイルストーン
   • Concrete Steps — 期待される出力を含む正確なコマンド
   • Validation and Acceptance — 成功を示す、確認可能な証拠
   • Idempotence and Recovery — 再試行またはロールバックの方法
4. すべてのファイルパスは、リポジトリのルートからの絶対パスにします。
5. すべての用語は本文中で定義します。読み手は何も知らないものとして扱います。
6. 実装を始める前に計画をコミットします。

モード 2：既存の計画を続行する

作業を再開するとき、または次のマイルストーンに着手するとき：

1. docs/exec-plans/active/ にある計画ファイルを読みます。
2. Progress で最初の未チェック項目を見つけます。
3. 作業を始める前に、以前のセッションで生じた Surprises のうち、このタスクに影響するものがないか確認します。
4. Plan of Work に従ってマイルストーンを実行します。
5. マイルストーンが完了したら、直ちに計画を更新します。
   • タイムスタンプ付きで Progress の項目にチェックを入れます：- [x] (YYYY-MM-DD HH:MMZ) Description
   • 発生した Surprises & Discoveries を追加します
   • 行った選択について Decision Log に記録します
6. コード変更とともに計画の更新をコミットします。
7. Validation コマンドを実行して成功を確認します。

重要：計画ファイルを更新せずに、マイルストーンが完了したと主張してはいけません。 計画こそが進捗を保持する仕組みです。更新しなければ、次のセッションで作業がやり直されます。

モード 3：計画を完了する

すべてのマイルストーンが完了したら：

1. Outcomes & Retrospective セクションに次の内容を記入します。
   • 計画と比べて達成できたこと
   • 残っている課題
   • 得られた教訓
   • 想定外の利点やコスト
2. ファイルを移動します：git mv docs/exec-plans/active/{name}.md docs/exec-plans/completed/{name}.md
3. 次のメッセージでコミットします：docs: complete exec-plan {name}

品質チェック

計画をコミットする前（新規作成時または更新時）に、次の項目を確認します。

• Purpose には、コード変更だけでなく、ユーザーから見える動作が記載されている
• 完了した項目には Progress のタイムスタンプがある
• Context では、リポジトリのルートからの完全なパスでファイルが示されている
• すべての用語が本文中で定義されている（重要な用語について「外部ドキュメントを参照」としていない）
• Validation に正確なコマンドと期待される出力が記載されている
• Recovery セクションで、リスクのある各ステップのロールバック方法が説明されている
• Surprises セクションが最新の状態になっている（空の場合も含む）
• 実装中に行った選択が Decision Log に記録されている

アンチパターン

• 説明のないチェックリスト：「- [ ] ファイル X を編集する」だけでは、次のセッションに何も伝わりません。なぜ編集するのですか？何を変更するのですか？どう検証するのですか？
• 重要なコンテキストを外部参照に任せる：「詳細は ARCHITECTURE.md を参照してください」――計画は自己完結している必要があります。関連するコンテキストを本文に含めてください。
• 進捗の更新を忘れる：最もよくある失敗です。マイルストーンを完了しても、タイムスタンプ付きでチェックを入れなければ、次のセッションで同じ作業が繰り返されます。
• 完了した計画を active/ に残す：すべてのマイルストーンが完了したら、completed/ に移動してください。active/ には未完了の作業だけを置きます。
• 検証を省略する：「テストに合格する」だけでは受け入れ基準になりません。「grep -n isValid file.swift の実行結果がないことを確認し、ファイル内に isValid の計算プロパティが存在しない」ことが受け入れ基準です。

他のスキルとの連携

• TCA コードに関する計画のマイルストーンを実装する前に、/pfw-composable-architecture を実行してください
• デバッグに関する計画のマイルストーンを実装する前に、debug スキルを実行してください
• リファクタリングに関する計画のマイルストーンを実装する前に、refactor スキルを実行してください
• API 設計に関する計画のマイルストーンを実装する前に、rest-api-design スキルを実行してください
• 計画のすべてのマイルストーンが完了した後、最終的なクリーンアップのために refactor スキルを実行してください