Codexでテスト駆動開発を設計し検証する方法と実践のポイント

Codexとテスト駆動開発を組み合わせる理由

テスト駆動開発の価値は、テストをたくさん増やすことだけにありません。実装する前に「入力が何で、どんな結果なら成功か」を決めるため、曖昧な依頼を観測できる条件へ変換できます。Codexのように既存コードを読みながら変更案を作るエージェントでは、この変換が特に重要です。コードの量を増やす速さより、何を満たしたら完了と判断するかを先に固定したほうが、手戻りの理由を追いやすくなります。

OpenAIのCodex公式ページでも、Codexが設計、包括的なテスト、コードレビューを通じて品質を高める道具として説明されています（出典: https://openai.com/codex/ ）。この説明を実務に落とすと、Codexへ「実装して」とだけ伝えるのではなく、「この振る舞いをテストで表し、通過させ、変更の理由を説明して」と依頼する形になります。TDDは、Codexの生成力を検証可能な小さな単位へ向けるための枠組みです。

コードが動くことと要件を満たすことは違う

画面が表示される、関数が値を返す、コマンドが終了する、といった確認は出発点にすぎません。空文字、上限値、存在しない識別子、通信失敗などを受け取ったとき、何を返し、どの例外を伝え、状態をどう戻すかまで決まって初めて要件になります。Codexは不足した前提をもっともらしく補うことがあるため、テストで観測点を先に置くと、推測された仕様がそのまま残るのを防げます。

たとえば「割引率を計算する」と依頼する場合、通常の金額だけを例にすると、負の金額や小数、割引率が100を超える場合の扱いが抜けます。「不正な入力はエラーにする」のか「範囲内に丸める」のかをテスト名と期待値で示せば、Codexが実装方針を選ぶ余地を必要な範囲に絞れます。

TDDはCodexへの完了条件になる

Codexへ渡す指示は、自然な文章だけでも実行できます。しかし完了条件が「いい感じに直す」だけでは、どこまで調べ、何を変え、いつ止まるかが分かりません。テスト名、入力、期待値、失敗時の扱いを明示すると、テスト結果が作業の区切りになります。これは担当者が変わっても説明しやすく、同じ修正を別の環境で再確認するときにも便利です。

テストはCodexを縛るためだけのものではありません。最初に失敗するテストを置き、最小限の実装で通し、重複を整理するという順番を示せば、Codexが一度に広い設計を変える可能性を下げられます。小さく通る変更を積み上げることで、途中の差分にも意味を持たせられます。

TDDを依頼する前に決めること

CodexにTDDを任せる前に、対象範囲と観測方法を決めておきます。対象範囲はファイル名だけでなく、触れてよい層、変更してはいけない公開インターフェース、利用するテストコマンドまで含めます。これを先に言語化しておくと、Codexが周辺の整理へ広がりすぎるのを抑えられます。特に既存プロジェクトでは、テストの書き方やデータの準備方法に固有の慣習があるため、最初に読む資料を示すことが大切です。

既存の規約をまとめたAGENTS.mdがあるなら、その場所と優先するルールを指示に入れます。OpenAIのガイドでも、AGENTS.mdをリポジトリの作業方法や確認方法を伝えるファイルとして扱っています（出典: https://developers.openai.com/codex/guides/agents-md ）。ただし、ファイルに書かれた内容が最新とは限らないため、Codexには実際のテストファイルと実行結果も照合させます。

先に固定するのは振る舞いと境界

最初に固定するのは実装の形ではなく、外から観測できる振る舞いです。関数の内部でどのクラスを使うか、どの変数名にするかまで決めてしまうと、Codexがより単純な設計を提案できなくなります。一方で、戻り値の型、例外の種類、永続化の有無、時刻の扱いなど、利用側が依存する契約は曖昧にしないようにします。

境界を決めるときは、入力を「通常」「境界」「不正または失敗」の三群に分けると整理しやすくなります。連続した値なら最小・最大・その一つ外、文字列なら空・長さ上限・上限超過、一覧なら空・一件・大量というように、意味のある変化点を選びます。すべての組み合わせを最初から網羅するのではなく、仕様を変えたときに壊れると困る点を優先します。

既存テストを仕様の一部として読む

既存テストには、文書化されていない期待値が残っていることがあります。テスト名、フィクスチャ、モック、データベースの初期化、失敗時のメッセージをCodexに読ませると、新しいテストがプロジェクトの書き方から外れにくくなります。テストが少ない場合も、「少ないから作り直す」と判断せず、まず現状の振る舞いを確認することが安全です。

この段階では、実装を変えずに「現在のテストが何を保証しているか」を説明させるのが有効です。説明に誤りがあれば、実装を変える前に前提を修正できます。TDDの最初の赤いテストは、新しい要件を表すものなのか、既存の不具合を再現するものなのかを分けておくと、後の差分を評価しやすくなります。

Codexに渡す指示の組み立て方

指示は、目的、対象、制約、テスト、完了条件の順に並べると読みやすくなります。目的には利用者が得たい振る舞いを書き、対象には調査してよいディレクトリや入口を書きます。制約には公開APIを変えない、依存を増やさない、既存の命名規則に合わせるなどを入れ、テストには先に追加するケースを示します。完了条件では、テスト結果、差分の説明、未確認事項を明記させます。

次のような依頼なら、Codexが最初に調べる範囲と、実装を終える条件が伝わります。プロジェクトに合わせてファイル名やコマンドだけ置き換えて使えます。

目的: 会員登録時のメールアドレス正規化を追加する。
対象: src/Member/EmailNormalizer と既存のテストディレクトリ。
制約: 公開されている戻り値の型を変えない。新しい依存を追加しない。

進め方:
1. 既存の実装、テスト、AGENTS.mdを読んで現在の契約を説明する。
2. 空白を含む入力、すでに正規化された入力、不正な入力のテストを先に追加する。
3. 追加したテストが失敗することを確認し、最小の実装で通す。
4. 重複を整理し、対象テストと関連テストを実行する。
5. 変更ファイル、実行した確認、残った懸念を最後にまとめる。

完了条件: 期待する三つの振る舞いがテストで読め、既存テストが通り、
公開インターフェースの変更がないことを差分から確認できる。

目的は実装名ではなく利用者の振る舞いで書く

「正規化クラスを作る」だけでは、どの入力を受け、何を返すかが分かりません。「前後の空白を除いたメールアドレスを返し、形式が不正なら指定した例外を返す」のように、利用者が観測できる結果へ書き換えます。実装名は対象を絞る補助情報として残し、完了条件の中心には置かないほうが、設計の選択肢と検証の焦点を両立できます。

目的の文章に例を一つ入れるのも効果的です。ただし例一つだけを全仕様と受け取られないよう、「この例に加えて境界値と失敗系を確認する」と明記します。Codexが例を一般化しすぎたり、例外的な入力を無視したりする場合は、テスト名で不足を指摘すると、抽象的な再説明より修正点が伝わります。

完了条件には確認結果の読み方も含める

「テストを実行する」だけでなく、「失敗した場合は原因を説明し、仕様が曖昧なら実装を広げずに質問する」「通過した場合は対象外のケースを列挙する」と書くと、結果の解釈まで揃います。テストが通ることは必要条件ですが、テストが要件を表しているとは限りません。テストそのものが誤った期待値を持つ可能性を、完了条件の中で扱います。

また、確認できない外部サービスや本番データがあるなら、その限界も書きます。ローカルで再現できる範囲と、人間が別途確認する範囲を分ければ、Codexが未確認の成功を報告するのを防げます。結果の報告を定型化すると、次の担当者も差分と実行結果を短時間で追えます。

CodexでTDDを進める手順

ここでは、一つの小さな機能を対象に、赤・緑・整理のサイクルをCodexと進める手順を示します。最初から大きな機能全体を指定せず、利用者の振る舞いが一つに絞れる単位を選んでください。各段階でテスト結果と差分を確認し、期待と違えば次へ進まずに指示を修正します。作業の速さは、変更をまとめるほど上がるとは限らず、確認可能な単位を保つことで結果的に速くなります。

各段階でCodexに報告させる内容を揃えると、作業を止める判断も明確になります。テスト結果が予想と違うときは、次の段階へ進まず、直前の差分を確認してください。

Step 1: 対象コードと現在のテストを調べる

最初の依頼では実装を書かせず、対象コードの入口、呼び出し元、既存テスト、テストの起動方法を調べさせます。Codexには「変更はまだ加えず、現在の契約と不足しているケースを説明する」と伝えます。ここで出てきた説明を人間が確認し、勘違いがあれば修正してから次の段階へ移ります。調査段階を分けると、最初の推測がそのまま実装へ流れ込むのを防げます。

Step 2: 失敗するテストを一つ追加する

次に、最も重要な振る舞いを一つだけ選び、期待値がまだ満たされないテストを追加します。テスト名には条件と結果を含め、失敗メッセージから何が足りないかが分かるようにします。Codexにはテストだけを変更させ、実装を同時に直さないよう範囲を指定します。テストが本当に失敗することを確認できれば、テストが新しい要件を表しているという証拠になります。

Step 3: 通過する最小の実装を作る

赤いテストが確認できたら、通過に必要な最小限の実装を依頼します。この段階で将来のケースまで先回りして抽象化すると、実装とテストの対応が見えにくくなります。Codexには「新しいテストを通し、既存の契約を壊さず、不要なファイルは変更しない」と伝えます。テストが通ったあと、追加したコードが期待値を偶然満たしていないか、入力の扱いを差分から読み返します。

Step 4: 境界値と失敗系を広げる

基本ケースが通ったら、境界値と失敗系を追加します。ここでは複数ケースをまとめて依頼してもよいですが、各ケースの目的をテスト名に残します。Codexが入力を勝手に補正したり、例外を握りつぶしたりした場合は、期待する振る舞いをテストで先に固定し直します。失敗系では、エラーの種類だけでなく、呼び出し元が復旧できる情報を返すかも確認すると、実装の使い勝手を評価できます。

Step 5: 整理してから関連範囲を確認する

すべてのテストが通ったら、重複した条件、分かりにくい名前、過剰な分岐を整理します。整理の前後で同じテストを走らせ、振る舞いが変わっていないことを確認します。その後、対象機能に直接関係するテスト、モジュール全体のテストの順で範囲を広げます。広い確認で失敗したときは、直前の整理と機能変更を分けて読み、原因が分からないまま一度に直さないことが重要です。

テストケースを設計する具体的な視点

TDDで難しいのは、テストを書くことより、何を期待値にするかを決めることです。Codexは入力や分岐を列挙するのが得意ですが、列挙されたすべてが同じ重要度とは限りません。仕様上のリスク、利用頻度、失敗したときの影響を人間が見て、最初に固定するケースを選びます。テストの数を目標にせず、要件の変化を検知できるケースを優先すると、保守の負担も抑えられます。

OpenAIの活用資料では、Codexがカバレッジの薄い箇所や未確認の境界条件を見つけ、単体テストや統合テストの候補を作る使い方が紹介されています（出典: https://cdn.openai.com/pdf/6a2631dc-783e-479b-b1a4-af0cfbd38630/how-openai-uses-codex.pdf ）。これはテストを無条件に採用するという意味ではなく、人間が見落としやすい候補を得て、要件に照らして選ぶという使い方です。

正常系は代表値と最小の組み合わせから始める

正常系では、最も典型的な入力を一つ置き、期待する結果を明確にします。条件が複数ある機能でも、最初からすべての組み合わせを一つのテストに詰め込むと、失敗したときの原因が見えません。料金計算なら一件の明細、権限判定なら一つの許可条件というように、主となる振る舞いを一つに切り出します。その後、条件を一つずつ増やし、結果の変化を確認します。

テスト名には「何をすると、どうなるか」を含めます。「正常に動く」より「有効なメールアドレスの前後空白を除いて返す」のほうが、実装の意図と期待値を同時に伝えられます。Codexにテスト名の候補を出させても、名称が実際の要件を言い換えているかは人間が確認してください。

境界値は仕様が切り替わる場所を選ぶ

境界値は、値の端を機械的に並べるのではなく、処理の意味が切り替わる位置を選びます。年齢制限なら境界の一つ下、境界ちょうど、一つ上、文字数制限なら上限と上限超過を確認します。日時を扱う機能では、日付の変わり目、タイムゾーンの違い、うるう年など、計算の前提が変わる場所を候補にします。Codexには条件分岐から候補を列挙させ、その中から仕様上必要なものを選ぶと効率的です。

丸めや並び順も境界になりやすい領域です。小数の0付近、同じ値が続く一覧、空の結果、最大件数を超える結果を用意すると、見た目には動いていても不安定な処理を見つけやすくなります。テストデータは意味が分かる名前を使い、なぜその値を選んだかをテスト名か補足コメントに残します。

失敗系はエラー後の状態まで確認する

失敗系では、例外が出ることだけを確認しないようにします。失敗した後にデータが途中まで保存されていないか、再試行できる状態か、利用者へ表示する情報が欠けていないかを見ます。外部サービスを呼ぶ処理なら、応答が遅い場合、想定外の形式の場合、接続できない場合を分けると、回復方法が考えやすくなります。Codexには失敗後の状態を言葉で説明させ、その説明をテストに落とし込みます。

不正入力に対して「空の結果」を返す設計と「例外」を返す設計では、呼び出し元の扱いが異なります。どちらが正しいかをCodexに決めさせず、既存の呼び出し方と利用者の期待から選びます。失敗系のテストは実装の細部を縛るためではなく、失敗したときに守るべき契約を残すために書きます。

Codexのテスト結果と差分を読む

テストが通ったという結果だけを見て、作業を完了にしないことが大切です。テストが実行されていなかった、対象ケースが除外されていた、期待値が実装に合わせて変えられていた、という可能性があります。Codexには実行したコマンド、対象になったテスト、通過件数、警告、未確認の範囲をまとめさせます。人間はその報告と実際の差分を照らし合わせ、言葉と変更が一致しているかを見ます。

最新のOpenAIモデル向けガイダンスでも、コーディングではテストの期待、受け入れ条件、完了確認を明示し、必要な確認が通った後に範囲を広げる考え方が示されています（出典: https://developers.openai.com/api/docs/guides/latest-model ）。この考え方は特定のモデルに限らず、Codexを使ったTDDの確認手順にもそのまま応用できます。

テストが通っても差分の意図を確認する

差分を読むときは、追加されたコードだけでなく、削除された分岐、変更された例外、テストデータの書き換えにも注目します。テストを通すために実装側の期待値を緩めていないか、テストを無効にする設定が入っていないか、関係のない整形が混ざっていないかを確認します。Codexに「この差分で要件を満たす根拠と、満たしていない可能性がある点を分けて説明して」と依頼するのも有効です。

人間が見るべきなのは、Codexの説明の上手さではなく、説明が差分と実行結果で裏付けられているかです。説明とコードがずれていたら、まず「どの行がその説明に対応するか」を質問し、必要ならテストを追加します。検証の会話を記録しておけば、後で仕様を見直すときにも判断の経緯を追えます。

失敗メッセージを次の依頼に変換する

テストが失敗した場合は、「直して」とだけ返さず、失敗した条件、期待値、実際の値、変更してよい範囲を示します。Codexにはまず原因の仮説を一つ提示させ、テストや実装のどちらが仕様と違うかを判定させます。原因が確定していないのに複数の箇所を同時に直すと、失敗が消えても本当の問題が残ることがあるためです。

たとえば「空配列を受けたときに0ではなくnullになった」という結果なら、戻り値の契約、既存利用者、テストの期待値のどれを変えるべきかを切り分けます。修正後は失敗したケースだけでなく、最初に通っていた正常系も再確認します。失敗は作業の中断理由ではなく、次の小さな指示を作る材料として扱うと、TDDのサイクルが崩れません。

既存プロジェクトにTDDを取り入れるときの注意

既存コードへTDDを導入する場合、最初から全体を新しい設計へ置き換えないことが重要です。テストがない古い処理では、まず現在の振る舞いを記録するテストを置き、その後に変えたい要件のテストを追加します。現状を記録するテストと、新しい正しさを求めるテストを混ぜると、失敗したときに「バグを見つけた」のか「仕様を変えた」のかが分からなくなります。

Codexには、対象を一つの関数や一つの利用シナリオに限定し、触れない範囲を明記します。大きな改修を一度に任せると、テスト追加、実装変更、名前の整理が同じ差分に入り、レビューの負担が増えます。小さな単位で完了条件を満たしたら、次の単位へ進みます。これは短期的には確認が増えるように見えますが、失敗の原因を局所化できるため、全体の修正時間を抑えやすくなります。

テストがない箇所では現状確認から始める

テストのない処理にいきなり理想の期待値を置くと、過去から続く利用者との互換性を壊す可能性があります。最初のテストでは、現在の入力と出力、例外、外部への副作用を記録し、テスト名に「現状の振る舞い」であることを示します。そのうえで要件変更を別のテストとして書き、旧仕様から新仕様へ変わる点を明確にします。

Codexには、テストがない理由を推測させるより、呼び出し元と実データの形を調査させます。推測で作ったテストは、実際には使われていない経路を対象にすることがあるためです。調査で得た事実、仮定、まだ確認できない点を分けて報告させると、現状の理解を人間が監査しやすくなります。

外部サービスは境界で分けて検証する

外部サービスと直接通信する処理は、TDDの対象を一つに切り出しにくい領域です。通信の詳細と、自分のアプリが判断する内容を同じテストに詰め込むと、失敗の原因がネットワークなのか判定処理なのか分かりません。外部との境界では応答の形を固定し、判定や変換のロジックは手元で再現できるデータを使って確認します。

Codexには、外部応答の成功・失敗・想定外形式をそれぞれ用意し、境界の内側でどの状態を返すかをテストさせます。実際のサービスへ接続できない場合は、接続できないことを隠さず、手元で確認できた範囲と別途確認が必要な範囲を分けます。これにより、テストの通過を本番接続の保証と誤解しにくくなります。

Codexの更新とTDDの関係

Codexの利用環境が更新されると、同じ依頼でも提案されるテストの粒度や実装の選び方が変わることがあります。公式リリース一覧では、2026年9月9日に安定版0.154.0が公開され、その後9月11日には0.155.0-alpha.3.9などの試験版が掲載されています（出典: https://github.com/openai/codex/releases ）。新しい版を試すこと自体が問題なのではなく、変更の前後を比較できる確認材料を持つことが大切です。

テスト駆動開発では、テストが実装の安全網になるだけでなく、Codexへの依頼を比較する基準にもなります。同じテストと同じ完了条件を使い、どのケースを見つけたか、差分がどれだけ広がったか、説明と結果が一致したかを比べられます。モデルやCLIが変わったときも、印象だけで良し悪しを決めず、対象範囲に合った観測結果で判断できます。

更新直後は代表ケースで短く確認する

更新後にいきなり全体のテストを長時間走らせるのではなく、まず代表的な正常系、境界値、失敗系を短く確認します。代表ケースで明らかな挙動の変化がないことを見たうえで、関連範囲へ広げます。テストの失敗が環境由来か実装由来かを切り分けるため、更新前の結果、実行条件、使用した設定も一緒に記録します。

Codexの出力を比較する際は、最終コードだけでなく、調査の説明と提案されたテストも見ます。以前は見つけられなかった境界条件を見つけたのか、単にテストを増やしただけなのかを区別します。比較の軸を決めておくと、最新という理由だけで不要な変更を採用することを避けられます。

版を固定するより確認方法を固定する

特定の版に依存して指示を作ると、更新のたびに文章を作り直すことになります。版番号を記録することは必要ですが、それ以上に、対象コードを読む、失敗するテストを置く、最小実装を作る、関連範囲を確認するという確認方法を固定するほうが長く使えます。版が変わっても、同じ観測点を持っていれば差分を説明できます。

もちろん、結果に影響しそうな版の変更がある場合は、どの版で何を確認したかを記事や開発記録に残します。安定版と試験版を同じ扱いにせず、利用目的と許容できる変化を分けます。TDDは版の違いを消すための仕組みではなく、違いを見つけて判断できるようにするための方法です。

よくある失敗と立て直し方

CodexとTDDを組み合わせても、指示の範囲が広すぎる、テストが実装の後付けになる、期待値が曖昧なままになる、といった失敗は起こります。大切なのは、テストが増えたかではなく、要件と変更の対応が読めるかを確認することです。問題が起きたら、いったん変更を小さく分け、最後に通った地点まで戻ってから、失敗した条件を一つだけ再現します。

失敗を見つけたら、変更を増やす前に対象範囲と最後に通ったテストを記録します。小さな再現例を作ることで、Codexへの次の指示も具体的になります。

最初から大きな機能を任せない

「認証を作り直して」「画面全体を改善して」のような依頼は、TDDの一サイクルに収まりません。Codexが多くのファイルを変更すると、テストの追加理由と実装の変更理由が混ざります。まず一つの入力と一つの結果に絞り、正常系を通してから境界値へ進めます。機能の大きさではなく、失敗したときに原因を一つへ絞れるかを基準に分割します。

分割の候補が分からなければ、Codexに実装案ではなく「利用者が観測できる振る舞いの単位」を列挙させます。そこから人間が一つを選び、対象外の範囲を明記します。設計を先に細かく決めすぎず、テストで確認したい契約から小さな変更を始めると、依頼の修正もしやすくなります。

テストを実装に合わせて書き換えない

テストが失敗したとき、実装を直す前に期待値を変えてしまうと、テストが要件を表さなくなります。期待値の変更が必要なのは、要件の理解が誤っていた、または既存の契約を改めると決めた場合です。その理由を指示と差分に残し、テストの変更と実装の変更を同じ理由で説明できるようにします。

Codexが「このテストを通すために期待値を修正しました」と報告したら、変更の根拠を尋ねます。利用者の要求、既存コード、公式仕様のどれに基づく変更なのかを分ければ、便利そうな出力へ引っ張られにくくなります。期待値を変えるときほど、通常系と失敗系の両方を再確認します。

通過件数だけを品質の指標にしない

通過したテストの件数が増えても、重要な経路が対象外なら安心できません。テストが実際に走ったこと、異常系が含まれていること、テスト名が要件を表していること、関連する既存テストが壊れていないことを確認します。カバレッジの数値を使う場合も、数字が低い箇所をすべて埋めるのではなく、失敗の影響が大きい経路から見ます。

Codexには、現在のテストで保証できることと保証できないことを表ではなく文章で整理させてもよいでしょう。数値だけでは分からない前提、モックで置き換えた部分、実データで未確認の部分が見えるためです。品質の判断を一つの数値へ寄せず、テスト・差分・実行条件を組み合わせて評価します。

まとめ：CodexにTDDの判断材料を渡す

Codexでテスト駆動開発を進めるときの要点は、先に振る舞いを決め、失敗するテストを小さく置き、最小の実装で通し、差分と関連範囲を確認することです。Codexはケースの候補や実装の初稿を素早く出せますが、何を正しいとするか、テストが要件を表しているか、未確認の範囲をどう扱うかは人間の判断です。

2026年9月のようにCodex CLIの安定版と試験版が近い間隔で更新される時期には、TDDのテストを比較の基準として持つ意味がさらに大きくなります。最新版を使うことを目的にせず、同じ振る舞いを同じ確認方法で測り、改善が本当に必要なところだけ変更してください。まずは一つの小さな関数について、失敗するテストを一つ書くところから始めると、Codexとのやり取りを安全に具体化できます。