hdknr blog

計画と実装を分ける承認ゲート設計

「計画するAI」と「書くAI」を分業し境界に関所を置く設計。スコープ・テスト・フルスイートの3ゲートで巨大 diff とスコープ膨張を防ぐ

概要

1 つの AI エージェントに「計画も実装も」全部やらせると、スコープが膨らみ、レビュー不能な巨大 diff が出て、テストを通さないまま先に進む、という事故が起きやすい。処方箋は 「オーケストレーター（計画・レビュー・ゲート）」と「コーダー（実装のみ）」を役割分担し、その間に承認ゲートを置くこと。

要点は「AI を賢くすること」ではなく **「AI が暴走できない構造を外側に作ること」**にある。

なぜ 1 体に全部やらせると事故るのか

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

分業モデル

役割は 2 つだけ。

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

Orchestrator drives, Codex codes — 承認済みプランを 1 タスクずつ実行し、コミットごとにテストゲートを通し、最後に PR を 1 本だけ出す

3 種類のゲート

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

タスクごとに「変更してよいファイル」を allowlist として列挙し、実装後にスクリプトが実際の変更（追跡済み / ステージ済み / 削除 / リネーム / 未追跡）を照合する。allowlist の外に手が出ていたら hard stop。

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

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

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

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

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

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

1 タスクを 3 回試して通らなければ run を停止し、人にエスカレーションする。サイレントにオーケストレーターが乗っ取って無理やり進めることをしない。

実装上のノウハウ

コーダー役に OpenAI Codex CLI を使う場合の起動例。

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

持ち帰れる原則

モデル名やツールに依存しない。オーケストレーター役は Skills を扱えるハーネスなら何でもよく、この「分業 ＋ ゲート」という構造自体が CLAUDE.md やパイプラインに移植できる。

関連ページ

ソース記事