elaborate

Prompt file imported from kenwata/dotfiles (.claude/commands/elaborate.md). Copyright stays with the author.

計画を、~/.claude/templates/BLUEPRINT.md §6 の五層設計に接続する設計書 docs/design/<slug>.md へ「詳細化」してください。本コマンドの責任は設計書までであり、TODO.md は作らない(タスク化は /breakdown docs/design/<slug>.md の責任)。要点:

1. 入力の判定(2 経路。混ぜない):
   • plan.md 経路(標準): 引数でパスが渡されたか、リポジトリ直下に plan.md がある場合。plan.md が一次情報。対象は 1 フェーズ(引数で §n や見出し名が指定されればそれ。無ければ AskUserQuestion で「どのフェーズを詳細化するか」を最初に確認する。plan.md に 本流: §<節番号> の行か「全体の制約」節が無い場合は、手順 3 の確認もこの同じ回の AskUserQuestion に束ねる。plan.md にフェーズ構造が無ければ全体を 1 フェーズとして扱う)。同一セッションに壁打ちの履歴があればそれも一次情報に加える。
   • plan mode 経路: 会話に承認済みプランがある場合。一次情報は 会話コンテキスト全体(探索結果・検討済み代替案と不採用理由・制約・ユーザー発言の生の意図)。プランファイルはそれを要約した骨子に過ぎない。行間の復元義務: 着地物はプランの転記・要約ではなく、プランで省略された前提・理由・境界条件を会話から復元して プランより詳細に 書く。
   • どちらも無い場合はその旨を明示し、plan.md のパス提示または計画内容の再確認をユーザーに求める。slug は計画内容から短いケバブケースで決める(plan.md 経路ではフェーズ名から)。
2. 前提確認: HANDOFF.md・docs/decisions.md の存在を確認。無ければ /initialize を先に実行するよう案内して中断する。
3. 本流の宣言の確認(plan.md 経路のみ): plan.md に固定書式の行 本流: §<節番号> が無ければ、対象フェーズを確認する問いと同じ回の AskUserQuestion で(手順 1 で束ねる。フェーズが引数で指定済みで手順 1 の問いが無い時は、ここで単独で問う)「plan.md のどの節が本流(達成すべきアウトカムへ直接進むフェーズ群)か」を確認し、plan.md に 1 行足して docs/decisions.md に 1 行追記する。設計書の「全体構想」行がその節を指せば本流、それ以外を指せば支線(道具立て・基盤整備など、本流を止めて行う作業)になり、/breakdown が支線の分解の前に本流の計器を通す(正は BLUEPRINT §6「本流の計器」)。本流と支線が plan.md の同じ節に混ざっているなら、支線を別の節へ分けることを提案する(分けるかどうかは利用者の判断)。本流か支線かを設計書へは書かない(全体構想の事実の転記になる)。あわせて、plan.md に見出しが §<節番号> 全体の制約 の節が無ければ、同じ回の AskUserQuestion で「全計画に効く制約(公開してよいもの、触れてはならない外部状態など)はあるか」を問い、答えを 1 項 1 制約で書いた節(無ければ - なし)を plan.md の末尾に足して docs/decisions.md に 1 行追記する(節の書き方は BLUEPRINT §6「全体の制約」)。
4. 未決定事項の洗い出しと確定: 設計書の各節(目的 / スコープ・非スコープ / 方針・構成 / 代替案と不採用理由)を埋めるのに必要で、入力にも会話にも無い事項を列挙し、AskUserQuestion でまとめて確認する(1 回最大 4 問。足りなければ回数を分ける)。捏造禁止の意味: 「黙って決めるな」であり、質問で埋めることは捏造ではない。質問せず推測で埋めることが捏造である。確認の結果が 全体構想に関わる決定(フェーズ構成・スコープ・方針の変更)なら plan.md を更新し docs/decisions.md に 1 行追記する。フェーズ内の詳細はここで決め、書き先は設計書とする。
5. 生成(冪等)— 着地させる前に proposal-reviewer エージェントを 1 回だけ起動し、設計書の下書き(作業ツリーの外に書く)と計画の解釈・slug・スコープ境界を自己完結のプロンプトで渡して反証させる。観点には /breakdown が差し戻す観点を含め、設計書が期待する出力や挙動を書いている前提は、エージェントに複製や一時ディレクトリで試作させて確かめる(誤った解釈や分解できない設計のまま永続文書が生成されると、以後のセッションがそれを正として動き、/breakdown の差し戻しで本コマンドをやり直すことになる。観点の一覧は BLUEPRINT §6「分解できるかの関門」)。返ってきた指摘は実測で精査して反映し、再レビューはしない:
   • mkdir -p docs/design → ~/.claude/templates/skeletons/design.md の placeholder を埋めて docs/design/<slug>.md を Write(既存 slug なら上書きせず diff 提示・承認後に更新。TODO.md に計画行を持つ(分解済みの)既存設計書の更新を本コマンドで行うのは、「目的」「スコープ / 非スコープ」または plan.md のフェーズ構成が変わる再計画だけ — 「方針・構成」節や完了条件の改訂で足りるなら /amend の対象であり、本コマンドを止めてそちらを案内する。まだ分解されていない設計書(/breakdown が設計の不足で差し戻した場合を含む)は、節を問わず本コマンドで更新する。分類の正は BLUEPRINT §6「変更の三段分類」)。冒頭の「全体構想」行は skeletons/design.md 冒頭コメントが定める固定書式 plan.md §<節番号> / <フェーズ見出しの逐語> で書く(節番号だけで止めない — 1 節に複数フェーズが並ぶ形が実在し、指すフェーズが特定できなくなる)。plan mode 経路で plan.md が無ければ「なし」。その次の「全体の制約」行も同じ冒頭コメントの固定書式で書き、plan.md の「全体の制約」節を指す(節が無い時だけ「なし」。制約の本文は転記しない)。「検討した代替案と不採用理由」を必ず埋める — 会話で検討したのに書き残さないことが最大の情報損失。「方針・構成」は番号付きの項(### 1. <見出し>)で書き(/breakdown とタスクが「第 n 項」で名指しする単位。変えてはならない契約は独立した項として立てる)、雛形の小見出し「前提と確かめ方」「実行者の裁量と停止条件」「段階と分解の指針」「落とし穴」を書く。設計書とそこから起こすタスクの読み手は、~/.claude/templates/model-routing.md の通常実装の役割のモデルである — 上位モデルの利用枠を設計と計画に充てるための分業なので、判定を要する規則(段階の境界、採否、閾値)は設計書で確定し、タスクには規則に当てはめる作業だけを残す。固定するものと裁量に任せるものの両方を列挙する(判断を全て潰すのではなく、境界を引く。名前や分け方のような局所の選択は裁量に渡してよい)。/breakdown は 1 回に 1 段階だけを分解する。「タスク分解」節は /breakdown が埋めるので placeholder のまま残す。
   • 設計書索引の更新: docs/design/index.md が無ければ ~/.claude/templates/skeletons/design-index.md をコピーし、placeholder 行を今回の 1 行で置き換えて作成する。有れば末尾の追記位置マーカー直前に 1 行追記する。列は 作成日(date +%Y-%m-%d。索引と設計書を同一コミットで着地させるため git の追加日と一致する)/ フェーズ(設計書の「全体構想」行と同じ逐語。plan.md が無ければ —)/ 設計書([<slug>](<slug>.md))/ 表題(設計書の # 設計: <表題> をそのまま)/ T(—。採番は /breakdown の責任)。既存 slug の更新では行を増やさず、表題が変わった時だけ表題列を直す。索引が無く既存の設計書が既に複数ある場合(索引導入前から動いているプロジェクト)は、新規 1 行だけを載せた索引を作り、既存分を遡って載せるかは報告でユーザーに確認する — 過去分の一括生成は既存の運用と衝突しうるため自動では行わない。
   • 計画が新規ディレクトリを必要とする場合: docs/architecture.md のディレクトリツリーと置き場の決定表を更新する(置き場は設計判断なのでここで決める。既存の決定表で置き場が決まるなら更新不要)。
   • 既存設計書を更新し、その設計書に既に TODO.md の計画行がある場合は、報告で「同じ計画行の未着手タスクの書き換え・廃止・追記を /breakdown が行う」ことを明示する(新しい計画行は起こさない)。
   • HANDOFF.md の「次セッションの最初の一手」を /breakdown docs/design/<slug>.md に更新する(書式は同ファイル冒頭の雛形コメントに従い全体上書き)。
6. 前提の確認: 設計書の「前提と確かめ方」のうち、Read・Glob・Grep(と本コマンドに許可された Bash)で確かめられる前提を、コミットの前に実際に確かめる。崩れていたら設計書を直してから着地させる(穴が /execute-task の実行中に初めて見つかると、/amend か再計画が要る。設計書の段階で見つければ書き直すだけで済む)。実装しないと確かめられない前提は、その旨を同じ小見出しに書く。
7. 検証(コールドスタートテスト): 「設計書だけを読んだ /breakdown(会話履歴なし・別セッションの可能性あり)が、検証可能な完了条件・対象パス・制約・落とし穴を持つタスクへ分解できるか」をセルフチェックし、会話にしか無い前提が残っていれば設計書へ書き足す。実行者が自走できるか も同じ読みで確かめる: 「実行者の裁量と停止条件」に固定するものと裁量に任せるものの両方が列挙されているか / 判定を要する規則が設計書で確定しており、通常実装の役割のモデルが上位モデルの判断なしに当てはめられるか / 「段階と分解の指針」に 1 タスクの大きさの目安が、この計画の単位で書かれているか。欠けていれば設計書へ書き足す(/breakdown がタスクを細かく割ることで補わせない — 足りないのは分割ではなく設計書の記述である)。あわせて①「全体構想」行が固定書式どおりで、指す節と フェーズ見出しの両方 が plan.md に実在すること(plan.md 経路のみ)②T 以外の未定義省略ID(M0, P1 等)が残っていないこと③設計書が挙げる対象パスが docs/architecture.md の決定表と矛盾しないこと ④docs/design/index.md に本設計書の行が 1 行だけ存在し、表題列が本文の # 設計: <表題> と一致すること ⑤「全体の制約」行が plan.md の「全体の制約」節を指し、節があるのに「なし」と書いていないこと、を機械的に確認する。
8. コミット(BLUEPRINT §6 の書式で自動実行): 要約 design: <slug> の設計書を策定、本文に「タスク:」「対応:」。手順 5 の反証の指摘を全て反映した設計書の指紋を、コミットメッセージ末尾の trailer に Breakdown-Readiness: <指紋> として入れる(指紋の計算と、値をハッシュだけに限る理由は BLUEPRINT §6「分解できるかの関門」。反証を通していない設計書には付けない)。docs/design/index.md は必ず同じコミットに含める(索引だけ次のコミットに遅れると、その間の履歴で索引が嘘になる)。plan.md・docs/decisions.md・docs/architecture.md を更新した場合も同じコミットに含める。
9. 報告: 生成/更新ファイルの一覧・確定した未決定事項・次の一手(/breakdown docs/design/<slug>.md)を簡潔に示す。

実行時機の原則: 対象は 計画粒度 だけ — 新しいフェーズ・施策(既存のどの T<n> の完了条件にも収まらない)、または既存設計書の「目的」「スコープ / 非スコープ」の変更(再計画)。ただし、監督が 1 セッションで書き切れる大きさの新しい施策は直接実装の経路で扱い、本コマンドを走らせない(正は ~/.claude/templates/BLUEPRINT.md §6「新しい施策の経路」)。既存設計書の一部と未着手タスクを直せば足りる変更は /amend に回す(穴一つのために設計書全体を読み直さないため)。既存 T<n> を実行する手段としての plan mode(タスク粒度)には走らせない — 判定基準の正は skeletons/todo.md §0。plan mode 経路は 承認直後の同一セッション が標準(行間が生きているのは承認直後だけ)。plan.md 経路にこの制約は無い(plan.md は repo 内の安定文書)。続けて同一セッションで /breakdown を実行するのが標準だが、別セッションでも成立する(設計書が自己完結していることを手順 7 が保証する)。