Task Plan

[作業]タスクの実装計画を立て、PR分割と依存関係を整理するスキル。 plan.md作成までが責務。実装はtask-executeが担う。

トリガー条件

以下のすべてを満たす場合に使用する：

• calmに[作業]タスクがある
• ユーザーが実装を依頼した
• plan.mdがまだ存在しない

以下では使用しない：

• plan.mdが既に存在する → task-execute を使う
• 仕様が未確定 → discussion / design スキルを使う
• 調査・検索・質問応答 → 本体が直接対応

ワークフロー

Step 0: 仕様確認

メインエージェントが以下を実行する（SAには委譲しない）：

1. 決定事項の取得: 関連トピックの get_decisions を取得する。加えて pull_precedents を タスクの作業背景（またはトピックの要約）を context として呼び、近傍トピックの関連 decision を 網羅的に取得する。両者を合わせて「ビジネス要件→設計→振る舞い」の導出に使う。取得した decision 本文は、後続の Step 5 導出検証SA に渡すため保持しておく。 （task-execute Step 2 でも pull_precedents を呼ぶが、あちらは実装着手時に各サブプランの 個別論点で呼ぶもの。ここ（plan時点）はタスク全体の仕様導出のための事前調査であり、目的が 異なるため重複ではない）

2. 設計書・仕様書の確認: 参照すべきドキュメントの存在確認と読み込み

3. ユーザーへの仕様確認: 決定事項と設計書の内容をユーザーに提示し、以下を確認する

   • 実装スコープが正しいか
   • 変更すべき仕様はないか
   • 追加の要件はないか
   • 業務ロジック・データモデル・外部API契約に解釈の余地が残っていないか

   確認しない（agent 自走で決めて plan.md に明記する）:

   • 変数名・関数名・クラス名などの命名
   • ブランチ名・base branch
   • PR分割の順序・グルーピング
   • ファイル配置・モジュール分け
   • 実装パターン（既存コード踏襲で決まるもの）

   上記は plan.md / サブプランに記載するだけで、ユーザー確認の対象としない。

4. ユーザーのGOが出てから Step 1 に進む

ユーザーへの提示テンプレート：

## 仕様確認

### 関連する決定事項
- id:{N}: {決定内容の要約}

### 設計書の要点
- {設計書から抜粋した重要ポイント}

### 実装スコープ
- {何を実装するか}
- {何を実装しないか}

### 確認事項
- {不明点や確認したいこと}

→ この内容で進めてOK？

Step 1: 変更内容の分類

タスクの変更内容を PR分割基準（5類型） で分類する。 レビューの「読み方」が同じものだけ1 PRにまとめる。異なる類型を1 PRに混ぜない。

類型	内容	レビューの読み方
A. 機械的置換	リネーム、import書き換え	差分を流し読みで確認
B. スキーマ/データ変更	テーブル追加/削除、トリガー、マイグレーション	データモデルの妥当性を精査
C. 新規モジュール追加	新ファイル、新クラス	ゼロからの設計レビュー
D. 既存コードの振る舞い変更	ロジック変更、API変更	before/afterの差分を精査
E. 削除/廃止	旧コード除去	参照残りがないか確認

Step 2: GO判定予測（predicted）の決定

Step 1で分類した各PR（単一PRの場合は1件のみ）について、GO判定の予測分類（predicted）を決める。 PR作成時に境界ゲート検出器（scripts/gate_check.py）が diff から出す機械判定（machine）と 後で突き合わせるための、plan時点の見立てである。外れても構わない（乖離自体が検出器の校正データになる）。

分類は3値: pre_go（事前にコードを読んで確認すべき）/ gray（機械的にどちらとも判定し切れない）/ post_veto_candidate（事後の拒否権行使で足りる候補）。

• 類型B（スキーマ/データ変更）、および類型Eのうちデータに触れるもの（テーブル削除・ データ移行を伴う廃止等）: 必ず pre_go とする
• それ以外（類型A/C/D、データ非接触の類型E）: ブラスト半径（migration・公開IF・破壊的操作への 接触見込み）とrevert容易性（PRサイズ・機械revertの成立見込み）から pre_go / gray / post_veto_candidate のいずれかを判断する。判断に迷う場合は安全側（pre_go）を選ぶ

各PRのpredictedはplan.md（単一PRの場合）またはサブプラン（複数PRの場合）に記録する（Step 4参照）。

Step 3: ブランチ戦略の判断

PRが複数になる場合、全PRをmainに直接向けるか、統合ブランチ（feature branch）を経由するかを判断する。

• main直撃（stacked PRs）: 各PRが独立してmainに入っても安全な場合
• 統合ブランチ経由: 中間状態でmainが壊れる、または機能として一体で部分マージに意味がない場合

統合ブランチを選択した場合：

• PR分割テーブルの末尾に final（統合マージ）行を追加する
• 各サブPRのbaseは統合ブランチとし、finalのbaseはmainとする
• finalの依存先は他の全サブプラン

Step 4: plan.md 作成

出力先: ~/.claude/projects/<project>/work/{task-name}/

PR が1個で済む場合: plan.md 単体（サブプランは作らない）

PR が複数になる場合: plan.md（インデックス）+ サブプラン（plan-a.md, plan-b.md, ...）に分割。 各サブプラン = 1 PR = 1 SA実行単位。

plan.md テンプレート（複数PR）

# {タスク名}

## 作業背景
{なぜこのタスクが必要か}

## 関連情報
- calm タスク: #{タスクID}
- 関連 decisions: #{ID}, #{ID}, ...
- 設計書: {パス}（あれば）

## ブランチ戦略
{main直撃 or 統合ブランチ（feature/{統合ブランチ名}）}

## PR分割

| # | 類型 | 内容 | ブランチ名 | base | predicted | 状態 |
|---|------|------|-----------|------|-----------|------|
| a | {A-E} | {概要} | feature/{名前} | main | {pre_go/gray/post_veto_candidate} | 🔲未着手 |
| b | {A-E} | {概要} | feature/{名前} | main or PR-aのブランチ | {pre_go/gray/post_veto_candidate} | 🔲未着手 |
| c | {A-E} | {概要} | feature/{名前} | main or 依存先 | {pre_go/gray/post_veto_candidate} | 🔲未着手 |
| final | - | 統合マージ | feature/{統合ブランチ名} | main | - | 🔲未着手 |

状態: 🔲未着手 → 🔄着手中 → ✅完了
※ final行は統合ブランチ戦略の場合のみ。main直撃の場合は不要。

## 依存関係
- PR-b は PR-a の完了後に着手（{理由}）
- PR-c は独立して着手可能
- final は全サブプランの完了後（統合ブランチ戦略の場合）

## サブプラン
- [plan-a.md](./plan-a.md): {概要}
- [plan-b.md](./plan-b.md): {概要}
- [plan-c.md](./plan-c.md): {概要}

サブプラン テンプレート

# サブプラン {a}: {タスク名}

## 類型
{A-E のどれか}

## サイズ見込み
{変更予定ファイル数と行数（追加+削除）の見立て。テスト・docsは目安から除外してよい。800行超になる見込みならこの時点でさらに分割を検討する}

## GO判定予測
- predicted: {pre_go/gray/post_veto_candidate}

## ブランチ
- ブランチ名: feature/{名前}
- base: {main or 依存先ブランチ}

## TODOリスト
- [ ] TODO 1: {内容}
- [ ] TODO 2: {内容}
- ...

## 仕様参照
- 設計書: {パス}
- 参考実装: {パス}
- テスト: {パス}

## 実装順序
{TODOの推奨実装順序と依存関係}

## 実装パターン
{既存コードから抽出したパターンの具体例。コードスニペット付き}

## エッジケース（仕様カバレッジ）

Step 0 で取得した decision（と関連decision）から、この機能が果たすべき「あるべき振る舞い」を
導出し、カバーすべきエッジケース（境界値・異常系・例外・特殊な振る舞い）として列挙する。
真実源は calm のビジネス要件・設計である。

| # | あるべき振る舞い（条件→期待結果） | 種別 | 根拠decision（関連含む） |
|---|------|------|--------|
| 1 | {例: rate>1 のとき例外を投げる（計算しない）} | 個別ケース / プロパティ | {id}, {id} |

各行の導出メモ（なぜその振る舞いが正しいか。ビジネス要件→設計→振る舞いの鎖を書く）:
- #1: ビジネス要件「{例: 割引率は100%超を認めない}」 → 設計上 {その関数の役割}
  → だから rate>1 は例外を投げるべき

- 個別ケース: 特定入力に対する振る舞い（境界値・異常入力など）
- プロパティ: 任意入力で成り立つ不変条件（例: decode(encode(x)) == x）
- 「あるべき振る舞い」は **アサート可能な具体記述**で書く（「適切に」「正しく」等の曖昧語は禁止、
  期待される具体的結果を書く）
- 各行は裸で書かず、根拠 decision からの**導出メモを必ず添える**。導出は
  Step 5 の導出検証SA がチェックする。人間は最終承認のみで正しさの番人ではない

**ビジネス要件が calm に無い場合**:
- 振る舞いが変わる実装なのに根拠ビジネス要件が calm に無い ＝ 仕様欠落。原則 task-plan を
  中断し、discuss で要件を確定してから戻る（自明・軽微ならその場でユーザー確認し decision 化して
  継続。線引きは LLM 判断）
- ビジネス要件に紐つかない技術変更で振る舞いが変わらないものは、表の代わりに
  「テスト不要（類型X：理由）」と明記する。許容類型 = 機械的置換 / 純粋削除 /
  コメント・docのみ / 外部依存のバージョン上げで挙動不変。リスト外の理由（「めんどう」等）は認めない

## 受け入れ基準
- [ ] {基準}
- [ ] テストが追加されている（通常系（happy path）・基本機能のテストに加え、エッジケース表の各ケースの「あるべき振る舞い」を検証するテストが存在すること。テスト不要明記の場合を除く）
- [ ] 既存テストが通る

## テスト実行方法
{テストの実行コマンド}

類型 B（スキーマ・データ変更）のサブプランには以下も追加する:

## migration / revert
- 破壊的変更 lint 該当有無: {DROP TABLE / DROP COLUMN / DELETE FROM / WHERE なし UPDATE / rmtree・os.remove 等を含むか。含む場合 `scripts/gate_check.py` の破壊的変更検出（追加行への正規表現マッチ）でフラグが立つため、意図的である旨と安全確認の観点を書く}
- revert 分類: {R1（migration非接触・revert commitのみで戻る）/ R2（migration接触・戻し方を具体的に書く）}

plan.md テンプレート（単一PR）

# {タスク名}

## 作業背景
{なぜこのタスクが必要か}

## 関連情報
- calm タスク: #{タスクID}
- 関連 decisions: #{ID}, #{ID}, ...

## サイズ見込み
{変更予定ファイル数と行数（追加+削除）の見立て。テスト・docsは目安から除外してよい。800行超になる見込みなら複数PRへの分割を検討する}

## ブランチ
- ブランチ名: feature/{名前}
- base: {main or 指定ブランチ}

## GO判定予測
- predicted: {pre_go/gray/post_veto_candidate}

## TODOリスト
- [ ] TODO 1: {内容}
- [ ] TODO 2: {内容}
- ...

## 仕様参照
- 設計書: {パス}
- 参考実装: {パス}

## 実装順序
{TODOの推奨実装順序と依存関係}

## 実装パターン
{既存コードから抽出したパターンの具体例}

## エッジケース（仕様カバレッジ）

Step 0 で取得した decision（と関連decision）から、この機能が果たすべき「あるべき振る舞い」を
導出し、カバーすべきエッジケース（境界値・異常系・例外・特殊な振る舞い）として列挙する。
真実源は calm のビジネス要件・設計である。

| # | あるべき振る舞い（条件→期待結果） | 種別 | 根拠decision（関連含む） |
|---|------|------|--------|
| 1 | {例: rate>1 のとき例外を投げる（計算しない）} | 個別ケース / プロパティ | {id}, {id} |

各行の導出メモ（なぜその振る舞いが正しいか。ビジネス要件→設計→振る舞いの鎖を書く）:
- #1: ビジネス要件「{例: 割引率は100%超を認めない}」 → 設計上 {その関数の役割}
  → だから rate>1 は例外を投げるべき

- 個別ケース: 特定入力に対する振る舞い（境界値・異常入力など）
- プロパティ: 任意入力で成り立つ不変条件（例: decode(encode(x)) == x）
- 「あるべき振る舞い」は **アサート可能な具体記述**で書く（「適切に」「正しく」等の曖昧語は禁止、
  期待される具体的結果を書く）
- 各行は裸で書かず、根拠 decision からの**導出メモを必ず添える**。導出は
  Step 5 の導出検証SA がチェックする。人間は最終承認のみで正しさの番人ではない

**ビジネス要件が calm に無い場合**:
- 振る舞いが変わる実装なのに根拠ビジネス要件が calm に無い ＝ 仕様欠落。原則 task-plan を
  中断し、discuss で要件を確定してから戻る（自明・軽微ならその場でユーザー確認し decision 化して
  継続。線引きは LLM 判断）
- ビジネス要件に紐つかない技術変更で振る舞いが変わらないものは、表の代わりに
  「テスト不要（類型X：理由）」と明記する。許容類型 = 機械的置換 / 純粋削除 /
  コメント・docのみ / 外部依存のバージョン上げで挙動不変。リスト外の理由（「めんどう」等）は認めない

## 受け入れ基準
- [ ] {基準}
- [ ] テストが追加されている（通常系（happy path）・基本機能のテストに加え、エッジケース表の各ケースの「あるべき振る舞い」を検証するテストが存在すること。テスト不要明記の場合を除く）
- [ ] 既存テストが通る

## テスト実行方法
{テストの実行コマンド}

Step 5: 導出検証SA

エッジケース表＋導出メモを作成したら、ユーザー確認の前に 導出検証サブエージェントを起動する。 検証対象ファイルは構成によって異なる：

• 単一PRの場合: plan.md自体にエッジケース表がある。plan.mdを検証対象として1回起動する
• 複数PRの場合: エッジケース表は各サブプラン（plan-a.md, plan-b.md, ...）側にあり、 plan.md（インデックス）側には存在しない。サブプランごとに1回ずつ、そのサブプランを 検証対象として導出検証SAを起動する（全サブプランをまとめて1回で検証しない。サブプランごとに 根拠decisionの組み合わせが異なりうるため）

いずれの場合も バックグラウンド（run_in_background: true） で起動する。モデルは model: opus を明示する（calm と振る舞いの整合・曖昧さ検出は批判的判断が要るため）。

このSAの役割は、検証対象（plan.mdまたはサブプラン）表の「あるべき振る舞い」が calm の ビジネス要件・設計から正しく導出できているかの検証である。振る舞いの正しさの番人はこのSAが主役で、 人間GOはこの検証を踏まえた最終承認に過ぎない。

導出検証SAへのプロンプトテンプレート：

あなたは導出検証サブエージェントです。実装計画の「あるべき振る舞い」が
ビジネス要件・設計から正しく導出できているかを検証してください。

## 検証対象
{plan.md（単一PRの場合）または該当サブプラン（複数PRの場合）の絶対パス}
（特に「## エッジケース（仕様カバレッジ）」表と各行の導出メモ）: {絶対パス}

## 真実源（ビジネス要件・設計）
以下は calm から取得済みの関連 decision 本文です。これを唯一の真実源として扱ってください。
{Step 0 で取得した関連 decision の本文をここに貼る}

## 検証ルール
1. 各「あるべき振る舞い」について、根拠として挙がった decision 本文から **該当する記述を逐語引用**し、
   その記述だけで期待結果（out）が一意に決まるかを ○×判定する。
   - 引用できない、または記述が複数解釈を許す（例: 「100%超を認めない」が 例外／clamp／警告ログ の
     どれにも読める）場合は「正しさ未担保」とし、導出メモが滑らかでも OK にせず人間にエスカレートする
   - **導出メモの文章が整合的に読めること自体を OK の根拠にしてはいけない**（後付けの辻褄は通さない）
2. decision の記述が曖昧・矛盾・欠落していて振る舞いが一意に定まらない箇所は
   「重大欠陥」として列挙する（あなたが辻褄を合わせて埋めてはいけない）
3. plan表の振る舞いと decision の記述にズレがある場合は、どちらが正しいかを裁定せず
   差分として報告する（正誤の判定は人間が行う）
4. 「あるべき振る舞い」がアサート不能な曖昧記述（「適切に」等）なら指摘する
5. **網羅性チェック**: 表のエッジケースが、この機能の入力空間・状態空間に対して代表性を持つかを見る。
   落ちている境界・異常系の **類型** を挙げる（個々の値の列挙でなく類型のフラグでよい。例: 異常系の
   組合せ、並行・状態依存、空／上限／境界の抜け）。網羅の確定判定でなく「抜けてそうな類型」の指摘に留める

## 出力
- 各ケースの導出妥当性: OK（逐語引用つき） / 要確認・正しさ未担保（＋理由）
- calm 側の欠陥リスト（曖昧・矛盾・欠落）
- plan表と decision のズレ（差分のみ、裁定なし）
- 網羅性の抜け（落ちていそうな境界・異常系の類型）

渡すもの：

• 検証対象ファイルの絶対パス（単一PR: plan.md／複数PR: 起動対象のサブプラン。複数PRの場合は サブプランの数だけこのSAを起動することになる）
• Step 0 で取得した関連 decision の本文（メインが取得済みのものを渡す。SAに calm を直接 叩かせない）

SA完了後、メインは各起動分の結果を受け取り Step 6 でユーザーに提示する（複数PRの場合はサブプラン ごとの結果をまとめて提示する）。要確認・欠陥があれば、ユーザーと解消してから（必要なら discuss に 戻り decision を補強してから）次へ進む。

Step 6: ユーザー確認

plan.md（とサブプラン）と Step 5 導出検証SAの結果 をユーザーに提示し、必ず確認を取る。

提示する内容：

• plan.md の絶対パス（PR分割テーブル・依存関係・ブランチ名・base branch・GO判定予測は plan.md 内に記載済み、報告対象であって確認対象ではない）
• 導出検証SAの結果（導出の妥当性、calm側の欠陥、plan表とdecisionのズレ。複数PRの場合は サブプランごとの結果を並べて提示する）
• 仕様解釈に不安が残った点（Step 0 でユーザーに振れなかった点があれば）

確認の対象は「仕様解釈・エッジケース網羅・calm との整合」に限る。命名・ブランチ名・PR分割の順番・ファイル配置・GO判定予測は agent 判断で確定済み（plan.md 参照）として扱い、ユーザー裁定を求めない。

実装には絶対に進まない。 ユーザーが確認してOKを出すまで待つ。

注意事項

• plan.md作成前にファイル操作を始めない
• ブランチ名・base branch・PR分割順序・命名・ファイル配置は agent 判断で確定し plan.md に明記する。ユーザー確認を挟まない
• 既存コードのパターンを調査してplan.mdに記載する（SAが参照できるように）
• 仕様が不明確な場合はユーザーに確認（勝手に解釈しない）。確認対象は「業務ロジック・データモデル・外部契約・スコープ」に限る