【Codex運用論】「自律させるな、テストを通させろ」— 2日間の失敗から学んだAIエージェントを制御する5つの鉄則
Codexを使っていて、「指示通り動かない」「頼んでもいない追加検証を始めて終わらない」「スコープを無限に広げて自滅する」といった経験はないでしょうか。
結論から言うと、Codexは「設計者」でも「作業員」でもなく、「受入テストをパスさせる実装者」として使うのが正解です。2日間の試行錯誤で分かった、Codexの成功率を劇的に上げる「渡し方」のノウハウをまとめました。
1. なぜ「手順書」も「目的」も失敗するのか？
うまくいかなかった回に共通していた理由は、「終わり」の判断をCodex自身にさせていたことでした。
- 「目的」を渡した場合：達成基準が曖昧なため、「まだ確認できることがある」「主キーの照合もしておこう」と自らスコープを広げ続けます。
- 「手順書」を渡した場合：書かれた手順で止まらず、手順にない確認作業や全件テストを自発的に足してしまいます。
Codexは「まだ足せることがある」限りコードを足し続ける性質を持っています。終わりをAI自身に決めさせてはいけないのです。
2. 成功する「渡し方」 5つの鉄則
成功した作業（1件20分〜50分で完了したケース）は、すべて以下のフォーマットに統一されていました。
① 受入（Acceptance Criteria）を先に渡す
「失敗するテスト1つ」または「このコマンドを実行するとこの値が返る」という確認手段を最初に提示します。これがCodexにとっての絶対的な「終わりの定義」となり、テストが通った瞬間に作業が停止します。
② 触るファイルを明確に列挙する
対象ファイル: src/utils/importer.py のように明示します。Codexは文脈の理解には波がありますが、「指定されたファイル以外は触らない」という境界線だけは極めて厳密に守ります。
③ 「やらないこと」を3つ書く
- 一般化・リファクタリング
- 追加の検証
- 別ファイルの整理
AIは単なる禁止命令を無視しがちですが、「受入テスト」と組み合わせることで威力を発揮します（受入テストに含まれない作業はすべて「不要なこと」として弾かれるため）。
④ 1回につき1件だけ渡す
受入テストが通ったら、即座にコミット＆pushしてそのセッションを終了します。「90分の枠が余っているからついでに」と複数タスクを詰め込んではいけません。
⑤ 守らせたいことは文章ではなく「道具（スクリプト）」で縛る
プロンプトの指示文（自然言語）で制約を守らせようとせず、環境やツールで物理的に縛ります。 - テストの選定 → related_tests.py などのスクリプトで自動決定
- セッションの停止 → 外部のスクリプト / 監視ツールで制御
- 文字数や投稿制限 → API / プラットフォーム側のバリデーションに任せる
3. 人間とCodexの役割分担
今回の検証から得られた、最も重要なパラダイムシフトは以下の通りです。
【人間の仕事】
・課題を「受入テストが書ける単位」まで細分化する
・調査、設計、意思決定を行う
【Codexの仕事】
・提示された境界線の中で、受入テストを通す実装だけを行う
砕けない仕事（どう設計すべきかの調査や判断）をCodexに投げると必ず失敗します。それは人間の仕事として手元に残し、純粋な「受入テストのグリーン化」だけをCodexに委任するのが最も高効率です。
4. 実際の改善アプローチと今後の検証
今回、既存の指示書をすべて「受入付きの小タスク一覧」に書き直しました。
- タスクの分割
- 旧：「Aの処理を修正する」
- 新：「PGコピー停止」→「注記の値を外出し」→「VACUUM」…といった9件の独立タスクに分解（各件に受入・触るファイル・90分枠を設定）。
- システムプロンプト（固定文）の改修
- 全作業者の共通指示に 「1回に1件、受入に無いことはしない」 を追加。
- プロンプトの再起動
- 6本のスレッド/ワーカーを新しい指示文で再起動。
次の数セッションで、「受入定義のない作業」や「ついで作業（不要なリファクタリング）」が排除されているかを計測・検証していきます。
まとめ
AIエージェントに自律的な「賢さ」を期待するのをやめ、「受入テストという狭い箱」の中に閉じ込めること。これがCodexの性能を100%引き出し、開発速度を安定させる唯一の鍵です。
- 6本のスレッド/ワーカーを新しい指示文で再起動。
Write a comment