Codexでテスト失敗を切り分ける前に決めること

このテーマをもう少し広げて見るなら、Codex CLIをCIで回す前に：exec・sandbox・承認境界を崩さない自動実行手順 と AI Coding Benchmark Kitの作り方：Bugfix・Feature Add・Test Repairを同じ条件で測る も合わせて確認してください。CIでCodexを動かす時のsandbox、承認、GitHub Actionsの境界を詳しく確認できるため。

3行まとめ

Type

種類。

Repro

再現。

Owner

担当。

Action

次の一手。

赤いCIをそのまま修正依頼にせず、判断材料へ変えます。

• テスト失敗は、修正前にfailure type、再現性、owner、次のactionへ分けます。
• Codexには、原因候補、追加で必要な情報、再実行条件、修正対象候補を出させます。
• flakyや環境由来の失敗を、アプリ本体や期待値の変更で隠さないようにします。

CIが赤い、E2Eが落ちた、typecheckが壊れた。こういう時に、Codexへ「直して」と投げたくなります。たしかに小さな失敗なら、それで通ることもあります。

ただ、テスト失敗には種類があります。本体bug、testの古さ、flaky、環境依存、外部API、runner差分、型定義の更新。これらを同じ「テストを直す」にまとめると、仕様を壊したり、期待値だけを書き換えたり、再発を見落としたりします。

この記事では、OpenAI公式のCodex Use Cases、Codex app features、Permissions、Worktrees、AGENTS.md docsをもとに、2026年6月1日時点の情報として整理します。Codexの機能やuse casesは更新され得るため、導入時は最新docsと自社CIの設定を確認してください。

この記事でわかること

Log

入力。

Flaky

揺れ。

Spec

仕様。

Gate

修正条件。

原因候補と修正条件を分けると、テスト変更で不具合を隠しにくくなります。

• test failure triageで見る分類軸
• CI logをCodexへ渡す前に整える情報
• flaky testと本体bugの分け方
• Codexに作らせるfailure table、cause memo、next action
• 修正へ進める条件
• PR単位、日次、週次で失敗を扱う運用

この記事は、AIコーディングツールの比較記事ではありません。比較条件を揃える話は、公開済み記事のAI Coding Benchmark Kitの作り方で扱っています。ここでは、実務で赤いCIを見た時に、Codexへ何を任せ、何を人間が判断するかへ絞ります。

前提知識

項目	内容	見方
Use Cases		QA用途。
Features		作業入口。
Permissions		権限。
Worktrees		変更分離。
AGENTS.md		test手順。

失敗ログの読解はread中心で始め、修正へ進む時だけ範囲を狭くします。

OpenAI公式のCodex Use Casesでは、QAやbug triage、codebase理解、作業補助のような用途が示されています。Codex app featuresは、projectやthread、terminal、worktreeなどの作業入口に関係します。Permissions docsは、どこまで読ませ、どこまで実行させるかを考える時に使います。

Worktrees docsは、修正へ進む場合に既存作業と分ける時に関係します。AGENTS.md docsは、test command、禁止操作、報告形式、未検証時の扱いをCodexへ伝える土台です。

公式情報で見る範囲

公式情報	この記事で見ること
Codex Use Cases	QAやbug triage用途
Codex app features	terminal、project、thread
Codex Permissions	read、write、networkの境界
Codex Worktrees	修正作業の分離
AGENTS.md	test手順と報告形式

bugfixとの違い

bugfixは、原因を直す作業です。test failure triageは、その前に「何が落ちているのか」「再現するのか」「誰が見るのか」「修正へ進んでよいのか」を整理する作業です。

triageを飛ばすと、テストを通すためだけの修正になりがちです。期待値を書き換える。待ち時間を伸ばす。selectorを雑に変える。関係ないrefactorを混ぜる。こういう修正は、CIを緑にしても、後で別の問題を生みます。

失敗を5種類に分ける

項目	内容	見方
Unit		小さい挙動。
Integration		結合。
E2E		操作flow。
Typecheck		型。
Env		環境。

種類を分けると、ownerと次のactionを決めやすくなります。

最初に、失敗を5種類に分けます。unit、integration、E2E、typecheck、environmentです。分類が決まると、ownerと次のactionが見えます。

unit testの失敗は、関数や小さなmoduleの仕様変化を示すことが多いです。integration testは、複数componentやserviceのつなぎ目を見ます。E2Eは、ユーザーflow、認証、画面、network、timingが絡みます。typecheckは、型定義、API変更、generics、dependency更新が関係します。environmentは、runner、cache、外部service、時刻、locale、OS差分が関係します。

unit

unit testは、小さな挙動を守ります。失敗した時は、対象関数、入力、期待値、直近diffを見ます。

Codexには、失敗したtest name、error message、関連diff、対象fileを渡します。いきなり期待値を書き換えさせず、仕様が変わったのか、実装が壊れたのかを分けさせます。

integration

integration testは、境界の失敗を拾います。DB、API client、queue、cache、schema、認証などが絡みます。

integration failureでは、どの境界で落ちているかを見ます。入力が間違ったのか、mockが古いのか、実serviceとの契約が変わったのか。Codexには、境界ごとの原因候補を出させます。

E2E

E2E failureは、判断が難しいです。UIが壊れたのか、test selectorが古いのか、待ち条件が弱いのか、認証状態が切れたのか、外部APIが遅いのか。

E2Eでは、trace、screenshot、test title、step、直近diffを見ます。Codexには、アプリ本体のbug、testの古さ、timing、環境の4つに分けて原因候補を出させます。

typecheck

typecheck failureは、型定義やAPI contractのズレを拾います。dependency更新、generated type、schema変更、strictness変更で起きやすいです。

Codexには、最初の数個のtype error、対象file、関連diff、最近のdependency変更を渡します。大量のerrorを全部渡すより、root cause候補を探させます。

environment

environment failureは、実装やtestではなく、実行環境に寄る失敗です。runner image、Node.js version、browser version、cache、locale、timezone、external serviceなどです。

environmentに見える失敗を、アプリ本体の修正で隠さないようにします。Codexには、実行環境、再現条件、直近のCI設定変更、local再現の有無を整理させます。

ログを渡す前に整える

1. 1Failing test

   対象名。

2. 2Error

   短い失敗。

3. 3Diff

   関連差分。

4. 4Command

   実行入口。

5. 5Mask

   秘密情報を除く。

長すぎるログより、再現に必要な情報を揃えます。

Codexへログを渡す前に、入力を整えます。長いlogをそのまま投げるより、失敗したtest、error、関連diff、実行command、再実行結果を揃えたほうが扱いやすくなります。

CI logには、内部path、private package名、環境変数名、tokenの一部、顧客IDが混ざることがあります。AIへ渡す前に、secret疑いの文字列がないかを見ます。

最小ログ

最小ログには、test name、error message、stack traceの上位、failed assertion、実行command、環境情報を入れます。

全部のlogを渡す必要はありません。必要なのは、原因へたどる材料です。長すぎるlogは、Codexにも人間にも読みにくいです。

関連diff

関連diffは重要です。テスト失敗だけを見ると、古い失敗なのか、今回の変更で壊れたのかがわかりません。

Codexには、PR diff、変更file、関連test file、最近触った設定を渡します。差分と無関係に見える失敗なら、flakyや環境由来も候補に入れます。

再実行結果

rerunで通ったかどうかも記録します。1回落ちて1回通ったなら、flaky候補です。毎回同じ場所で落ちるなら、再現性が高いです。

rerunで通ったから終わりではありません。再発しやすいtestなら、記録して週次で見ます。

secret疑いは渡さない

logにsecret疑いがある場合は、Codexへ渡す前に止めます。maskされていないtoken、private endpoint、顧客情報、内部URL、認証headerが入っていないかを確認します。

失敗ログは便利ですが、情報漏えいの入口にもなります。

flakyを別扱いにする

項目	内容	見方
Count		再現回数。
Runner		実行環境。
Time		時刻。
External		外部依存。

揺れるtestは、期待値変更ではなく観測と分離から始めます。

flaky testは、特別に扱います。たまに落ちて、たまに通るtestです。これを本体bugとして直すと、原因を外すことがあります。

flakyの判断では、再現回数、runner、時刻、外部依存、並列実行、resource不足を見ます。

再現回数

同じcommitで何回落ちたかを見ます。1回だけ落ちてrerunで通る。3回中1回落ちる。毎回同じstepで落ちる。これで扱いが変わります。

Codexには、run historyを短く渡します。単発のlogだけでは、flakyかどうかを判断しにくいです。

時刻とrunner

特定時刻、特定runner、特定browser、特定OSでだけ落ちる場合があります。CIの実行環境差分は、E2Eやintegration testで特に効きます。

Codexには、runner image、browser version、OS、Node.js version、parallelism、timezoneの差分を見せます。

外部依存

外部API、sandbox環境、メール配信、決済sandbox、feature flag serviceが絡むtestは、外部依存で揺れます。

外部依存が原因なら、アプリ本体を直すのではなく、mock、contract test、retry設計、監視対象を見直します。

Codexに作らせる成果物

Table

一覧。

Memo

原因候補。

Question

不足情報。

Ticket

次作業。

成果物を固定すると、PRごとの赤いCIを追いやすくなります。

Codexに作らせる成果物は、failure table、cause memo、next actionです。修正PRより先に、読むための成果物を作ります。

failure tableは、失敗一覧です。cause memoは、原因候補と根拠です。next actionは、修正、追加確認、rerun、owner確認、test debt化などの行き先です。

failure table

failure tableには、test name、failure type、error summary、reproducibility、owner候補、next actionを入れます。

PRでCIが複数落ちている時は、これだけでも価値があります。どれが同じ原因で、どれが独立した失敗かが見えます。

cause memo

cause memoには、原因候補を3つ以内で書かせます。候補ごとに、根拠、反証、追加で見るfileやlogを出します。

「たぶんここです」だけでは弱いです。なぜそう見たのか、何がまだ未確認なのかを残します。

next action

next actionは、修正、追加確認、rerun、owner確認、保留に分けます。

すべてを修正へ回さないことが大事です。再現性が低いものはrerunやwatchへ回します。仕様が不明なものはowner確認へ回します。secret疑いがあるlogは入力から除外します。

修正へ進める条件

項目	内容	見方
Repro		再現あり。
Spec		仕様確認。
Owner		担当あり。
Test		再実行入口。

条件が足りない失敗は、修正ではなく追加確認へ戻します。

修正へ進める条件は、再現できる、仕様が確認できる、ownerがいる、再実行入口がある、です。

この条件が揃わないままCodexへ修正させると、CIを緑にするための変更になりやすいです。

再現できる

再現できるとは、同じcommandで同じ失敗を確認できることです。localで再現できなくても、CI上で同じstepが落ちるなら、再現性があります。

再現できない場合は、すぐ修正せず、必要な情報を集めます。trace、screenshot、runner情報、直近の成功runとの差分を見ます。

仕様が確認できる

testが落ちた時、どちらが正しいのかを確認します。実装が間違ったのか、testが古いのか、仕様が変わったのか。

仕様が確認できないまま期待値を書き換えると、不具合を隠します。Codexには、仕様確認が必要な点を明示させます。

ownerがいる

ownerがいない失敗は、放置されます。unitならmodule owner、E2Eならflow owner、CIならplatform owner、外部依存ならintegration ownerのように分けます。

Codexにはowner候補を出させますが、採用判断は人間が持ちます。

日次・週次で回す

1. PR

   その場で分類。

2. Daily

   赤いCIを棚卸し。

3. Weekly

   再発をまとめる。

4. Monthly

   test debtを見る。

単発の失敗と recurring failure を分けて扱います。

test failure triageは、PR単位だけでなく、日次・週次で見ると効果があります。単発の失敗と、繰り返す失敗は扱いが違うからです。

PR単位では、そのPRで直すべきか、既存のflakyかを見ます。日次では、赤いCIを棚卸しします。週次では、recurring failureやtest debtをまとめます。

PR単位

PR単位では、今回のdiffで壊した可能性を見ます。関連file、関連test、直近成功runとの差分を確認します。

Codexには、PR内で直すべき失敗と、別ticketへ分ける失敗を分けさせます。

suite単位

suite単位では、特定test suiteの健康状態を見ます。E2Eだけ落ちる、typecheckだけ増える、integrationだけ時間切れになる、といった傾向です。

Codexには、週ごとの失敗をまとめさせ、繰り返すtest、時間帯、runner、ownerを表にします。

recurring failure

recurring failureは、放置すると開発速度を落とします。みんながrerunに慣れてしまうと、本当のbugも見落とします。

recurring failureは、test debtとして扱います。owner、影響、直す候補、放置した時のcostを残します。

よくある失敗

Expect

期待値だけ変更。

Ignore

flaky放置。

Dump

ログ丸投げ。

No owner

担当なし。

テストを通すことと、仕様を守ることを分けて見ます。

よくある失敗は、test期待値だけを書き換える、flakyを無視する、ログを全部渡す、ownerを決めない、の4つです。

Codexを使うと、修正案は速く出ます。だからこそ、修正前のgateが必要です。

test期待値だけを書き換える

期待値変更が正しい場合もあります。ただし、仕様が変わった根拠が必要です。実装が壊れたのに期待値を変えると、testは通っても品質は下がります。

Codexには、期待値変更が妥当な理由と、実装修正が必要な理由を分けて出させます。

flakyを無視する

flakyを無視すると、CIの信頼が落ちます。rerunすればよい、という文化になると、本当の失敗も流れます。

flaky候補は、すぐ直せなくても記録します。再現回数、runner、時刻、外部依存を残します。

ログを全部渡す

ログを全部渡すと、情報が多すぎるだけでなく、secretや内部情報の混入riskが上がります。

Codexへ渡すのは、原因調査に必要な最小ログです。長いlogはartifactとして保存しても、AIへの入力は絞ります。

FAQ

項目	内容	見方
Auto fix		条件後。
E2E		flow確認。
Rerun pass		記録する。

Codexの出力は、修正命令ではなく判断材料として扱います。

Codexに自動修正まで任せてよいですか？

条件が揃った小さな失敗なら可能です。再現できる、仕様が確認できる、ownerがいる、再実行入口がある場合です。揃っていない場合は、修正ではなく追加確認へ戻します。

E2E failureはどう扱いますか？

E2Eは、アプリ本体、testの古さ、timing、環境を分けます。traceやscreenshotがあるなら、Codexには原因候補と追加確認を出させます。selectorだけを直して終わらせないようにします。

rerunで通ったら閉じてよいですか？

一度だけなら閉じてもよい場合があります。ただし、同じtestが繰り返し落ちるなら、flaky候補として記録します。rerun passは、原因解決ではなく観測結果です。

AGENTS.mdには何を書けばよいですか？

test command、失敗時の報告形式、期待値変更の条件、未検証時の書き方、触ってよいtest範囲を書きます。Codexが「通りました」と言うだけで終わらないように、失敗ログと未確認点を残す形式にします。

---

次に読むなら

参照した主な情報源

• Codex Use Cases
• Codex app features
• Codex Permissions
• Codex Worktrees
• AGENTS.md in Codex

次に読むなら

更新履歴

1. 2026.06.01

   初版。

Codexのuse casesや権限機能は、導入時に公式docsで見直します。

• 2026年6月1日: 初版公開。