月曜の朝、受注システムを担当する開発者に「数量がゼロの注文を更新すると、想定と異なる状態になる」という障害票が届いたとします。これは説明のための架空例です。担当者の目的は、目の前の例外だけを消すことではありません。同じ入力で不具合を再現し、修正後には発生しないことをテストで示し、既存の注文処理を壊していないと確認したうえでレビューへ渡すことです。



AIを利用しない場合でも、障害管理システム、Gitリポジトリ、ログ検索、テストランナー、コード検索などの道具はすでに使われています。開発者は障害票とログを読み、再現条件の不足を補い、仕様書から期待動作を確認します。その後、関連しそうなハンドラーやドメインロジックを検索し、既存テストの書き方を調べます。原因の見当がついた段階で回帰テストを書き、修正前のコードで狙った理由により失敗するかを確認してから実装へ進みます。

難しいのは、一つひとつの作業よりも、情報が別々の場所に散らばっていることです。障害票には現象、ログには実行時の情報、仕様書には期待動作、既存テストには暗黙の設計判断が残っています。開発者はそれらを頭の中で結び直さなければなりません。テストが先に書かれず、修正後に追加されると、修正済みの実装に合わせたテストになり、不具合を本当に捕捉できていたのか判断しにくくなります。本記事では、この情報整理から失敗する最小テスト、限定的な修正、検証証拠の整理までをCodexへの段階的な依頼として組み立てます。

不具合修正の負担は、コードを書く時間だけでは測れません。資料探し、再現条件の正規化、関連コードの探索、テスト作成、修正後の確認が連続し、途中で前提が変われば前の工程へ戻ります。とくに保守期間の長いシステムでは、障害票の用語とコード上の名前が一致せず、検索範囲を広げるほど無関係な実装も候補に入りやすくなります。



Codexを使う場合も、入力と完成条件を変えてはいけません。比較対象は同じ障害報告、同じ仕様、同じリポジトリ状態、同じテスト環境です。成果物も、再現条件、回帰テスト、修正差分、検証結果という同じ形にそろえます。AIに多くの変更を作らせたことではなく、人が妥当と判断できる証拠までそろったかが品質条件になります。

| 工程 | AIを使わない場合 | Codexで補助する範囲 | 人が残す判断 |
| --- | --- | --- | --- |
| 資料確認 | 障害票と仕様書を往復して条件を整理する | 記述の一致点と不足点を列挙させる | 正式な仕様と追加確認の要否を決める |
| コード探索 | 用語を変えながら実装とテストを検索する | 候補ファイルと呼び出し関係を調査させる | 調査範囲が適切か判断する |
| 再現テスト | 既存形式を調べて入力と期待値を書く | 既存パターンに合わせた最小テストを作らせる | テストが障害の本質を表すか確認する |
| 修正 | 原因候補を試しながら実装を変更する | 承認した範囲で最小差分を作らせる | 仕様変更や設計変更の必要性を判断する |
| 検証 | 対象テストと関連テストを実行して記録する | 実行結果と未確認事項を整理させる | 副作用とリリース可否を判断する |

この対応関係を決めずに「直してください」とだけ依頼すると、探索、仕様解釈、テスト追加、実装修正が一度に進み、どの前提から差分が生じたのか追いにくくなります。回帰テストを先に失敗させる流れは、Codexの出力を無条件で信頼するためのものではありません。修正前後の挙動を観測可能にし、人が判断しやすい単位へ作業を分解するための仕組みです。

中心となる考え方は、Codexへの依頼を「調査」「レッド」「グリーン」「検証」に分け、各段階の間に人の承認を置くことです。レッドでは不具合を表す最小テストを追加し、修正前の実装で失敗する事実を確認します。グリーンでは、そのテストを通すために必要な範囲だけを修正します。検証では対象テストだけでなく、関連するテストや静的検査など、リポジトリで定められた確認を実施します。



OpenAIの公式クックブックでは、リポジトリの目的、コーディング規約、テスト基準、作業範囲などをAGENTS.mdへ記録する方法が紹介されています。AGENTS.mdは必須ではなく、Codexが認識する任意のリポジトリ指示です。また、作業を小さなフェーズへ分けることは、人による確認のしやすさや履歴の追跡に役立つ方法として示されています（出典: OpenAI Developers）。本記事ではその考え方を、単一の不具合修正へ縮小して適用します。

調査段階では書き込みを許可せず、障害報告とコードの対応、仕様上の期待値、既存テストの候補、未確定事項を報告させます。レッドへ進む承認後も、変更対象は原則としてテストだけです。テストが失敗しなければ、すでに修正済み、再現条件が不足、テスト対象が違うなどの可能性があるため、実装修正へ進ませません。

グリーンでは依存関係の更新、公開インターフェースの変更、無関係なリファクタリングを対象外にします。より広い設計変更が必要だと判明した場合は、当初の不具合修正から切り離して再計画します。Codexが調査と差分作成を連続して支援しても、仕様の優先順位、互換性、安全性、リリース判断は担当者とレビュアーに残ります。この境界が明示されているほど、生成された差分を短時間で読むことよりも、正しい観点で読める状態を作りやすくなります。

実践には、Gitの差分を読めること、対象言語とテストフレームワークを扱えること、テストの失敗理由を解釈できることが前提です。さらに、対象リポジトリで利用するテストコマンド、静的検査、生成物の扱い、変更禁止領域を把握しておきます。Codexにコマンドを推測させるのではなく、README、既存のCI設定、開発者向け文書など、リポジトリ内の根拠から特定させる方針にします。



入力は、障害報告、期待動作を示す仕様、関連ログ、既存テスト、再現に必要な最小データです。顧客名、認証情報、本番データ、社外秘のログをそのまま渡してはいけません。架空値や匿名化したフィクスチャで同じ条件を表せるか検討し、秘密情報を含むファイルやディレクトリは読み取り対象から除外します。外部サービスへの接続、デプロイ、コミット、プッシュなどは、不具合修正とは別の承認事項として扱います。

AGENTS.mdが存在する場合は、Codexに適用範囲を確認させます。ルートだけでなく作業ディレクトリに適用される指示があれば、テスト基準や変更境界へ反映します。存在しない場合に、新規作成を必須とする必要はありません。公式クックブックでもAGENTS.mdは任意と説明されており、既存プロジェクトの運用に合わせて構成を調整する前提です（出典: OpenAI Developers）。

開始前には、作業ツリーの既存変更を識別し、今回の差分と混ざらない状態を用意します。障害報告の再現条件には、入力値、事前状態、操作、期待結果、実際の結果を記載します。不明点は推測で埋めず、「仕様確認が必要」「ログだけでは確定できない」と明記します。準備の終了条件は、Codexがコードを書けることではなく、人が最小テストの期待値を説明でき、許可する変更範囲を指定できることです。

操作は五段階に分けます。以下は提案するお願い文の例であり、特定のリポジトリで実行・検証した結果ではありません。角括弧の部分を自社の情報へ置き換え、各段階の出力を人が承認してから次へ進みます。対象リポジトリをCodexが参照できる開発環境で、既存のリポジトリ指示に従わせてください。



第1段階は読み取り専用の事前調査です。関連ファイルだけでなく、期待動作の根拠と未確定事項を分けて報告させます。

コピーして使うお願い文:

このリポジトリで、次の障害を調査してください。
障害: [障害報告の要約]
再現条件: [入力、事前状態、操作、実際の結果]
期待動作の資料: [仕様書やチケットのパス]

適用されるリポジトリ指示、既存テスト、実装、検証方法を読み取ってください。
この段階ではファイルを変更せず、コマンドも破壊的なものは実行しないでください。
報告には、期待動作の根拠、関連ファイル候補、推定される処理経路、
不足情報、最小回帰テストの案、実装修正で触れる可能性がある範囲を含めてください。
事実と推測を分け、根拠のファイルを示したところで停止してください。

担当者は、障害票と仕様の食い違い、候補ファイルの過不足、再現条件の欠落を確認します。原因の断定ではなく、テストとして固定できる外部挙動が明確かを見ます。

第2段階では、レッドを作ります。変更対象をテストに限定し、失敗しない場合の停止条件も指定します。

コピーして使うお願い文:

承認した再現条件に基づき、障害を表す最小の回帰テストを1件追加してください。
既存テストの配置、命名、フィクスチャ、アサーション形式に合わせてください。
実装コード、依存関係、設定、公開インターフェースは変更しないでください。

リポジトリ内で確認できる対象テストの実行方法を使い、追加したテストを実行してください。
失敗した場合は、実行したコマンド、失敗したアサーション、期待値と実際値を報告してください。
テストが成功した場合、または障害と無関係な理由で失敗した場合は、
実装を変更せず、考えられる理由と次に必要な確認を報告して停止してください。

失敗という結果だけでは不十分です。構文エラー、フィクスチャ不足、環境依存ではなく、障害報告に対応するアサーションで失敗しているかを人が確認します。

第3段階は最小修正です。レッドの証拠を承認してから依頼します。

コピーして使うお願い文:

承認済みの回帰テストを通すための最小修正案を作成してください。
障害の原因と修正方針を短く説明してから、必要な実装だけを変更してください。
無関係なリファクタリング、依存関係の更新、公開APIの変更、設定変更は行わないでください。
修正後に対象テストを実行し、成功または失敗の実測結果を報告してください。
想定より広い変更が必要だと分かった場合は、変更を広げずに停止してください。

第4段階では、関連範囲を検証します。対象テストの成功だけで完了にせず、リポジトリ内で根拠を確認できる検査へ広げます。

コピーして使うお願い文:

現在の差分を読み、変更した処理から影響を受ける既存テストと検証項目を特定してください。
リポジトリに定義済みのコマンドだけを使い、対象テスト、関連テスト、
適用可能な静的検査を狭い範囲から順に実行してください。
実行した項目、結果、未実行項目、その理由を分けて報告してください。
失敗を隠すためのテスト削除、アサーション緩和、検査除外は行わないでください。

第5段階はレビュー用の証拠整理です。ここでは新しい変更を加えず、判断材料をそろえます。

コピーして使うお願い文:

これ以上ファイルを変更せず、現在の差分をレビューしてください。
障害の再現条件、追加した回帰テスト、修正の仕組み、変更ファイル、
実行した検証と結果、未確認の副作用、残るリスクを整理してください。
テストが修正前に失敗し、修正後に成功したことを、観測した事実だけで示してください。
推測、未実行、要承認の事項には明確な印を付けて停止してください。

この五段階により、Codexの作業を一括生成ではなく、証拠を伴う小さな変更として扱えます。途中で仕様が曖昧だと分かれば、コードを増やす前に担当者へ戻せる点も重要です。

架空の障害を「数量ゼロの更新要求に対する扱いが、仕様と一致しない」とします。入力には、匿名化した障害票、注文更新の仕様、対象エンドポイントの既存テスト、関連するバリデーション実装を用意します。期待値は仕様書から確定させる必要があり、Codexに都合のよい挙動を選ばせません。数量ゼロを拒否するのか、削除として扱うのか、更新しないのかは、製品仕様を決める人の判断です。



第1段階の成果物は、処理経路と根拠の一覧です。第2段階では、失敗するテスト差分と実行結果が残ります。第3段階では、原因へ限定した実装差分が加わります。最後に、検証結果と未確認事項を含むレビュー要約を作ります。出力を「修正しました」という一文で終わらせず、後から別の開発者が判断を再現できる形にすることが要点です。

成果物の例:

再現条件:
数量ゼロを含む更新要求を、既存の有効な注文へ送る

期待動作:
仕様書の該当箇所に記載された挙動

レッドの証拠:
追加したテスト名、実行コマンド、障害に対応する失敗内容

グリーンの証拠:
同じテストの成功結果と、変更した実装の要約

関連検証:
実行した既存テストと静的検査、結果、未実行項目

残る判断:
境界値、互換性、監視、リリース方法に関する未確定事項

これは実行結果そのものではなく、記録形式の例です。実際の成果物には、Codexが観測したコマンドと出力を記載し、人がログと照合します。また、回帰テストは内部メソッドの呼び出し回数だけに依存させず、障害報告で観測された外部挙動を可能な範囲で表す必要があります。内部実装へ密着しすぎるテストは、正しいリファクタリングでも壊れやすく、障害を防ぐという目的から外れるおそれがあります。

修正差分が最小でも、成果物はテストだけではありません。仕様根拠、再現条件、失敗理由、成功理由、検証範囲が組になって初めてレビュー可能になります。Codexには整理と候補作成を任せられますが、期待値が製品判断と一致しているか、テストが将来の変更を不当に縛らないかは、担当者が引き受けるべき判断です。

レビューでは、生成されたコードの読みやすさより先に、レッドの成立を確かめます。追加テストが修正前の状態で失敗し、しかも障害報告と同じ理由で失敗することが必要です。可能であれば、隔離した作業環境で実装修正だけを一時的に外し、回帰テストが再び失敗するか確認します。この確認は変更を失わない安全な方法で行い、既存の作業を上書きしてはいけません。



テストコードでは、入力が再現条件を過不足なく表しているか、期待値の根拠が仕様にあるか、アサーションが障害の外部挙動を検査しているかを見ます。正常値、境界値、無効値の区別も必要です。架空例なら、数量ゼロだけでなく、正の数量や仕様上許容される境界を既存テストが守っているか確認します。ただし、当初の障害と無関係なテストを大量に追加すると、レビュー範囲が拡大するため、別課題へ分ける判断も必要でしょう。

実装修正については、公開インターフェース、データ永続化、監査ログ、例外処理、並行実行、キャッシュなどへの影響を追います。Codexが「関連テストは成功した」と報告しても、実行されていない統合テストや外部サービスとの契約までは保証されません。実行ログと終了状態を確認し、環境不足で未実行になった検証は未確認のまま記録します。失敗した検査を今回と無関係と判断する場合も、その根拠を人が残します。

承認の最終条件は、回帰テスト、最小修正、関連検証、未確認リスクの四点をレビュアーが説明できることです。認証・認可、金額計算、個人情報、データ移行など影響の大きい領域では、専門担当者の追加レビューや手動確認が必要になります。Codexは判断材料を集められても、組織のリスク許容度やリリース可否を決定する主体ではありません。コミット、プッシュ、デプロイなどの外部状態を変える操作は、このレビューが終わった後の別工程として承認します。

効果を確かめるときは、修正全体の所要時間だけを比べない方が実態を捉えやすくなります。Codexを使うと調査や下書きがまとまる一方、依頼文の準備、出力の確認、誤った候補の除外に作業が移る可能性があります。資料探索、再現条件整理、テスト作成、修正、検証、レビュー手戻りに分け、開始と終了、やり直しの理由、成果物の不足を記録します。



| 記録対象 | 確認する内容 | 改善を判断する観点 |
| --- | --- | --- |
| 調査 | 読んだ資料と候補ファイル | 根拠のない探索を減らせたか |
| 再現条件 | 不明点と確認回数 | 実装前に曖昧さを発見できたか |
| テスト | レッド成立までの修正回数 | 障害を表す最小テストへ早く収束したか |
| 実装修正 | 変更ファイルと差分の範囲 | 無関係な変更を抑えられたか |
| 検証 | 実行項目と未実行項目 | 証拠と未確認事項を区別できたか |
| レビュー | 指摘と再作業の内容 | 仕様誤解や副作用を早い段階で見つけられたか |

比較には、規模と影響範囲が近い過去の障害を使います。ただし、難易度が異なる案件の時間を単純に並べても、Codexの効果とは切り分けられません。同じリポジトリ、同じ品質条件、近い種類の不具合で記録を重ね、準備と確認を含む総作業として評価します。実測値がない段階では削減率を掲げず、「コード探索の候補整理が再利用できた」「レッドが成立しない段階で仕様不足を発見できた」といった工程上の変化を記録します。

最初に選ぶのは、過去に修正済みで、原因と正解が分かっている非クリティカルな障害が適しています。現在の修正内容を見せずに、匿名化した障害報告と当時の仕様からCodexへ段階的に依頼し、作成された回帰テストが旧実装で失敗するかを確かめます。本番反映を伴わないため、依頼の粒度、停止条件、レビュー項目を調整しやすくなります。

その一件で、五段階すべてを自動化する必要はありません。読み取り専用の調査と最小テスト案だけから始め、根拠の示し方に問題がなければテスト作成へ広げます。次に試す小さな一歩は、候補となる修正済み障害を一件選び、障害票、仕様、既存テスト、検証コマンドの所在を一枚のメモへ整理することです。その準備自体が難しければ、Codexを動かす前に、チームの保守手順で欠けている情報を発見できます。

- Iterating Development Workflows with Codex（OpenAI Developers。提供資料内で公開日は確認できず、資料取得日は2026年11月1日です。本文では新機能として扱っていません）