Codexテスト仕様書の作成手順と実装前に見る確認項目7つ

Codexテスト仕様書は何を固定する文書か

Codexテスト仕様書は、「この関数にテストを追加して」と頼むための短いメモではありません。対象となる機能の目的、利用者から見える振る舞い、守るべき条件、問題が起きたときの扱いを、別の人が読んでも同じ判定にたどり着けるように整える文書です。Codexは既存のコードやテストを読んで候補を作れますが、何を正しいとするかという製品上の判断を、ファイル名だけから確実に復元できるとは限りません。先に仕様書を置けば、テストの数を増やすことよりも、確認すべき意味をそろえることへ集中できます。

テストコードは、仕様書に書いた条件を実際の入力と検証方法へ変換した成果物です。仕様書が「空の名前は拒否する」と書いているなら、テストコードは空文字、空白だけ、未指定など、どの入力を同じ条件として扱うかを具体化します。反対に、テストコードが通ったから仕様書も正しいとは限りません。期待値そのものが誤っていれば、誤った動作を固定してしまうため、文書の妥当性とコードの実行結果を別の段階で確認します。

期待する振る舞いを実装方法から切り離す

仕様書では、最初から関数名、クラス名、使用するライブラリを正解として書きすぎないことが大切です。利用者がどんな入力を渡し、成功時に何を受け取り、失敗時に何を知らされるのかを先に示します。実装の候補を縛る必要がある場合は、互換性や既存の公開形式など、守る理由まで添えます。そうするとCodexは、実装の細部を勝手に決めるのではなく、文書にある振る舞いと既存コードの関係を調べたうえでテスト案を組み立てやすくなります。

テストコードと仕様書の役割を分ける

テストコードは、同じ条件を何度でも確認できる形へ落とし込むものです。一方、仕様書は、なぜその条件を確認するのか、どこまでを今回の対象にするのか、まだ決まっていない部分は何かを共有します。両者を一つの長いコード例へ詰めると、判断の理由が読みにくくなります。Codexへは仕様書を先に読ませ、テストコードの差分と、仕様書では未決定の箇所を別々に報告させると、確認者が採否を決めやすくなります。

2026年8月25日の公式記事が示す記録の価値

今回このテーマを見直す理由は、OpenAIが2026年8月25日に公開した反復する作業とCodexに関する公式記事です。記事では、評価作業を始める前に過去の結果を読み、目的と計画を書き、確認を受けてから進め、実行した内容と結果の解釈を記録する例が示されています。これは特定のテストフレームワークを勧める内容ではありませんが、同じ種類の確認を何度も行うとき、会話の記憶だけに頼らず、次の担当者が読める資料へ変える考え方を示しています。テスト仕様書は、その考え方をコードの品質確認へ適用するための身近な器です。

テストの失敗は、単に赤い結果として消費するものではありません。入力が想定と違ったのか、期待値が古いのか、準備データが足りないのか、実装に欠陥があるのかを分けて記録すれば、次のCodexへの依頼が具体的になります。OpenAIの公式記事でも、うまくいかなかった方法や判断の理由を残すことが次回の作業に役立つと説明されています。テスト仕様書に失敗条件と判断欄を持たせると、テストを追加するたびに文書の精度も上がります。

目的と前回結果を最初に置く

仕様書の冒頭には、「何を安心して変更するための確認か」を一文で書きます。次に、前回どの条件が通り、どこで失敗し、何が未確認だったかを置きます。初めて作る場合は前回結果を「なし」と明記すれば十分です。Codexが過去のテスト結果を読むときも、単なるログの断片ではなく、今回の目的と結び付いた情報として解釈しやすくなります。確認者にとっても、テスト数ではなく、前回から何を学んだかを追いやすくなります。

事実と提案を別の欄にする

公式資料で確認できた内容、既存コードから読み取れた内容、今回の仕様として提案する内容を一つの文章に混ぜないようにします。たとえば「既存画面は空欄を受け付ける」は観測した事実、「空欄を拒否する」は変更提案、「既存利用者との互換性を確認する」は判断課題です。三つを分けるだけで、Codexが提案を既定の仕様と誤認しにくくなり、人が変更の必要性を見直す場所も明確になります。

仕様書に入れる確認項目7つ

七つの項目は、テストケースを大量に列挙するための順番ではなく、意味の確認から実行結果の判定までを漏れなくつなぐための順番です。すべてを長文にする必要はありませんが、空欄を残す場合は「未決定」と書き、Codexに推測させないようにします。小さな関数でも、対象、期待結果、境界条件、異常時の扱い、準備データ、確認方法、完了条件がそろえば、テストの抜けを話し合う土台になります。

Step 1: 対象と範囲を決める

最初に、どの機能、画面、API、関数を確認するのかを書きます。読むだけの関連箇所と、今回変更してよい箇所も分けて示します。対象を「注文処理全体」のように広くしすぎると、Codexが周辺の改善までテスト対象へ含める可能性があります。「割引率を計算する関数と、その呼び出し元の入力変換まで」のように、含める範囲と含めない範囲を同じ段落へ置くと、最初のテスト案を比較しやすくなります。

Step 2: 期待する結果を書く

正常な入力を渡したとき、戻り値、画面表示、保存される状態、呼び出される処理のどれを確認するかを決めます。数字だけでなく、単位、並び順、丸め方、表示文言など、結果の意味に関わる条件も必要です。「正しい値になる」ではなく、「税込み金額を小数点以下切り捨てで返し、通貨単位を変えない」のように書けば、Codexが曖昧な期待値を補いにくくなります。既存テストに期待値がある場合は、仕様書と一致するかを先に照合します。

Step 3: 境界条件を並べる

境界条件は、通常の値の両端と、そのすぐ外側を意識して書きます。0、最小値、最大値、上限の直前、上限を超えた値、空文字、長すぎる文字列など、機能の意味に合わせて選びます。すべての数字を機械的に試す必要はありませんが、どの境界を選び、なぜ代表になるのかを残すことが重要です。Codexには、境界を列挙した理由も短く説明させると、似たテストの重複を減らしながら抜けを見つけられます。

Step 4: 異常時の扱いを決める

入力が不正な場合、依存するデータがない場合、外部の応答が遅い場合などに、何が起きれば利用者にとって安全なのかを書きます。例外の種類、エラー表示、再試行の可否、処理を中断する位置が決まっているなら具体化します。まだ製品上の判断が済んでいない場合は、期待値を勝手に決めず「確認待ち」と記録します。異常系を後付けすると、成功するテストだけが増えて、失敗時の利用者体験が確認から抜けやすくなります。

Step 5: 準備するデータと前提を示す

テストを始める前に必要なデータ、設定、権限、時刻、言語、外部サービスの代替方法を明記します。データベースに既存の利用者が必要なのか、空の状態から始めるのか、同じ識別子を再利用してよいのかも重要です。準備方法が曖昧なままだと、Codexは手元で偶然見つけたデータを使い、別の環境で再現できないテストを作ることがあります。個人情報や本番のデータを持ち込まない条件も、対象と同じ強さで書いておきます。

Step 6: 確認方法と証拠を選ぶ

どのテストを実行し、どの表示、差分、ログ、画面、件数を見て判定するのかを決めます。単体の振る舞いは戻り値や例外、複数の部品の連携は保存状態や応答、画面の確認は利用者が見える結果というように、対象に合う証拠を選びます。Codexには「テストが通った」とだけ報告させず、実行した名前、結果、失敗した場合の条件、未実行の理由を残させます。確認者が同じ証拠を追えることが、テスト仕様書の価値です。

Step 7: 完了条件と保留点を定める

最後に、何がそろえば今回のテスト作業を終えるのかを決めます。対象範囲のケースが実装され、重要な境界と異常時が確認され、既存テストへの影響が説明され、残った保留点が記録されている、といった条件が候補です。「問題がないこと」だけでは判定できないため、未確認の環境や別の課題を完了条件から分離します。Codexが条件を満たせない場合は、無理に完了とせず、どの項目が不足しているかを報告させます。

Codexへテスト仕様書を渡して確認する手順

仕様書を作った後は、いきなり全ケースのコードを書かせるのではなく、内容を読ませ、解釈を確認し、対象を小さく分けて実行します。OpenAIのAGENTS.mdに関する公式ガイドでは、Codexが作業前にAGENTS.mdを読み、全体の案内とプロジェクト固有の案内を重ねて扱う仕組みが説明されています。プロジェクトで守るテスト規約があるならそこへ置き、今回だけの対象や完了条件はテスト仕様書へ置くと、長期的な決まりと一時的な依頼を混同しにくくなります。

Step 1: 仕様書と対象コードを先に読ませる

最初の依頼では、テストコードを変更する前に仕様書、対象コード、既存テスト、関連するデータ定義を読むように伝えます。Codexには、理解した対象範囲、現在の挙動、仕様書と食い違う点、追加で質問したい点を短くまとめさせます。この段階でコードを書かせないと、文書にない期待値を実装から拾って既定の仕様にしてしまう問題を早く見つけられます。読み取り結果が仕様書と合わなければ、確認者が文書を直すか、仕様の変更として承認します。

Step 2: テストケース案を確認する

次に、Codexへテストケースの案を表形式で出させます。入力、前提、期待結果、異常時の扱い、確認する証拠を一行ずつ並べ、正常系と境界条件と異常系がどれに当たるかを分けます。ここで人が見るのは、ケース数の多さではなく、仕様書の七項目が案へ反映されたか、同じ意味の重複がないか、判断待ちの項目を勝手に埋めていないかです。修正が必要なら、テストコードを書く前に仕様書かケース案のどちらを直すか決めます。

Step 3: 小さな範囲でテストコードを作る

ケース案が固まったら、関連する一つの機能からテストコードへ変換します。既存の命名、データ準備、例外確認、後片付けの書き方を読ませ、プロジェクトの形式に合わせるようにします。複数の機能を一度に変更すると、失敗した理由が仕様の誤りなのか、テストの準備不足なのか分かりにくくなるため、最初は代表的な正常系と一つの境界条件に絞ります。差分を読んでから、残りのケースへ広げる順番が安全です。

Step 4: 結果を仕様書へ戻す

テストを実行した後は、通過したケースだけでなく、失敗した条件、実行できなかった条件、想定外に見つかった既存の挙動を仕様書へ追記します。Codexの報告には、変更したファイル、実行した確認、結果、保留点を分けて書かせます。OpenAIのCodex CLI公式案内でも、作業中の差分やコマンドを確認し、レビューで変更を点検する使い方が説明されています。結果を会話の末尾に置くだけでなく、次に読める文書へ戻すことで、同じ失敗を繰り返しにくくなります。

仕様書のひな形を最初の依頼に使う

毎回ゼロから文書を考えると、対象範囲や完了条件の抜けが起きやすくなります。次のひな形は、プロジェクトの文体やテストの形式に合わせて書き換えて使います。項目をすべて埋められないときは、空欄にせず「確認待ち」と記入します。Codexへ渡す文章は長ければよいわけではなく、どの情報を根拠に、どの範囲を、どの結果で判定するのかが読めることを優先します。 短い文書でも、確認者が次の判断へ進める情報がそろっていれば十分に役立ちます。

# テスト仕様書

## 目的
このテストで、何の変更を安心して確認するのか。

## 対象と対象外
確認する機能・ファイル・画面・API。
今回の確認から外す場所と、その理由。

## 期待する振る舞い
正常な入力、返す結果、保存される状態、利用者への表示。

## 境界条件と異常時
最小値・最大値・空値・不正値と、失敗したときの扱い。

## 準備データ
必要なデータ、設定、時刻、言語、外部サービスの代替方法。

## 確認方法
実行するテスト、見る結果、記録する証拠。

## 完了条件と保留点
終わりと判定する条件、まだ人が決める項目。

仕様書を短く保つ場所を決める

仕様書には、Codexが次に読むべき情報への道筋と、今回の判断に必要な条件を置きます。ライブラリの一般的な説明や、変更と無関係な背景まで貼り付けると、重要な期待値が埋もれます。詳しい設計資料が別にあるなら、文書名や該当見出しを示し、Codexが参照できる場所を限定します。短い入口と詳しい資料を分けると、仕様書を更新する負担を抑えながら、根拠も失わずに済みます。

仕様の変更履歴を残す

テストが失敗したとき、コードだけを直すのか、仕様を変更するのかを判断した記録を残します。期待値を変えた場合は、利用者向けの仕様が変わったのか、文書の誤りを修正しただけなのかを書き分けます。変更日、判断した担当者、確認した結果を短く添えれば、後からテストが弱くなった理由を追えます。Codexには変更履歴を勝手に整理させるのではなく、事実と提案を分けて追記させ、人が最後の判断を行う形にします。

テスト結果をCodexと人でどう読むか

テストが通ることは重要ですが、それだけで機能の品質が証明されるわけではありません。仕様書にないケースが抜けている、準備データが現実と違う、期待値が実装に引きずられている、といった問題は、通過結果だけからは見えません。Codexには機械的な確認と結果の整理を任せ、人は仕様の妥当性、利用者への影響、保留点の扱いを確認します。OpenAIの公式資料でも、Codexの出力を人が点検し、差分や実行結果を見て判断する使い方が案内されています。

判断をそろえるには、仕様書、テストコード、実行結果の三つを横に並べます。仕様書の条件がケース案へ入り、ケース案がテストコードへ変換され、テストコードの結果が仕様書の完了条件を満たしているかを順に見ます。どこかが飛んでいれば、テストが緑でも「確認済み」とせず、未確認の項目として残します。テストの数を増やすより、三つの資料が同じ意味を指していることのほうが、変更を任せる範囲を決めるうえで大切です。

通過したテストを過信しない

通過は、その入力と環境で、書かれた期待結果が得られたという事実です。未記載の境界や、実際の利用者が行う連続操作まで確認したという意味ではありません。Codexが「すべて確認できた」と書いても、仕様書の対象外や未実行のケースがないかを人が照合します。報告には、通過、失敗、未実行、判断待ちを分けて記載させると、結果の見栄えに引きずられにくくなります。

失敗を次の改善へ変える

失敗したときは、テストを削除して緑に戻す前に、仕様書のどの条件に関係するかを確認します。実装の不具合なら再現条件と修正方針を残し、期待値の誤りなら変更理由と影響範囲を書きます。準備データや環境が原因なら、次回に必要な前提を仕様書へ加えます。失敗を記録として残すと、Codexへ同じ説明を繰り返す必要が減り、確認者が判断の経緯を追いやすくなります。

仕様書と既存テストのずれを見つける

既存テストが通っていても、仕様書の新しい条件をまだ表していないことがあります。逆に、既存テストが古い期待値を守っている場合もあります。Codexには、仕様書の各項目がどのテスト名や確認箇所に対応するかを表にさせ、対応がない項目を抜き出させます。対応先が見つからないこと自体を失敗と決めるのではなく、今回追加するのか、対象外として残すのかを人が判断し、その理由を文書へ戻します。

Codexテスト仕様書を運用に定着させるコツ

仕様書を作って終わりにしないためには、大きな文書を一度に完成させようとせず、変更の単位に合わせて更新します。新しい機能なら目的と期待結果を先に書き、既存機能の修正なら前回結果と影響範囲を先に書きます。テストの失敗やレビューで見つかった抜けは、次の作業でも役立つ条件へ変換します。OpenAIのAGENTS.md公式ガイドが示すように、プロジェクト共通の規約と個別作業の指示は置き場所を分けると、文書が肥大化しにくくなります。

チーム内で使う場合は、仕様書の作成者よりも、確認者が判定できるかを基準にします。担当者が変わっても対象、期待結果、準備データ、完了条件が読めれば、Codexへの依頼も同じ形で引き継げます。特定のモデル名や一時的な画面表示だけに依存せず、入力と結果と根拠を残しておくことが重要です。入口や版が変わったときも、仕様書が意味を保っていれば、テストコード側の調整だけで確認を続けられます。

共通規約と個別条件を二層に分ける

すべてのテストで守る命名、データの扱い、実行前の確認は、プロジェクト共通の案内へまとめます。今回だけの対象範囲、期限、確認したい不具合、完了条件は個別の仕様書へ置きます。どちらにも同じ内容を長く複製すると、片方だけ更新されて矛盾しやすくなります。Codexに文書を読ませるときは、共通規約を前提にしつつ、今回の仕様書が優先する範囲を明示すると判断の境界が伝わります。

小さな変更で文書の質を測る

仕様書の良し悪しは、文字数ではなく、Codexが質問せずに正しいテストを書けるか、そして人が結果を短時間で判定できるかで測ります。まず一つの関数や一つの画面で試し、ケース案、差分、実行結果、保留点がそろうかを見ます。抜けた項目があればひな形へ戻して直し、次の機能で同じ確認を行います。小さな比較を重ねると、文書のどの欄が不足しているかを感覚ではなく結果で把握できます。

まとめ：テストの意味を先にCodexへ渡す

Codexテスト仕様書の役割は、テストコードを増やすことではなく、何を正しいとするかを実装前に共有することです。対象範囲、期待結果、境界条件、異常時の扱い、準備データ、確認方法、完了条件の七つを順に書けば、Codexが実装から推測した期待値をそのまま採用する危険を抑えられます。2026年8月25日のOpenAI公式記事が示した、目的、過去の結果、計画、実行内容、判断を残す考え方も、テスト作業へ自然に移せます。

Codexへは仕様書と対象コードを読ませ、ケース案を確認してから小さくテストコードへ変換します。結果は通過だけでなく、失敗、未実行、判断待ちに分け、仕様書へ戻します。人は仕様の妥当性と影響を判断し、Codexは読み取り、候補作成、差分整理、確認結果の記録を受け持つ。文書とテストと結果を同じ意味でつなぐことが、AIコーディングエージェントを安心して使うための出発点です。

参照した公式情報: OpenAIの反復作業とCodexの記事、AGENTS.mdの案内、Codex CLIの機能案内、OpenAI Codexの公式リポジトリ。