Codexでデバッグする方法｜再現条件から原因を狭め、修正を同じ条件で確かめる

Codexでデバッグを頼む時は、「直して」とだけ書かず、再現手順と変えてはいけない条件を渡し、先に再現してから修正を提案するよう頼みます。そのうえで、原因の候補を1つずつ確かめ、修正の後に同じ手順を実行し直します。この記事では、教材の不具合を使って、再現条件の固定、依頼文、仮説の否定、修正前後の比較、未確認の残し方を説明します。

この記事は、OpenAIの公式資料に基づく解説です。参照したのはPrompting、Best practices、Scheduled tasks、Sandbox、Browserで、いずれも2026年11月3日に確認しました。手順の組み立てと表の整理は編集部がまとめたものです。教材のコード、ログ、テスト結果は編集部が手元のPythonで実行して得たものです。Codexで実行した実測ではなく、Codexの出力でもありません。

Codexでデバッグを頼む前に何をそろえるか

公式資料のPromptingにある「Fix a bug」の節は、手元で再現できる不具合を対象に、再現手順と怪しいと思うファイルを渡すよう案内しています。資料は、渡すものを次のように分け、大まかな説明よりも再現手順と制約のほうが重要だと書いています。

資料の例は「設定画面で保存を押すと、保存しましたと出るのに反映されないことがある」という不具合で、起動のコマンドから再読み込みまでを番号で書き、最後に「まず手元で再現してから、修正を提案し、確認を実行する」と頼んでいます。修正後の確認として、同じ再現手順の実行を挙げています。

複雑な変更やデバッグでは、推論の強さをMediumかHighにすることが公式のBest practicesで案内されています。同じ資料は、完了の条件に「不具合がもう再現しないこと」を例に挙げています。

似た作業との違いも決めておきます。差分の欠陥を探すならコードレビュー、動作を変えずに構造を直すならリファクタリングです。この記事は、動かした時に起きる不具合の原因を調べる作業を扱います。

デバッグは再現条件を固定するところから始める

ここからは編集部が作った教材で説明します。見積もりの機能で「会員でない人に、たまに会員価格が表示される。定価3200円のカートが2880円だった」という問い合わせが来た、という設定です。コードは次のファイルに分かれています。

「たまに」のままでは、直ったかどうかを判断できません。まず、いつも起きる手順を探します。この教材では、同じカートを会員、非会員の順で見積もると必ず起きました。短いスクリプトにして、実行のたびに同じ結果になるようにします。

# repro.py（要点）
cart = {"A": 2, "C": 1}  # 定価の合計は3200円
cache.clear()
member = pricing.quote(cart, member=True)
guest = pricing.quote(cart, member=False)
print(f"RESULT member={member} guest={guest} expected_guest=3200")

$ python3 repro.py pricing
INFO cache MISS key=Ax2,Cx1
INFO calc subtotal=3200 member=True total=2880
INFO cache HIT key=Ax2,Cx1
RESULT member=2880 guest=2880 expected_guest=3200
REPRODUCED

再現の手順に入れるのは、入力、順番、期待する結果、実際の結果の4つです。問い合わせの言葉より、この短いスクリプトとログをCodexに渡すほうが確実です。実際の不具合で再現の手順が作れない時の扱いは、後の節で説明します。

Codexへのデバッグの依頼文はどう書くか

教材の場合、依頼文は次のように書けます。公式資料の例に、仮説の扱いと報告の形を編集部が足したものです。

不具合：非会員の見積もりに会員価格が返ることがある。

再現：python3 repro.py pricing を実行する。
期待：guest=3200 / 実際：guest=2880（ログを添付）

制約：
- quoteの引数と戻り値は変えない
- キャッシュをやめて隠すのではなく、原因を直す
- 修正は最小にする
- 回帰テストを足す

進め方：
1. まず再現手順を実行し、同じ結果になるかを報告する
2. 原因の候補を挙げ、それぞれを確かめる実験と結果を書く
3. 否定した候補も、否定した根拠と一緒に残す
4. 修正を提案してから実装し、同じ再現手順とテストを実行する

完了の条件：同じ手順でguest=3200になり、回帰テストが通ること。
確かめられなかったことがあれば、解決済みと書かず、残りとして書く。

進め方まで細かく書いているのは、この記事の主題が「原因を狭めること」だからです。公式資料の「まず再現してから」だけでも始められます。IDE拡張では、問題がありそうなファイルと一番近い呼び出し元を開いて頼む流れが資料に載っています。CLIでは、@でファイルを指定できます。規模が大きく見通しが立たない不具合は、編集の前に調べて方針を出す/planから始められます。

デバッグではコマンドを実行します。ネットワークなどサンドボックスの外が必要な場合、Codexは承認の設定に従って確認します。データを消す手順や本番環境への接続が再現に含まれる時は、依頼文の制約に、使ってよい環境を書いてください（編集部の注意点です）。

デバッグの仮説はどう否定して原因を狭めるか

原因の候補を挙げたら、1つずつ「これが原因なら、こう実行するとこうなる」と予想し、実行します。予想と違えば、その候補を外します。教材で編集部が実行した結果は次のとおりです。

決め手になった出力は次のとおりです。

H3 順番を逆にする guest=3200 member=3200（会員価格は2880のはず）
H3 間でキャッシュを消す guest=3200
H3 保存されたキー=['Ax2,Cx1']

順番を逆にすると、今度は会員に定価が返りました。最初に入った値が、もう一方にも使われているということです。ログのcache HITの時に計算の行が出ていないこととも合います。

ここで大事なのは、候補を外した根拠を残すことです。「端数処理は問題なさそう」では、次に調べる人が同じ確認をやり直します。「割引の関数を会員と非会員で0〜100000円まで実行し、別の計算との差は0件」と書けば、確かめた範囲が分かります。同時実行も「この症状の原因ではない」と言えるだけで、同時実行の問題がないことまでは確かめていません。価格表も、確かめたのはこのカートの商品だけです。

Codexの報告を読む時も同じです。原因の説明があっても、実験と結果が書かれていなければ、推測かもしれません。「どのコマンドで確かめたか」を尋ねてください。

デバッグの修正は同じ条件でどう確かめるか

教材の修正は、キャッシュのキーに会員区分を足す1行です。教材では修正の前後を同じ手順で比べるため、修正後をpricing_fixed.pyという別のファイルに置いています。カート、順番、キャッシュの初期化は同じで、変えたのは読み込むファイルだけです。実際の作業では同じファイルを直し、同じコマンドを実行します。

- key = ",".join(f"{sku}x{qty}" for sku, qty in sorted(cart.items()))
+ key = ",".join(f"{sku}x{qty}" for sku, qty in sorted(cart.items())) + f"|member={member}"

キャッシュをやめても症状は消えますが、原因が分からないまま残り、計算の回数も増えます。依頼文の制約に書いたのはこのためです。

修正の後は、同じ手順を実行します。

$ python3 repro.py pricing_fixed
INFO cache MISS key=Ax2,Cx1|member=True
INFO calc subtotal=3200 member=True total=2880
INFO cache MISS key=Ax2,Cx1|member=False
INFO calc subtotal=3200 member=False total=3200
RESULT member=2880 guest=3200 expected_guest=3200
NOT_REPRODUCED

次に回帰テストを足します。ただし、修正後に通るだけでは、そのテストが不具合を捕まえられる証拠になりません。修正前のコードで落ちることも確かめます。

テストには、同じ条件の2回目はキャッシュから返り、計算が走らないことの確認も入れました。これがないと、キャッシュをやめて症状を隠す修正でも通ってしまいます。実際、キャッシュを読まない版と保存しない版は、会員と非会員のこの確認で失敗し、金額を確かめる他のテストは通りました。

Best practicesの資料も、変更を頼むだけで終わらせず、必要なテストを作らせ、関連する確認を実行し、結果を確かめ、受け入れる前に作業を点検するよう案内しています。Codexが直した場合も、同じ表を埋めるよう頼めます。「テストが通りました」だけの報告なら、修正前のコードで落ちたかを尋ねてください。修正の点検の進め方はコードレビューの解説にまとめています。

デバッグの結果で未確認を解決済みにしない

再現手順で直ったことと、問題がすべて解決したことは別です。教材でも、次のことはまだ確かめていません。

• 問い合わせが出た人の見積もりが、本当にこの経路を通っていたか
• 修正前に保存された古いキーの値が、キャッシュに残り続けないか
• 同時に実行した時に、別の問題がないか
• このカートにない商品の価格が、価格表と合っているか

報告には「直ったこと」「確かめた方法」「確かめていないこと」を分けて書きます。公式資料のScheduled tasksには、自分の直近の変更からバグを探して直すスキルの例が載っています。このスキルは、最小の確認を優先し、確認を実行できない時は何を実行するはずだったかとその理由を書くよう指示しています。同じ指示を依頼文に入れておけば、未確認を報告に残すよう頼めます（効果を確かめたものではありません）。

再現できない時の頼み方

再現できない時も、怪しい場所を直して終わりにしないよう頼みます（次の表は編集部の整理です）。

デバッグの依頼に画面や定型の手順を足すには

画面の不具合なら、エラーの画面をそのまま渡せます。読み込ませ方と依頼文は画像を読み込ませる方法で説明しています。描画した画面にしか現れない不具合は、ChatGPTデスクトップアプリの内蔵ブラウザーで要素を指してコメントする方法も、公式資料のBrowserにあります。CLIとIDE拡張では使えません。

同じ調べ方を何度も使うなら、Best practicesが例に挙げるとおり、定型のデバッグの流れをスキルにできます。プロジェクトのテストのコマンドはAGENTS.mdに書いておくと、毎回説明せずに済みます。

Codexのデバッグで起こり得る問題と頼み方

次の表は編集部が想定した例で、Codexでの実測ではありません。依頼文で防げることを確かめたものでもありません。

まとめ：デバッグは再現手順を固定し、同じ条件で確かめる

Codexでデバッグを頼む時は、再現手順と制約を渡し、先に再現してもらいます。原因の候補は実験で1つずつ確かめ、否定した根拠も残します。修正の後は同じ手順を実行し、回帰テストが修正前のコードで落ちることも確かめます。確かめていないことは、残りとして報告に書いてもらってください。

Codexの全体像から確かめたい場合は、Codexとは？使い方と仕事でできることを読んでください。チームの不具合対応にCodexをどう組み込むかを整理したい場合は、法人向けのご相談も受け付けています。