| name | implementation-plan |
| description | 実装計画（Plan）ファイルを作成する。TDD・コミット分割・自動テスト一覧・工数見積もりを含む再現性の高い Plan を生成する。機能追加・バグ修正・リファクタリング等の実装計画策定時に使用。トリガー: 「Planを作って」「計画を立てて」「実装計画を」 |
目的
実装者がそのまま着手できる Plan を作成する。Plan は、What を守りながら How を固定しすぎず、TDD の短いフィードバックループで実装・検証・コミット・PR 作成まで進められる粒度にする。
t-wada による TDD の核
t-wada が紹介・実践している TDD の核は、テスト件数のノルマではなく、実装前に不安をテストリストへ書き出し、そこから小さく 1 つ選んで Red → Green → Refactor を回すことにある。
Red では、次に確認したい振る舞いを失敗するテストとして表現する。Green では、そのテストを通すための最小実装に集中する。Refactor では、全テストが通る状態を保ったまま設計を整える。途中で新しい不安に気づいたら、その場で実装に混ぜず、テストリストへ戻して次のサイクルで扱う。
前提確認
Plan 作成前に以下を確認する。足りない情報があれば、コードベース・docs・既存テストを先に調べる。調べても判断できない場合だけユーザーに確認する。
- 対象スコープ: 何を実装・修正するか
- 既存パターン: 該当モジュール、責務境界、テスト配置、命名規則
- 検証方法: 言語・フレームワーク・テストコマンド・Lint/format/type check
- 制約条件:
AGENTS.md、CLAUDE.md、docs 配下の関連仕様
出力先
docs/plan/plan-<topic>.md に作成する。実装済みの Plan は docs/plan/archived/ に移動する。
作成手順
- assets/plan-template.md を Plan の唯一の雛形として使う
- テンプレート内の全プレースホルダーを具体化する
- 対象スコープからテストリスト / 不安リストを作る
- TDD Cycle、変更ファイル、コミット分割、検証コマンド、工数見積もりを埋める
- Plan 作成後、プロジェクト指示に従ってレビュー依頼コマンドを実行する
TDD Cycle の単位
Plan では、TDD Cycle の単位を明確にするために以下を区別する。
- テストリスト項目:
T1, T2 のような、まだコードではない振る舞い・不安のメモ
- 自動テスト: Red で実際に追加する
test_name のようなテストコード
各 TDD Cycle では、テストリストから次に扱う テストリスト項目を 1 つだけ 選ぶ。Red ではそれに対応する自動テストを 1 つだけ書き、Green と Refactor を終えてから次の項目へ進む。
ここでいう「1 つだけ」は、1 回の Red で扱う変更を小さく保つための制約であり、1 つのテストリスト項目に必要な自動テスト総数を 1 件へ制限するものではない。1 項目に複数の入力条件、状態遷移、境界値、失敗地点が含まれる場合は、同じ項目を複数の TDD Cycle に分け、各 Cycle で自動テストを 1 件ずつ追加する。
Plan に記載された自動テスト一覧を上限やノルマとして扱わず、実装中に新しい不安を発見した場合はテストリストへ追加し、必要な Cycle を続ける。テストリスト項目の完了は「予定したテストを 1 件通したこと」ではなく、その項目が表す振る舞いと主要な失敗境界への不安が解消されたことで判断する。
テストリストの扱い
テストリスト / 不安リストは Plan 全体の設計メモではなく、TDD Cycle の元データである。
- ID は
T1, T2 のように Plan 全体で一意にする
- 各項目は外から見た振る舞い、入力、出力、副作用、エラー境界で書く
- private メソッド、内部構造、実装都合をテスト対象にしない
- 正常系だけでなく、空・ゼロ状態、境界値、異常系、統合観点を必要十分に含める
- High 優先項目は
対応するCycle を必ず持たせる
- Medium/Low を未対応にする場合は
今回対象外理由 を書く
複数の独立した期待結果を Then に並べなければ表現できない項目や、複数のstatus・障害地点を一度に扱う項目は、そのまま自動テスト 1 件へ押し込めない。項目自体を分割するか、同じ項目に対応する Cycle を複数用意する。
観点漏れの確認だけに references/test-coverage.md を使う。この参照は、Red で大量のテストを書くためのものではない。
TDD Cycle の作り方
各 Cycle には以下を必ず含める。
- 目的: この Cycle で到達したい振る舞い
- 今回選ぶ 1 項目: テストリストID、選ぶ理由、この時点で扱わないこと
- RED: 追加する自動テスト名、Given/When/Then、想定される失敗
- GREEN: RED の自動テストを通す最小実装方針
- REFACTOR: 全テストが通る状態で整理する観点
- テストリスト更新: 完了、追加、次候補
- コミット: Cycle 完了後に切る Conventional Commit
禁止事項
- テストリストを作らず、いきなりテストコードや実装 Step を書く
- Green 中に別ケース対応やリファクタリングを混ぜる
- Refactor を省略してコミットする
- 最後にまとめてテストを書く Step を作る
- カバレッジ稼ぎのためだけのテストを書く
- 実装詳細に強く依存したテストを書く
必須セクション
Plan には以下をこの順序で含める。詳細な書式は assets/plan-template.md に従う。
- ヘッダー
- 設計方針
- TDD 方針
- Plan スコープ
- 対象一覧
- テストリスト / 不安リスト
- Step 0: Worktree 作成
- Step 1-N: TDD Cycle
- Step N+1: 動作確認
- Step N+2: Plan・仕様書との自己チェック
- Step N+3: PR 作成
- Step N+4: 初回レビューバック
- Step N+5: レビュー対応後の再レビューバック
- 変更ファイル一覧
- コミット分割
- 自動テスト一覧
- 工数見積もり
品質チェック
Plan 完成前に以下を確認する。
- 冒頭 Note に「振る舞い（What）は決して変えてはいけないが、より美しい設計があれば実装方法（HOW）だけは変えてもよい。」が含まれている
- Plan スコープに
WT作成 → 実装(TDD) → コミット(意味ごとに分離) → PR作成 が含まれている
- テストリスト、TDD Cycle、自動テスト一覧の対応が崩れていない
- 動作確認後、PR 作成前に Plan と関連仕様書を読み直し、実装・テスト・文書の差分を自己チェックする Step がある
- PR 作成後に
sleep 15m して pr-review-back-workflow Skill を実行する Step がある。レビューがまだ無い場合は sleep 5m して再実行し、最大 2 回まで追加待機する
- レビュー対応を push した後に、再度
sleep 15m して pr-review-back-workflow Skill を実行する Step がある。レビューがまだ無い場合は sleep 5m して再実行し、最大 2 回まで追加待機する
- Rust 実装なら
cargo fmt --check, cargo test, cargo check, cargo clippy --all-targets --all-features -- -D warnings が動作確認に含まれている
- 関連 docs がある場合、更新対象に含まれている
