Codex 失敗ケース検証：AI がコードを壊す理由とレビュー手順

git diff --stat を見ると突然 18 ファイルが出てきます。Codex に頼んだ作業は「ボタンの状態を直す」だけだったはずです。CI はすべて緑。でも diff を開くと、coverageThreshold が下げられ、flaky test が skip になり、さらに validateEmail() helper まで追加されています。しかもリポジトリには既に emailSchema があります。

これは Codex がわざとコードを壊したわけではありません。タスクの境界が広すぎ、検証フローが緩すぎたのです。ここでは「AI は信用できるか」という抽象論ではなく、失敗パターンの見分け方、検証ゲート、rollback と振り返りの流れを整理します。失敗を偶然ではなく、プロセス上の穴として扱うためです。

失敗パターン表：AI がコードを壊すときの典型

GitHub 上の 33k 件の agent-authored PR を対象にした arXiv の研究では、マージされなかった PR は変更が大きく、対象ファイルも多く、プロジェクトの CI/CD 検証に通らない割合が高い傾向がありました。これは AI agent の知能だけの問題ではありません。タスク分解、検証フロー、reviewer engagement が関係します。

よくある 9 つの失敗パターンを、判断シグナルと最初の対応と一緒に整理します。

パターン	見え方	判断シグナル	最初の対応
diff が大きすぎる	変更範囲が依頼を大きく超える	git diff --stat の変更ファイル数がタスク説明より明らかに多い。たとえば「ボタン修正」なのに 10+ ファイルが変わる	まず file list を見て、想定内の変更と範囲外の変更を分ける。範囲外はタスク分割か revert
テストが偽の緑	テストは通るがロジックは間違っている	diff で coverageThreshold が下がる、flaky test が skip になる、assertion が緩む	テスト設定が変わっていないか確認する。pre-change で失敗する回帰テストを要求する
間違ったディレクトリを触る	CI 設定や無関係なファイルを変える	タスクと無関係なのに .github/workflows/、Makefile、package.json scripts が変わる	AGENTS.md に CI/config 変更禁止があるか確認する。revert してルールを書き戻す
重複コード	既存 helper/util と同じものを生成する	新しい helper が追加されたが、リポジトリ内に同等の関数や schema がある	既存実装を検索する。重複なら revert し、既存実装を使うよう Codex に伝える
PR が大きすぎる	plan のない大きな PR	PR body が「fix issue」だけで、implementation plan、検証コマンド、rollback 説明がない	独立して review、検証、rollback できる小さな PR に分ける
CI を弱める	CI 設定を変えて通過させる	CI が失敗しているのに、business code ではなく test/CI 設定だけを変える	blocker として扱う。CI 変更を revert し、business code 側の修正を要求する
隠れた業務バグ	ロジックは正しそうだが業務制約を破る	権限チェックや入力検証が削除され、テストがその経路を見ていない	critical path を 1 本追い、副作用を確認する。reviewer の明示的な approve を要求する
untrusted input	外部入力を検証せず使う	ユーザー提供のデータや path を sanitization / validation なしで使う	input validation があるか確認する。なければ validation test を要求する
plan なしの大変更	plan の前に実装を始める	変更予定ファイル、触らないファイル、検証コマンドを列挙せずに Codex が編集する	先に /plan、または goal/context/constraints/done when を明確にしてから実装する

これらは単独で起きるとは限りません。「diff が大きすぎる」PR には、「間違ったディレクトリ」「重複コード」「テストが偽の緑」が混ざりがちです。GitHub Blog の agent PR review checklist でも、CI gaming、コード再利用の見落とし、隠れた correctness 問題、plan のない大 PR は agent-generated PR の赤信号として挙げられています。

最初の原則は、CI が緑かどうかだけを見ないこと。まず diff の範囲と戻しやすさを見ます。

タスク分割の判断フロー：大きな作業も Codex に渡せる

OpenAI の Best practices は、複雑または曖昧なタスクでは先に plan を立て、その後に実装へ進むことを勧めています。Codex は検証できる状態のほうが品質を出しやすく、小さく焦点の合ったタスクほど test と review がしやすくなります。

ただし「小さく分ける」は抽象的な合言葉ではありません。どこまで分けるかは、各ステップを独立して検証し、rollback できるかで決めます。

7 ステップの閉ループ：scope から update rules まで

Codex の変更には、次の検証ループを使います。

scope -> plan -> patch -> verify -> review -> merge/rollback -> update rules

各ステップには確認項目と戻る条件があります。

1. scope（タスク境界を決める）

確認すること：

• タスクは goal + context + constraints + done when として具体的に書けるか？
• auth、payment、notification のように複数サブシステムをまたぐか？
• CI 設定、database schema、外部依存に影響するか？

戻る条件：複数サブシステムをまたぐ、または CI/config に影響するなら、複数の子タスクに分けます。

2. plan（先に計画する）

確認すること：

• Codex は変更予定ファイル、触らないファイル、検証コマンドを先に列挙したか？
• plan はリスクと終了条件を明確にしているか？
• plan に rollback パスがあるか？

戻る条件：plan がない、または上記が含まれないなら、もう一度 /plan を要求します。

3. patch（変更を作る）

確認すること：

• git diff --stat は plan の想定ファイルと一致しているか？
• CI/config や無関係ファイルへの範囲外変更がないか？
• 既存 helper と同じ重複コードを生成していないか？

戻る条件：diff が plan と一致しない、または赤信号に当たるなら、step 2 に戻って plan をやり直します。

4. verify（変更を検証する）

確認すること：

• core path を覆うテストが追加されたか？
• そのテストは pre-change で失敗するか？
• CI status checks は required で、skipped ではないか？
• lint/pre-commit は通ったか？

戻る条件：関連テストがない、またはテスト設定を弱めて通しているなら、step 3 に戻って patch をやり直します。

5. review（人間が見る）

確認すること：

• diff の範囲は想定どおりか？
• critical path を 1 本追ったか？
• reviewer は明示的に approve したか？ AI の自己申告だけではないか？
• branch protection の required reviews/status checks/conversation resolution があるか？

戻る条件：reviewer が request changes した、または赤信号が見つかったなら、step 3 に戻ります。

6. merge/rollback（マージまたは戻す）

確認すること：

• 次章の検証証拠を満たしているか？
• hunk/file 粒度で独立して戻せるか？
• worktree で隔離され、失敗したら捨てられ、成功したら PR に進めるか？

戻る条件：証拠が足りない、または独立して戻せないなら、rollback して step 1 に戻ります。

7. update rules（ルールを残す）

確認すること：

• 失敗は AGENTS.md のルール不足から起きたか？ たとえば「CI 設定を変更しない」「5 ファイルを超える変更は分割する」などです。
• 禁止事項、受け入れ基準、rollback パスを AGENTS.md に書き戻すべきか？

対応：ルール不足が原因なら、AGENTS.md に書き戻します。

大きなタスクも Codex に渡せる

大規模リファクタリングを Codex に任せてはいけないわけではありません。ただし、各ステップを単独で rollback できる粒度まで分ける必要があります。AI で 10,000 行をリファクタリングした経験でも、小さく進めることとテストの安全網が重要でした。

十分に細かく分けられているかは、次で判断します。

• 各 patch は hunk/file 粒度で独立して revert できるか？
• 各 verify は pre-change で失敗することを証明できるか？
• 各 merge に reviewer approve と status checks があるか？

答えが「いいえ」なら、まだ大きすぎます。

Codex review pane の実践：検証はテストだけではない

検証時に最初に見るべきものはテストではなく、diff の範囲と rollback 粒度です。Codex app の review pane には、3 種類の view と hunk/file 粒度の操作があります。

3 つの view

review pane は Git リポジトリの状態を反映します。Codex の変更だけでなく、ユーザーや他タスクの未コミット変更も表示されます。

View	表示内容	使う場面
uncommitted changes	すべての未コミット変更（デフォルト）	現在の Codex タスクの変更範囲を見る
all branch changes	現在の branch と base branch の差分全体	複数 task の累積変更を含む全体を見る
last turn changes	直前の Codex turn の変更	直近の Codex 変更だけを切り出し、範囲外変更を素早く見つける

検証では、まず uncommitted changes を見て範囲が広がっていないか確認します。次に all branch changes で前のタスクの残りを確認します。最後に last turn changes で Codex が plan どおり動いたかを見ます。

inline comments と hunk/file 粒度の操作

review pane は diff の具体的な行に inline comments を付けられます。その comment は、後続の Codex 修正のコンテキストにもなります。

操作レベル：

• entire diff：diff 全体を stage/unstage/revert
• file：1 ファイルを stage/unstage/revert
• hunk：1 つのコードブロックを stage/unstage/revert（最小粒度）

CI 設定の削除のような範囲外変更を見つけたら、diff 全体を戻す前に、その hunk/file だけを revert できます。

PR context の読み込み

PR branch 上で GitHub access や gh auth login が使える場合、review pane は PR context、review comments、changed files を読み込めます。これにより、検証は「ローカル diff を見る」だけでなく、「PR diff と reviewer comments を見る」段階に進みます。

変わりやすい事実への注意：UI や slash command の細部は変わる可能性があります。公開前に正確な挙動が必要なら、公式ページを再確認してください。

検証の基本原則

検証はテストだけではありません。

1. まず diff の範囲が plan と一致するかを見る
2. 次に rollback 粒度が十分に小さいかを見る（hunk/file 粒度）
3. 最後にテストが追加され、critical path を覆っているかを見る

最初の 2 つを満たしていないなら、テストが通ってもコードが正しいとは言えません。

検証証拠チェックリスト：テスト通過だけでは足りない

GitHub Docs の protected branches の説明では、required status checks は successful、skipped、neutral のいずれかで protected branch に入れるとされています。GitHub Actions では skipped が success と扱われる場合があり、merge を止めないことがあります。

つまり「CI が緑」は「コード品質がよい」と同じではありません。必要なのは 1 つの信号ではなく、複数の証拠です。

次のチェックリストを使います。

コードレベルの証拠

• diff の範囲が想定どおりで、範囲外変更がない
• 重複コードがなく、既存実装を検索している
• タスクが明示的に許可していない限り、CI/config を変更していない

テストレベルの証拠

• core path を覆うテストが追加されている
• post-change だけでなく、pre-change で失敗することを示せる
• coverageThreshold の引き下げ、skip、assertion の弱体化がない

CI レベルの証拠

• lint/pre-commit が通っている
• CI status checks が required で skipped ではない
• チェックを通すためだけに CI 設定を変えていない

PR レベルの証拠

• PR body に implementation plan、検証コマンド、rollback 説明がある
• AI の自己申告ではなく、人間の reviewer が明示的に approve している
• branch protection の required reviews/status checks/conversation resolution がある

rollback レベルの証拠

• 各 patch は hunk/file 粒度で独立して revert できる
• worktree でタスクを隔離しており、失敗したら捨て、成功したら PR に進められる

branch protection と status checks

GitHub の protected branches では、次のような条件を要求できます。

• required reviews：指定数の reviewer が approve してから merge
• required status checks：protected branch に入る前に pass、skipped、neutral の状態が必要
• conversation resolution：すべての会話を resolved にしてから merge

これらは AI の外側にある merge gate です。AI が完了と言っただけで置き換えられるものではありません。

検証の順番

検証は次の順番で進めます。

1. まず diff の範囲を見る（file list と diff size）
2. 次に CI/test config が変わっていないかを見る
3. 次にテストが追加され、core path を覆っているかを見る
4. 最後に reviewer が明示的に approve したかを見る

順番を逆にしないでください。先にテストを見ると、範囲外変更や CI の弱体化を見落としやすくなります。

rollback と振り返り：壊れた後に何をするか

検証で範囲外変更や偽の緑が見つかったら、最初の対応は rollback です。同じ混乱した diff の上で Codex にさらに直させることではありません。

rollback 粒度：hunk から branch まで

変更範囲と失敗原因に応じて、適切な rollback 粒度を選びます。

粒度	使う場面	操作
hunk レベルの revert	CI 設定の削除など、1 つのコードブロックだけが範囲外	review pane でその hunk を選択 -> revert
file レベルの revert	ファイル全体に重複コードや範囲外変更がある	review pane でその file を選択 -> revert
branch 破棄	タスクの方向が間違っており、複数ファイルを戻す必要がある	git checkout main -> branch を削除

原則は、使える最小粒度で戻すことです。複数の hunk/file が問題なら、branch 破棄を考えます。

worktree で隔離する：失敗は捨てられる

同シリーズの Codex Worktree 実践では、worktree を使って並行タスクを隔離します。失敗した作業は捨て、成功した作業だけを PR に進める考え方です。

worktree 内のタスクがコードを壊したら、その worktree を削除すれば main workspace に影響しません。同じ branch で何度も revert するより安全です。

失敗後の対応：AGENTS.md に書き戻す

rollback 後は、失敗がルール不足から起きたかを判断します。そうなら AGENTS.md に書き戻します。

AGENTS.md に書くべきかは、次で判断します。

• 「CI 設定を変更しない」「5 ファイルを超えたら分割する」など、プロジェクト規約が不足していたか？
• 「テストは pre-change で失敗することを証明する」など、受け入れ基準が不足していたか？
• 「各 patch は独立して revert できる」など、rollback ルールが不足していたか？

該当するなら、次章の考え方で適切な AGENTS.md に書きます。

失敗後の対応：skill にする

失敗を skill にするかは、次で判断します。

• 業務制約を理解できないなど、Codex の能力境界から起きた失敗か？
• 複数 agent の協調など、複雑な多段階フローから起きた失敗か？
• diff 範囲、CI config、テスト追加を毎回見るような、繰り返し実行する検証フローか？

該当するなら、同シリーズの Codex Skills/plugins で扱うように skill 化を検討します。

AGENTS.md の置き場所：ルールはどこに書くか

Codex は run/session の開始前に instruction chain を作り、global と project の AGENTS.md を読みます。project レベルでは Git root から現在ディレクトリまで順に読み、近いファイルほど具体的なルールとして扱います。

つまり AGENTS.md は、リポジトリ root、サブモジュール、具体的な機能ディレクトリに置けます。Codex は現在位置に近い具体的なルールを優先します。

AGENTS.md の典型的な場所と内容

同シリーズの Codex 完整入門ガイドで扱う AGENTS.md テンプレートでは、典型的には次のように分けます。

場所	典型的な内容	例
repo root	repo layout、build/test/lint commands、engineering conventions	Project structure: src/frontend, src/backend, src/shared; build: npm run build; test: npm test; lint: npm run lint
src/frontend	frontend-specific conventions、PR expectations	frontend では React hooks のみ使い、class component は使わない。PR には Storybook story を含める
src/backend	backend-specific conventions、do-not rules	backend で database を直接操作しない。ORM を通す。controller に SQL を書かない
src/shared	shared utilities conventions	shared には pure function だけを置き、副作用を持たせない

失敗経験を書き戻す場所

失敗後は、原因に応じて書き戻す場所を選びます。

失敗原因	書き戻す場所	例
CI 設定を誤って削除した	repo root -> PR expectations -> do-not rules	明示的な許可なしに .github/workflows/、Makefile、package.json scripts を変更しない
5 ファイルを超える変更	repo root -> PR expectations -> do-not rules	5 ファイルを超える変更は分割する。各タスクは 3 ファイル以内を目安にする
偽の緑のテスト	repo root -> what done means	テストは core path を覆い、pre-change で失敗することを証明する。post-change だけをテストしない
重複コード	repo root -> engineering conventions	src/lib に helper を追加する前に既存実装を検索する。あれば既存実装を使う
plan なしの大変更	repo root -> PR expectations	3 ファイルを超える変更は先に /plan を出し、編集ファイル、触らないファイル、検証コマンドを列挙する
untrusted input	src/backend -> engineering conventions	すべてのユーザー入力は validation する。ユーザー提供のデータや path を直接使わない
隠れた業務バグ	src/backend -> engineering conventions	権限チェックや validation を変えたら、critical path を 1 本追い、副作用を確認する

ルール探索：近いファイルを優先する

OpenAI の AGENTS.md ドキュメントでは、project instruction は Git root から現在ディレクトリまでの chain として扱われ、近いファイルほど具体的です。

実務では次のように分けます。

• repo root の AGENTS.md：build/test/lint commands、CI を変更しないなどの共通ルール
• サブモジュールの AGENTS.md：frontend は hooks のみ、backend は SQL 禁止などの具体ルール
• 機能ディレクトリの AGENTS.md：特定 API の業務制約など、最も具体的なルール

失敗経験を書き戻すときは、次で判断します。

• CI 変更禁止のような全体ルールなら repo root
• frontend conventions のようなサブモジュール規約なら src/frontend
• 特定 API の業務制約なら src/backend/api/xxx

AGENTS.md の限界

AGENTS.md は範囲外変更や誤操作のリスクを下げますが、コードの正しさを証明するものではありません。Codex が AGENTS.md に従っていても、ロジックを間違えることはあります。

最後のゲートは、人間の reviewer が明示的に approve することです。AGENTS.md があるだけで品質が保証されるわけではありません。

AI PR を人間が review するときの赤信号

GitHub Blog の agent-generated PR review の助言では、まず file list と diff size を見て、CI/test config が変わっていないかを確認し、新しい helper が重複していないかを検索し、critical path を 1 本追い、pre-change で失敗するテストを要求します。

赤信号チェックリストは次のとおりです。

コードレベルの赤信号

• file list と diff size がタスク説明より大きい
• .github/workflows/、Makefile、package.json scripts など CI/test config が変わっている
• 新しい helper が既存 helper と重複している
• PR body が「fix issue」だけで、implementation plan、検証コマンド、rollback 説明がない
• 10 ファイルを超えるような大 PR

テストレベルの赤信号

• 新しいテストがない
• テストが post-change だけを見ており、旧挙動の失敗を証明できない
• coverageThreshold の引き下げ、flaky test の skip、assertion の弱体化がある

CI レベルの赤信号

• CI が失敗したのに、business code ではなく test/CI 設定だけを変えている
• CI status checks が passing ではなく skipped または neutral
• CI 設定を変えてチェックを通している

PR レベルの赤信号

• PR body が空
• implementation plan がない
• reviewer approve がなく、AI の完了報告だけ
• conversation が unresolved のまま

blocker と分割シグナル

種類	赤信号	対応
blocker	CI が失敗したのに test/CI 設定だけを変えた	request changes し、CI 変更を revert し、business code の修正を要求する
blocker	coverageThreshold 低下や skip など、偽の緑のテスト	request changes し、test config 変更を revert し、新しいテストを要求する
blocker	validation なしの untrusted input	request changes し、validation test を要求する
分割シグナル	10 ファイルを超えるような大 PR	request changes し、小さな PR に分ける
分割シグナル	PR body が空で implementation plan がない	request changes し、plan、検証コマンド、rollback 説明を追加する

reviewer の基本原則

reviewer が見ているのは、「AI は信用できるか」という抽象論ではありません。確認するのは次です。

1. diff の範囲がタスク説明と一致するか
2. CI/test config が変わっていないか
3. テストが追加され、core path を覆っているか
4. critical path を追って、隠れた副作用がないか

順番を逆にしないでください。先にテストを見ると、CI の弱体化や範囲外変更を見落としやすくなります。

結論

Codex がコードを壊す原因は、抽象的に「信用できない」からではありません。タスク境界が広すぎ、検証フローが緩すぎることが多いのです。実務で使うべきチェックリストは次です。

• 失敗パターン表：Codex の変更が壊れる典型を見分ける
• 7 ステップの閉ループ：scope から update rules までの受け入れフロー
• review pane の実践：テストだけで終わらず、diff 範囲と rollback 粒度を先に見る
• 検証証拠チェックリスト：テスト通過だけでなく、diff 範囲、テスト追加、CI status、人間の review、branch protection も見る
• rollback と振り返り：hunk/file レベルの revert、worktree 隔離、AGENTS.md や skill への書き戻し
• AGENTS.md の置き場所：repo root、サブモジュール、機能ディレクトリに範囲ごとのルールを書く
• 人間 review の赤信号：file list と diff size、CI/test config、テスト追加、reviewer approve の順に見る

このチェックリストを review 時に実際に使える形にしてください。Codex の変更を検証するたびに項目をなぞります。同じ検証フローが何度も出るなら、同シリーズの Codex Skills/plugins のように skill 化を考えます。

失敗は偶然ではなく、プロセス上の穴です。

次に読むもの

公開済み記事

• AI で 10,000 行をリファクタリング：実プロジェクトの振り返りとテストの安全網 — 小さく進めることとテストの安全網の実践
• Cursor リファクタリングガイド — 他の AI coding tool にも使える検証原則
• GitHub Actions CI workflow — status checks の基礎
• GitHub Actions workflow — PR workflow の基礎
• Codex Cloud agent ワークフロー — リモート実行、PR 検証、長時間タスクの閉ループ

同シリーズ（Codex 実践ガイド）

• Codex 完整入門ガイド — CLI、IDE、Cloud、desktop の入口
• Codex の安全と権限 — sandbox/approval でリスクを下げる
• Codex コードレビュー — review を受け入れゲートの 1 つにする
• Codex 自動化タスク — exec が作った patch も人間の review が必要
• Codex Worktree 実践 — 並行タスクを隔離する
• Codex Skills/plugins — 検証フローを skill にする
• Codex テスト駆動開発 — TDD + Codex
• Codex コスト最適化
• Codex の企業導入