hdknr blog
戻る

「計画するAI」と「書くAI」を分ける開発手法 — codex-build に学ぶ承認ゲート設計

TL;DR

きっかけ

X で流れてきた次の投稿がこの記事の出発点だ（元ツイート、引用元は作者 @cathrynlavery 本人）。

Fable と Codex を併用して開発している人向けの /codex-build というスキルがオープンソースになった。

  • Fable がオーケストレーション担当：計画、判断（taste）、コンテキスト管理
  • Codex が実際のコーディング担当
  • 両者の間に承認ゲートがあり、レビューとテストを通らないと何も出荷されない

要は 「頭脳」と「手」を別のエージェントに分け、境界に関所を置くという話だ。ここで言う「Fable」は Anthropic の Claude Fable 5（長時間タスク・計画立案に強いモデル）を指す。ただし後述するように、スキル自体は特定モデルを必須にしていない。本質はモデル名ではなく、この「分業＋ゲート」という構造の側にある。

なぜ 1 体のエージェントに全部やらせると事故るのか

AI コーディングを一度でも本気で回すと、だいたい同じ壁に当たる。

これらは「エージェントが賢くないから」ではなく、計画・実装・検証・出荷を 1 つのループの中で同じ主体がやっているから起きる。実装している当人が「これで十分」と自己判断すると、確認バイアスがそのまま出荷まで通ってしまう。

そこで有効なのが、役割を物理的に分けてしまう手法だ。

codex-build の分業モデル

codex-build は、この分業を Claude Code のスキル（SKILL.md にエージェントへの手順を書いておき、必要時に自動で読み込ませる仕組み）として実装している。全体像は次のとおり。

codex-build のオーケストレーター役とコーダー役の分業と、スコープ・テスト・フルスイートの3ゲートを通して1本のPRにまとめる開発フロー図

登場する役割は 2 つだけだ。

重要なのは、コーダーには「今回いじってよいファイル」と「1 タスク分の指示（ブリーフ）」しか渡さない点だ。全体像や意思決定はオーケストレーターが握り、コーダーは目の前の 1 タスクだけを閉じた範囲で書く。

README の説明文が端的だ ——「Orchestrator drives, Codex codes（オーケストレーターが運転し、Codex がコードを書く）。承認済みプランを 1 タスクずつ実行し、コミットごとにテストゲートを通し、最後に PR を 1 本だけ出す」。

3 種類の承認ゲートと失敗時の停止

この手法の肝は、フローの各所に置かれた「関所（ゲート）」だ。codex-build には性質の違う 3 つのゲートと、それらを補う失敗ハンドリングがある。

① スコープゲート（allowlist 強制）

タスクごとに「変更してよいファイル」を allowlist として列挙しておき、Codex が書いた後に付属スクリプト check_scope.py が実際の変更（追跡済み / ステージ済み / 削除 / リネーム / 未追跡）を照合する。allowlist の外に手が出ていたら hard stop（そこで止める）。

「ついでに直しました」を構造的に禁止する仕掛けだ。エージェントの善意に頼らず、範囲逸脱を機械的に弾く。

② テストゲート（コミット前）

各タスクの実装後、コミットする前にオーケストレーターがテストを実行する。グリーンでなければコミットしない。つまり 「壊れたコミット」がそもそも履歴に入らない。1 タスク = 1 コミットの粒度と組み合わさることで、あとから git bisect しても各コミットが常にグリーンという状態が保たれる。

③ フルスイートゲート（PR 前）

全タスクが終わったら、最後に全テストを回す。ここを通って初めて push し、PR を 1 本だけ作る。タスクごとの小さな緑と、全体としての緑を分けて確認するわけだ。

④ 失敗時のエスカレーション

3 つのゲートに加えて、失敗ハンドリングも設計されている。Codex が 1 タスクを 3 回試して通らなければ run を停止し、人にエスカレーションする。サイレントにオーケストレーターが乗っ取って無理やり進める、ということをしない。

Codex の呼び出し方

コーダー役の実体は codex exec サブコマンドの呼び出しだ。SKILL.md では概ね次の形で起動する。

codex exec "<ブリーフ本文>" \
  -C "$(git rev-parse --show-toplevel)" \
  -s workspace-write \
  -m "$MODEL" \
  -c model_reasoning_effort="$EFFORT" \
  < /dev/null

細部にノウハウが詰まっている。

導入とコマンド

Claude Code のプラグイン経由でインストールできる。

/plugin marketplace add cathrynlavery/codex-build
/plugin install codex-build@codex-build

実行は、事前に用意した承認済みプランを渡す形をとる。

/codex-build:build plan.md
/codex-build:build plan.md xhigh
/codex-build:build plan.md --model gpt-5.6-codex

注意: 元ツイートではコマンドが /codex-build と短縮表記されているが、正確なスラッシュコマンドは /codex-build:build だ（commands/build.md で定義）。また、同じ作者の別リポジトリ cathrynlavery/codex-skill は「Claude のプランを Codex にセカンドオピニオンとしてレビューさせる」別物なので混同しないこと。

plan.md は人があらかじめレビューして承認したプランである点がミソだ。「何を作るか」の合意は人とオーケストレーターの間で先に固め、その後の実装ループは自動化する。承認ゲートは実装フェーズだけでなく、その手前の計画フェーズにもあるわけだ。

この手法から持ち帰れること

codex-build は「Claude Fable 5 で計画し、OpenAI Codex で書く」という特定の組み合わせで紹介されているが、そこは本質ではない。実際、スキルのオーケストレーター側は “your agent (Claude Code, or any Skills-capable harness)” と汎用的に書かれており、Fable は作者個人の運用であってスキルの要件ではない。持ち帰るべきは次の設計原則だ。

  1. 計画と実装の主体を分ける — 実装した当人に「これで十分か」を判定させない。別役割（別コンテキスト）にレビューさせるだけで確認バイアスが大きく減る。これは以前書いた「AI エージェントにリファクタさせるときの「完了の定義」の引き方」の敵対的レビューと同じ発想だ。
  2. スコープを allowlist で機械的に縛る — 「触ってよい範囲」を宣言し、逸脱をスクリプトで弾く。善意ではなく構造で守る。
  3. コミット前にテストゲートを置く — 「テストが緑になったら完了」ではなく「緑でなければコミットさせない」。壊れた状態を履歴に残さない。
  4. 出荷は 1 PR に集約し、人が最終承認する — マージ（＝出荷の最終決定）はエージェントに委ねない安全境界にする。

この 4 つは、codex-build を使わなくても、自分の CLAUDE.md・スキル・CI パイプラインに移植できる。むしろ**「どのモデルが賢いか」より「AI が暴走できない関所をどこに置くか」の方が、実運用の品質を決める**。これがこのスキルの一番のメッセージだと思う。

まとめ

前の記事
建築設備メンテナンス視点で SORACOM の IoT を分類し直す — 保全高度化ラダーという第3の軸
次の記事
AIエージェントで採用ES・履歴書を事前スクリーニングする仕組みの作り方【2026年】