plan

GitHub issue ( $ARGUMENTS ) から実装計画と動作確認チェックリストを作成する。

本スキルは 意思決定 + 計画策定 に責務を持つ。/research が列挙した候補から実装方法を選択し、受け入れ条件をタスクにマッピングして TDD で計画化し、AC を検証可能にする動作確認チェックリストまで作成する(チェックリストを計画段階で作ることで、/review-plan が実装前にカバレッジを検証できる)。

記述の原則: 探索の代替を書き、付加的な説明は書かない

plan.md は /implement が持つ唯一の文脈(あとは自力の grep だけ)。したがって plan.md の良さは分量ではなく、/implement が自力で探さずに済む情報がどれだけ入っているかで決まる。

書く(探索の代替になる)	書かない / 最小限にする(探索を減らさない)
変更対象の正確なファイルパス	方式選択の長い理由づけ(1〜3 行で足りる)
追加・変更する関数 / メソッド / シンボル名とシグネチャ	却下した代替案の詳細(research.md にある)
参照すべき既存実装の具体的な場所(path:行 または関数名)	issue 本文の言い直し
具体的なテストケース(入力と期待結果)	コードの振る舞いを散文で描写した説明
データ形状・エラー処理・命名・配置の決定事項	一般的なベストプラクティスの解説

理由は 2 つ。

1. /implement の判断を消せる — 「どこを触るか」「どう構造化するか」が決まっていれば、/implement は二回目の設計をしなくて済む。/dev は M / L の implement を Opus で走らせる前提で組まれているので、ここの具体度がそのまま実装の精度になる。足りないと test 失敗ループに落ち、最悪 plan の書き直しに戻ってくる
2. 文脈量が減る — エージェントループは毎ターン会話全体を再送するので、plan.md の 1 行はターン数の分だけ運ばれる。パス 1 行(≒40 文字)は、それが不要にする grep の結果(数百行)よりはるかに小さい。逆に探索を 1 回も減らさない記述は、ターン数の分だけ掛け算で無駄になる

判断基準: ある一文を削ったとき /implement が grep を 1 回増やすなら、それは残す。増やさないなら削る。

引数

$ARGUMENTS は <issue> [mode] [lite] の形式で受け取る。

• <issue>: issue 番号(123、#123)または URL
• [mode]: auto / normal。auto の場合、本スキル内ではユーザーに質問せず、選択・判断はすべて推奨案で自動決定して、その選択理由と置いた仮定を plan.md に明記する。省略時は normal 相当(質問する)
• subagent として実行され AskUserQuestion が使えない場合(/dev から起動されたとき): normal でも直接は質問できない。質問は呼び出し元の指示どおり tmp/issues/<issue番号>/questions.json(AskUserQuestion と同じ構造: question / header / multiSelect / options[])に書き、最終メッセージを status: needs-input として一旦終了する。回答(answers)が渡されたら文脈を保ったまま続きから進める
• [lite]: 簡易計画モード。/dev が難易度 tier S(1〜2 ファイルの定型・局所変更、副作用なし)と判定した issue で使う。research.md を前提とせず、手順を次のように縮める:
  • step 3: gh issue view から AC を直接抽出する(research の fallback と同じ)。AC が曖昧なら通常どおり質問(auto は仮定を明記)
  • step 4: 候補列挙をせず、既存パターンに沿った 1 方式を採用し 1 行で理由を書く
  • step 5: 書き込み系 API があれば列挙する(無ければ「なし」と明記。1 件でも見つかったら lite の前提が崩れているので、plan.md 冒頭に「tier 昇格を推奨」と書く。/dev はこれを読んで tier を上げる)
  • step 6: タスクは 1〜2 個。Red / Green / Refactor の構成は維持する
  • step 7: DoD は AC 充足・既存テスト pass・lint / type check pass・checklist 全 pass の 4 項目を基本にし、issue 固有の基準があれば足す
  • step 8: checklist は AC ごとに正常系 1 項目 + 明らかな異常系のみ。UI 変更があれば撮影台本は通常どおり出す
  • 出力構造(必須セクション)は通常と同じ(後続スキルが同じ形で読めるように)。plan.md 冒頭に lite で作成した旨を書く

手順

1. プロジェクト固有の注意点を読み込む

プロジェクト(git root)の .agents/skills-config/plan/config.json を読み込み、attentions 配列に記載されたプロジェクト固有の注意点(副作用カスケード、暗黙の必須セット、フレームワーク特有のエントリポイント、過去の手戻り事例など)を把握する。ファイルが無ければ注意点なしとして続行する。以降の計画策定で該当する変更が含まれる場合、対応する波及範囲を計画に反映する。

2. 既存成果物の読み込み

tmp/issues/<issue番号>/ 配下の以下を確認し、存在すればインプットとして活用する。

• research.md(md が無ければ research.html。以降も同様): 受け入れ条件・影響範囲・実装方法の候補・リファレンス・盲点候補(必須相当。なければ step 3 で警告)
• plan.md / checklist.html: 既存の計画とチェックリスト(再計画モード: テスト失敗等で再実行された場合は、新規作成ではなく既存内容を更新する)
• implementation-notes.md: 再計画モードの場合、実装中に記録された逸脱(Deviations)を計画へ反映する

3. 受け入れ条件の取得

• research.md がある場合: その「受け入れ条件」セクションから AC を読み込む
• research.md が無い場合: gh issue view で issue を取得し、AC を抽出する。issue に AC が無い・曖昧な場合は AskUserQuestion でユーザーに確認する(本来 /research で行う作業の fallback。auto では確認せず、抽出した AC と置いた仮定を plan.md に明記する)

4. 実装方法の選択

• research.md の「実装方法の候補」セクションから候補を読み込む
• 各候補の概要・Pros / Cons・推奨度を整理して AskUserQuestion で ユーザーに選択してもらう(自由入力でのフィードバックも受け付ける)。auto の場合は質問せず推奨度最上位の案を採用し、選択理由を plan.md に記録する
• research.md が無い場合は本スキル内でコードベース調査 + 候補列挙を行ってから選択する
• 再計画モード(既存 plan.md がある)の場合: 既存計画で選択された方式を尊重し、変更が必要な場合のみ再選択する(auto 以外はユーザーに確認)

5. 副作用 identifier の抽出

選択された実装方法から、変更が引き起こす 副作用 identifier(コードに直接現れない間接依存の起点)を洗い出す。例:

• データ書き込み: コレクション名 / テーブル名 / ドキュメントパスのパターン(orders/{orderId} など)
• イベント発火: イベント名 / トピック名 / channel 名
• キュー投入: キュー名 / job 名
• ファイル出力: バケット名 / パスプレフィックス
• HTTP 発火: URL パス / endpoint 名
• 設定書き込み: 設定キー / feature flag 名

抽出方法:

• 変更対象コードに含まれる書き込み系 API 呼び出し(.set() .update() publish() emit() enqueue() 等)から identifier を列挙
• step 1 で読み込んだ config.json の attentions のうち、該当する identifier に関する注意点を波及範囲に組み込む

6. 受け入れ条件カバレッジ・タスク策定

選択された方法・AC・副作用 identifier をもとに、TDD(Red → Green → Refactor)の流れで実装計画を立てる。

• 各タスクは「テストを書く(Red)→ 実装する(Green)→ /simplify でリファクタリングする(Refactor)」の順で構成する
• 各タスクについて、次の 3 つを名指しで書く(「記述の原則」参照。/implement が自力で探さずに済むかはここで決まる):
  1. 対象ファイルの正確なパス(新規作成なら作成先のパスも)
  2. 追加・変更する関数 / メソッド / シンボルの名前とシグネチャ(既存を変更する場合は変更前後が分かる形で)
  3. Red フェーズで書く具体的なテストケース(「テストを追加する」ではなく、入力と期待結果を列挙する)
• 既存パターンに倣う場合は、倣う対象を path:行 または関数名で名指しする(「既存の実装に合わせる」では /implement が探しに行くことになる)
• データ形状・エラー処理の方針・命名・配置に選択の余地がある場合は、plan 側で決めて書く(/implement に委ねない)。本質的に実装時にしか決まらないものは「implement 判断」と明記して残してよい
• step 5 で抽出した副作用 identifier の波及先(trigger / subscriber / consumer 等)も影響範囲に含める
• AC ごとに対応タスクをマッピングする(AC1 → タスク 1, 2 のように、全 AC が 1 つ以上のタスクで満たされる状態にする)。マッピングできない AC があればタスク追加を検討する

7. 完了の定義(Definition of Done)の策定

タスクが全て完了した上で 「この issue 全体として何を満たせば完了とみなすか」 を明文化する。各タスク単位の完了条件(step 6)とは別に、issue 全体の合格基準として /dev の DoD ゲート(plan / implement / test / review のループ脱出条件) になる。

以下のカテゴリで漏れなく定義する:

• AC 充足: research で確定した全 AC が満たされていること(チェック方法も明記)
• テスト: 既存テストが全て通る / 新規テストの最低カバレッジ / checklist.html の全項目が pass(チェックリスト本体は step 8 で作成し、DoD からは参照する)
• 副作用検証: step 5 で抽出した副作用 identifier の波及先が想定どおり動作する(trigger 起動、subscriber 受信、設定反映など)
• コード品質: lint / type check / /simplify 通過、デバッグログ・コメント残骸の除去
• ドキュメント: 必要に応じて README / 設定ファイル / コメントの更新
• 後方互換性 / マイグレーション: 既存データやクライアントへの影響対応(必要な場合のみ)

各項目は 検証可能な粒度 で書く(「動作確認した」ではなく「checklist.html の項目が全 pass」のように、何をもって満たしたとみなすかが明確であること)。issue 固有の合格基準(性能目標、UI 仕様、外部連携の挙動など)も加える。

再計画モードでは既存の DoD を尊重し、追加要件があれば追記する。

8. 動作確認チェックリスト(checklist.html)の作成

AC・タスク・副作用 identifier を起点に、tmp/issues/<issue番号>/checklist.html を plan.html とは別ファイルとして 作成する(/test がチェック結果を書き込むため、計画書とは分離する)。

• 各 AC を満たすことを確認するための具体的なブラウザ操作・期待結果を記述する
• AC ごとに 正常系・異常系・エッジケース を網羅する(AC が「不正入力でエラー」なら、各種不正パターンを列挙)
• チェックリスト項目には対応する AC 番号を併記する(例: [AC1] 不正なメールでエラーが表示される)
• 副作用 identifier の波及先確認(trigger 起動・通知送信など)も項目に含める
• AC で明示されていないが確認が必要な観点(パフォーマンス・他機能への影響・UI 崩れなど)は 補助項目 として明示的に分けて追加する
• 各チェック項目は <input type="checkbox"> でブラウザ上で進捗を追えるようにする
• UI 撮影台本: 計画に ユーザーから見える UI 変更 が含まれる場合のみ、「UI 撮影台本」セクションを追加する。影響を受ける画面ごとに 1 行、撮影名(連番_内容。例: 01_ログイン画面)・URL・到達手順(ログイン等の前提操作)を表形式で列挙する。/capture スキルがこの台本を共通の手順書として before(実装前・/dev から呼ばれる)/ after(実装後・/test から呼ばれる)を同名ファイルで撮影し、/test が前後比較(compare.html)を生成する。UI 変更が無い issue ではセクション自体を出力しない(/capture と比較生成の自動スキップ判定に使われる)

必須セクション(見出しとして含める): 前提条件(環境・テストデータ等)/ 正常系 / 異常系 / エッジケース / 補助項目。UI 変更がある場合のみ UI 撮影台本 を加える。

再計画モードでは既存 checklist.html を更新する。内容が変わらない項目の checked 状態(前回のテスト結果)は保持する。UI 撮影台本の既存の撮影名は変更しない(撮影済みの screenshots/before/ とのファイル名対応が崩れるため。画面の追加は新しい連番で行う)。

9. plan.md / plan.html への書き出し(2 種生成)

計画を tmp/issues/<issue番号>/plan.md に書き出す(md が正。後続スキル /review-plan / /implement / /dev 等はこちらを読む)。続けて同じ内容を人間のレビュー用に plan.html としてレンダリングする(TDD フェーズの色分け・<details> 折りたたみ・Mermaid 図などのリッチ表現はこちらに)。

• 再計画モードでは md を更新してから html を再生成する(html だけを編集しない)
• checklist.html は例外として html 単一のまま(/test がチェック結果を書き込む状態ファイルのため。step 8 参照)

出力構造(必須セクション)

レイアウトやスタイル、図表の有無・種類は計画内容に応じて自由に設計してよい(テンプレートは置かない)。ただし他スキルが情報を抽出できるよう、以下のセクションは md の見出し(##)として含めること(html も同構成にする)。

• 概要: issue の目的と背景
• 選択された実装方法: 採用した方法と選択理由(1〜3 行。却下案の詳細は research.md にあるので繰り返さない。auto の場合は自動決定の根拠と置いた仮定も簡潔に)
• 受け入れ条件カバレッジ: AC ↔ タスクの対応表(テーブル推奨)
• 副作用 identifier: 書き込み先・発火イベント・設定キー等の列挙と、想定される波及先
• タスク一覧: 各タスクのタイトル(依存関係も)
• タスク詳細: 各タスクの対象ファイルパス・関数 / シンボル名とシグネチャ・Red / Green / Refactor の各フェーズ(Red は具体的なテストケース)・完了条件。倣う既存実装は path:行 または関数名で名指しする
• 完了の定義(Definition of Done): カテゴリごとの合格基準を検証可能な粒度で列挙(チェックボックスで表現するのが望ましい)

処理フロー・データフロー・コンポーネント関係・状態遷移などが計画の理解を助ける場合は、Mermaid や SVG で図を積極的に追加してよい。ただし図は plan.html 側に置く(人間のレビュー用)。plan.md は /implement が読むファイルなので、図で説明するより名前とパスで名指しする方が効く。

注意事項

• 実装方法の 選択は本スキルが行う(/research は候補列挙までで選択しない)
• 受け入れ条件は本スキルでは原則新規作成しない(/research で確定済みのものを使う)。research が無い場合のみ fallback として本スキルで AC を確定する
• チェックリストの項目は AC を起点に作る(AC こそが「動作する」の定義)。AC をカバーしない項目は補助項目として明示する
• issue の内容が曖昧で計画に落とし込めない部分がある場合は、ユーザーに確認を取る(auto では保守的な解釈を採用し、仮定として plan.md に明記する)
• config.json の attentions は LLM が解釈する自然言語のメモ。形式を厳密に判定せず、関連しそうな注意点は積極的に計画に反映する
• plan.md を長くすること自体が目的ではない(「記述の原則」)。/implement の探索を減らさない記述は、ターン数の分だけ無駄になる。削る対象は散文的な説明・背景・却下案の詳細で、削ってはいけないのはパス・シグネチャ・テストケース・決定事項
• 本質的に実装時にしか決まらない判断を無理に先取りしない。決められないものは「implement 判断」と明記する(曖昧なまま書かれている方が危険)。こうした判断が多く残る issue は tier XL に相当し、/dev は XL の implement を Fable で走らせる