自律開発ループ(計画書ドリブン)

仕様書/実装計画書を入力に、計画を順序付きステップへ分解し、各ステップを テストファーストのマイクロループで自律進行する。各サブステップは レビューゲートを収束で通過してからコミットする。レビュー・コミットは 既存スキルに委譲し、本スキルは段取りとゲート管理に徹する。報告は日本語。

起動可否ゲート

本スキルを起動してよいのは、ユーザーからこの計画書/仕様書に基づく自律進行の明示的な指示が あったときに限る(例:「このステップから自律で進めて」「止まらず最後まで進めて」)。計画書の 内容説明・相談・単なる実装依頼(「このステップを実装して」等、マイクロループを回すとは言っていない 指示)だけでは起動しない——満たすべきなのは「マイクロループで自律的に何ステップも進めてよい」 という指示であって、「この計画に沿って作業して」の一般的な言い換えでは足りない。指示が無ければ 本スキルを起動せず、対象の計画書/仕様書と、自律進行してよいか(どこまでの範囲か)をユーザーに 確認する。確認を待たずに起動しない。

委譲先(各役割は既存スキルが持つ。再実装しない)

本スキルは段取りだけを持ち、各委譲先のルール・定義・終了条件はそのスキルを正とする。 ここに内部ルールをコピーせず、下記の委譲先一覧が示すスキルを [[スキル名]] の記法で起動して参照する(コピーを持つと片方の修正でもう片方の 修正が必要になり、いずれ食い違う)。本スキルが書くのは「いつ呼ぶ・結末でどう分岐する・何を渡す」 というオーケストレータ固有の判断に限る。

• レビュー: codex-review-loop(起動記法は [[codex-review-loop]])— レビューを反復し、ある結末で終了する。結末の種類と その定義・停止規定は review-loop-judgement の終了条件 が正。
• コミット: commit(起動記法は [[commit]])— コミットを委譲。起動時に渡す入力(codex レビューの最終応答原文／ レビュー済みファイル一覧)と前提ゲートは commit のワーカーへ渡すプロンプトの型・メインモデルの責務 に従う。

仕様整合(仕様書間の参照の記法・用語規約)は、ドキュメントを編集した本ループが直接確認する (フェーズ3)。参照の書き方・整合確認の観点は docs/conventions/cross-references.md、 用語規約表は docs/conventions/terminology.md を正とする。

設計の前提(なぜこの作りか)

• コミット = レビュー収束の証。[[codex-review-loop]] は収束以外の結末でも終わりうる (種類は当該スキルが正)。自律進行できるのは収束したときだけで、それ以外はループを止めて ユーザーに諮る。勝手な合理化でコミットしない([[commit]] 側のゲートが二重に止める)。
• サブステップごとにコミットして作業ツリーを空にするから、次フェーズのレビュー対象差分が そのフェーズの変更だけに絞れる(テストのレビュー時はテスト差分、実装のレビュー時は実装差分)。 ゲートを通すために各フェーズを独立コミットにするのは段取り上の必然。
• 各コミットは green を保つ。テストファーストでテストだけ先にコミットすると未実装ぶんが 赤になるので、未実装に対応するテストは xfail/skip で印を付けてコミットし、実装フェーズで 印を外して緑にする(下記のフェーズ1・フェーズ2)。赤いテストをそのまま履歴に残さない。

入力

• 計画書/仕様書のパス(必須)。渡されていなければユーザーに尋ねる。
• 計画書の見出し・章立てを1ステップとして上から順に処理する(分割案の事前合意は取らない)。 チェックリスト項目を持つ計画書なら、項目を1ステップとして扱う。
• 過大ステップの自動分割: 1つの見出しが独立した複数の振る舞い(別々のテストで検証でき、 別々に実装・コミットできる単位)を含むなら、見出し合意を取り直さずにサブステップへ分割して 1サブ振る舞いずつマイクロループを回す。判断目安: その見出しのテストが複数の独立した観点に またがる/変更が複数モジュールに分かれる場合は分割する。見出し単位はあくまで既定で、 マイクロループ(小さく変更→レビュー→コミット)を保てる粒度を優先する。

開始時の段取り

1. 作業ツリーのベースライン記録: git status で開始時点の未コミット差分を確認し、 差分のあるファイルの集合(=ベースライン汚染ファイル)を控える。これらは本ループの対象外 ベースラインで、以降の「フェーズの差分が残っていない」判定はこのベースラインを除いた差分で 行う(全体が空であることは求めない。無関係なユーザー差分を残差分と誤認しないため)。
   • 同一ファイル混入の回避: コミットは [[commit]] のファイル単位ステージング(git add <file>)で 行うため、ベースライン汚染ファイルを本ループで編集すると、そのファイルの既存 hunk まで フェーズコミットに巻き込む(この環境では git add -p 等の hunk 単位分離が使えない)。 よって、あるステップがベースライン汚染ファイルを編集する必要が出たら、自走で編集せず停止し、 ユーザーにそのファイルの commit/stash(退避)を依頼してから進める。汚染ファイルに触れない 範囲は通常どおり進めてよい。差分が多く本ループの作業と紛らわしいときも、進める前に確認する。
   • 受動的変化の検出: 上の停止規定は能動的編集が前提。汚染ファイルが副作用(formatter・生成物・ 誤操作)で変わると、除外判定では見逃す。そこで各コミット前に、ベースライン汚染ファイルの現在の 差分が開始時から変化していないことを確認する(開始時に各汚染ファイルの diff を控えて突き合わせる)。 変化していたら、フェーズが汚染ファイルに副作用を及ぼした証拠なので停止してユーザーに諮る (混入のままコミットしない)。
2. 着手前の検証(緑ベースライン確認): 計画の作業に入る前に検証 (docs/conventions/verification.md)を通し、 開始時点で赤が無いことを確認する。本ループは各コミットの緑維持を前提に進む (上記設計の前提)ため、着手前に既存の赤があると、本ループの変更が壊したものと誤認したり、 赤いベースラインの上ではフェーズ2の緑判定が無意味になる。既存の赤・収集エラーがあれば自走で 進めず、状況を要約して停止しユーザーに諮る(本ループと無関係な既存不具合をここで黙って踏み越えない)。 全体が緑であることを確認してから次へ進む。実行は run-and-bench(起動記法は [[run-and-bench]])の規律に従う。
3. 計画書を読み、見出し/章立てからステップ列を作る。各ステップの「やること・関係する実装/ 仕様・想定テスト」を一文ずつ控える。計画書がマイルストーン一覧/完了基準/チェックリストの節を 持つなら、それを完了の正本一覧として控える(完了判定はこの一覧に突き合わせる。下記完了の判定)。 見出しの本文が後続マイルストーンへ作業を先送りしている場合(例「まずAを入れ、Bは後段で段階導入」)、 その先送り分も独立ステップとして一覧に必ず入れる(本文を読み飛ばして見出しだけで列挙しない)。
4. TodoWrite にステップを登録(1ステップ=1 todo、進行に応じて in_progress/completed を更新)。 どこまで進んだかは git log と todo で復元できるようにする。
5. ステップを上から1つずつ、ステップ着手時の根拠検証を通してから ステップごとのマイクロループで進める。

ステップ着手時の根拠検証

各ステップのマイクロループへ入る前に、そのステップが挙げる問題と、修正方針が根拠として述べている 事実を、実コード・実仕様で1つずつ裏取りする。事実を確かめたら、その事実からこの方針が導けるか ——挙げられた問題を実際に解くか、別の破綻を生まないか——も同じ場で確かめる(事実だけ正しく結論が 誤っている計画は、事実の照合を素通りする)。計画書が「決定」と書いていることは、根拠の正しさも 導出の正しさも保証しない。

裏取りの結果、根拠が実コード・実仕様と食い違っていた、または方針がその根拠から導けなかったなら、 その方針をそのまま実装してはならない。食い違いの内容と、方針を実行した場合に何が起きるかを示して 止め、ユーザーに諮る。根拠が崩れた決定は決定として扱わない(計画書に書いてあることを検証の 代わりにしない)。

ステップごとのマイクロループ

各ステップは原則 フェーズ1(テスト)→ フェーズ2(実装)→ 必要ならフェーズ3(ドキュメント) の順。 純粋なドキュメント作業のステップはフェーズ3だけでよい。各フェーズは 変更 → レビューゲート → 収束ならコミットの同じ形を取る。

フェーズ1: テスト作成

1. 計画書とコードを根拠に、このステップの振る舞いを表すテストを書く/拡張する。 テスト方針の詳細は libs/vmd/vmd.md §4 に従う。
2. 未実装に対応するテストは pytest.mark.xfail(reason="impl pending: <ステップ名>") で印を付ける (コミットを緑に保つため)。既存実装で既に検証できるテストは印を付けない。 原則 skip でなく xfail を使う。理由: 実装後にテストが通れば xfail は XPASS として 表面化し「印の外し忘れ」を検出できるが、skip は実装後も無音で素通りし、外し忘れたまま 緑コミットが成立してしまう。skip は実行自体が不可能な場合(未導入の依存・未実装APIの import で収集が失敗する等)に限る。skip を使う場合も reason に同じ印 impl pending: <ステップ名> を必ず入れる(フェーズ2で行う印の残存検査が xfail/skip 区別なく この印の grep で残存を拾えるようにするため)。
3. 印付きテストが xfail/skip で赤が無いことを確認する(対象範囲に絞って回してよい)。
4. レビューゲート: [[codex-review-loop]] を起動し、テスト差分をレビューさせる (テストの妥当性・カバレッジ・仕様との一致を問う)。
5. 収束判定(下記ゲートの結末で分岐)。収束なら [[commit]] へ。

フェーズ2: 実装

1. テストを満たす実装を書く。フェーズ1で付けた xfail/skip の印を外す。
2. 緑を確認する(対象範囲に絞って回してよい)。緑にできない/方針が立たないときは ループを止めてユーザーに諮る。
3. 外し忘れ検査: このステップで付けた impl pending: <ステップ名> マーカーが残っていないか grep で確認する(残っていれば実装したのに無効化されたテストがある証拠)。残存ゼロを確認する。 緑確認(手順2)は印が残ったままでも成立しうるので、この検査を別に行う。
4. レビューゲート: [[codex-review-loop]] を起動し、実装差分をレビューさせる。
5. 収束判定。収束なら [[commit]] へ。

フェーズ3: ドキュメント(必要なときだけ)

フェーズ3が要るかの判定(機械的に適用する。曖昧なら「要る側」に倒し、過小更新を避ける): このステップが公開API・CLIオプション・デフォルト値・データ形式・ファイルレイアウト・利用手順の いずれかを変えた/新設したか確認する。該当する場合はフェーズ3を行う。配置規約(下記)で対応する ドキュメント(libs/ のフォーマット仕様、各ツール直下のツール仕様、README、docs/specs/)を grep で確認し、既存の言及があれば追従(更新)、新規公開面でまだ言及が無ければ追記する (言及が無い=不要、ではない。新設こそ追記が要る)。計画書がドキュメント作成/修正を明示して いる場合も行う。配置規約: フォーマット層の仕様は libs/、ツール仕様は各ツール直下(CLAUDE.md のリポジトリ構成)。

1. 該当ドキュメントを修正/作成する。
2. 参照の記法・用語規約を直接確認する。 docs/conventions/cross-references.md の観点 (節参照・ファイル相互参照がMarkdownリンクの記法になっているか。リンク先の実在確認はこの点検で なく、コミット前に通す検証が担う)と、 禁止・注意表記 の表の表記で、 編集した(または編集に関係する)ドキュメントを read-only で点検し、候補を洗い出す。洗い出した候補の扱い:
   • 明白な候補(平文の節参照・裸のファイル参照、用語規約表の機械的な違反)で、このステップの変更に 関するものは反映する。反映後の差分は手順3のレビューゲートを通るので、誤反映はそこで止まる。
   • 例外規則が絡む/文脈判断が要る候補は自走で断定せず、論点を添えて要ユーザー判断として諮る (禁止・注意表記 の表は例外規則を持つため、判断の重い候補を機械的に断定しない)。
   • 新規作成して未コミットのドキュメントも、編集した本ループが直接点検するので対象に含める (コミット前のドキュメントを点検から漏らさない)。これらの整合は手順3のレビューゲートでも 重ねて担保する(参照の記法・用語を codex に確認させる)。
3. レビューゲート: [[codex-review-loop]] でドキュメント差分をレビューさせる。
4. 収束判定。収束なら [[commit]] へ。

ドキュメント作業が独立して大きいときは独立ステップにしてよい。同一ステップに付随する小さな ドキュメント追従(関数名・節番号の更新等)は、実装コミットに混ぜずこのフェーズ3の1コミットに まとめる(複数の小修正を個別コミットに散らさない、という意味であって、フェーズをまたいで 混ぜてよいという意味ではない)。

ゲートの結末で分岐(全フェーズ共通)

[[codex-review-loop]] の結末で分岐する。結末を自分で覆さない(結末の種類と定義は当該スキルが正):

• 収束したとき → 全フェーズで、[[commit]] を起動する前に検証 (docs/conventions/verification.md)を通し緑を確認する ([[codex-review-loop]] はレビュー中に検証ツールを実行しない設計のため、照合・仕分けで適用した 修正が緑を壊していないかは、収束後のこの再実行だけが唯一の担保になる)。赤なら [[commit]] を 起動せずループを止め、状況を要約してユーザーに諮る。緑を確認したら [[commit]] を 起動する。プロンプトに必ず渡す:
  • codex レビューの最終応答テキスト原文(要約や地の文でなく、収束を含む原文そのまま)。
  • このフェーズでレビュー・変更したファイルの明示リスト(= ステージ対象。git add -A は使わない)。
  • 任意で一行の意図ヒント(例「ベジェ評価のテスト追加」)。 渡す入力の詳細・前提ゲートは [[commit]] に従う。コミット成功(ハッシュ・件名)を確認し、さらに git status で、開始時ベースラインを除いて、このフェーズの変更が全てコミット済み(=このフェーズ 起因の差分が残っていない)ことを確認してから次フェーズ/次ステップへ進む(ベースラインの既存差分は 対象外なので残っていてよい)。このフェーズ起因の残差分があれば次フェーズのレビュー対象に混入するので、 原因(ステージ漏れ・想定外の生成物)を調べて解消する。todo を進める。
• 収束でない結末で終わったとき → コミットせずループを止め、状況と論点を要約してユーザーに 諮る。結末の種類・どれで停止/再試行するかの具体条件は [[codex-review-loop]] の規定が正なので、 ここに種類を列挙しない(列挙すると委譲先の用語が変わったとき同期修正が要る)。本スキルの判断は 「収束か、収束でないか」の二分岐だけ。

加えて、計画書が曖昧で正しいテストが書けないときも推測で進めず、止めてユーザーに諮る(これは レビュー前段の判断で、本スキル固有)。

変更が無いフェーズ

そのフェーズで差分が出ないとき(例: ドキュメント修正が不要)は、レビュー/コミットを飛ばして次へ進む ([[commit]] は対象変更が無ければ何もせず報告して終わる)。

完了の判定(計画全体)

完了とは、計画書が挙げる全ステップ/全マイルストーンがコミット済みかつ緑であることを、計画書自身の 正本一覧(計画書がマイルストーン一覧・完了基準・チェックリストの節を持つ場合にそれを控えたもの。開始時の段取り)に突き合わせて確認したときだけを指す。直前にコミットしたステップを 到達点と錯覚して計画全体の完了扱いにしない(中間チェックポイントでの完了宣言を禁ずる)。

• 各コミット後に問うのは「計画は終わったか」でなく「正本一覧で次に未了のステップは何か」。 未了が1つでも残る限り、止まらず次ステップのマイクロループへ進む(自律進行が既定)。
• 計画書の削除可否・終了宣言・「一段落」判断は、正本一覧の未了ゼロを確認してからのみ行う。 自分が今やった範囲へスコープを縮めて完了を語らない。

進行と報告

• 各コミット後に一行で報告(何をコミットしたか・ハッシュ)。
• 停止時(収束以外の結末・計画書の曖昧など)は、どのステップ・フェーズで何が起きたかと論点を要約して諮る。
• 全ステップ完了時に、ステップ別のコミット一覧と残課題をまとめて報告する。

やってはいけないこと

• 収束していないのにコミットする(合理化・「テストが緑だから」「もう十分」で通さない)。
• ゲートの結末(収束以外)を自分の判断で収束扱いにする。
• レビューやテストを飛ばして実装をコミットする。
• 複数フェーズの変更を1コミットに混ぜてレビュー対象を曖昧にする(各フェーズ独立コミットが原則。 例外はない。同一ステップの小さなドキュメント追従はフェーズ3の1コミットにまとめるが、これは フェーズ3内の話でフェーズをまたぐ混在ではない)。
• 計画書にない仕様変更を自走で入れる(必要なら止めて諮る)。
• 計画書の記述を裏取りの代わりにして、根拠が実コード・実仕様と食い違うステップをそのまま実装する (ステップ着手時の根拠検証)。
• 直前にコミットしたステップを計画全体の完了と錯覚する(完了は正本一覧の未了ゼロで判定。完了の判定)。