投稿者: Pegasus_flying_freely

重複したコードの共通化のようなリファクタリングは、AIに任せやすい仕事です。挙動を変えない変更なので、既存のテストが全部通れば終わりにしたくなります。ただ、テストが全部通ったことは、テストが見ている挙動が変わらなかったことしか示しません。守りたい挙動をテストが本当に見張っているかは、別に確かめる必要があります。

請求書と見積で重複していた明細の金額計算を、Codexに1つの関数へまとめさせました。既存の8件のテストはすべて合格です。そのうえで、明細ごとに丸めていた計算を「合計してから丸める」に変えた版をわざと作って走らせると、落ちたのは請求書側の1件だけでした。見積側だけを同じように壊した版では、8件が1件も落ちません。見積の丸め順序を見張るテストはなかったのです。そしてCodexの完了報告は、「未テストの挙動」としてまさにその見積の複数明細を挙げていました。

この記事では、守りたい挙動を1つずつ壊してテストを走らせ、どのテストが落ちるかを確かめる手順を、この実例で示します。読み終えたら、AIにリファクタリングを任せる前に、どの挙動のテストを足しておくべきかを判断できます。

題材：請求書と見積の明細計算を1つにまとめる

元のコードでは、invoice()（請求書）と quote()（見積）が同じ明細の計算を2回書いていました。どちらも明細ごとに金額を小数第2位で丸め（四捨五入）、それを合計します。

from decimal import Decimal, ROUND_HALF_UP
def invoice(lines):
    total=Decimal("0")
    for price, quantity in lines:
        total+=(Decimal(price)*quantity).quantize(Decimal("0.01"),rounding=ROUND_HALF_UP)
    return format(total,".2f")
def quote(lines):
    total=Decimal("0")
    for price, quantity in lines:
        total+=(Decimal(price)*quantity).quantize(Decimal("0.01"),rounding=ROUND_HALF_UP)
    return {"amount":format(total,".2f"),"currency":"JPY"}

Codex CLIの新しいセッションに、重複した明細の計算を非公開の補助関数に抜き出すこと、シグネチャ・出力・例外・Decimalの丸めを保つこと、既存テストを変えないこと、まだテストしていない挙動を報告することを、英語の仕様書で1回依頼しました（2026年9月21日、Python 3.13）。Codexは _line_amount() を追加して両方から呼ぶ形にし、変更は billing.py だけ、既存の8テストはすべて合格と報告しました。

def _line_amount(price, quantity):
    return (Decimal(price)*quantity).quantize(Decimal("0.01"),rounding=ROUND_HALF_UP)

既存の8テストは次のとおりです。7件が invoice()、1件が quote() を見ています。

import unittest
from billing import invoice, quote
class Compat(unittest.TestCase):
    def test_empty(self): self.assertEqual(invoice([]),"0.00")
    def test_whole(self): self.assertEqual(invoice([("10",2)]),"20.00")
    def test_half(self): self.assertEqual(invoice([("0.005",1)]),"0.01")
    def test_per_line(self): self.assertEqual(invoice([("0.005",1),("0.005",1)]),"0.02")
    def test_negative(self): self.assertEqual(invoice([("-0.005",1)]),"-0.01")
    def test_quantity(self): self.assertEqual(invoice([("0.005",2)]),"0.01")
    def test_quote(self): self.assertEqual(quote([("2.555",1)]),{"amount":"2.56","currency":"JPY"})
    def test_generator(self): self.assertEqual(invoice((x for x in [("1",1)])),"1.00")

手順1：守りたい挙動を1つずつ書き出す

最初に、このリファクタリングで変わってはいけない挙動を、関数ごとに書き出します。今回の題材なら、たとえば次の3つです。

• 請求書：明細ごとに丸めてから合計する

• 見積：明細ごとに丸めてから合計する

• 見積：戻り値の形（amount と currency の辞書）

共通化で崩れやすいのは、関数どうしで同じに見えていた計算の細部です。とくに金額の丸め、権限の判定、日付の境界のように、間違えるとお客様や利用者に直接影響する箇所を優先して書き出します。全部を書き出す必要はありません。

手順2：その挙動だけを壊した版を作る

書き出した挙動ごとに、その挙動だけが変わる版を手で作ります。丸めの順序なら、「明細ごとに丸める」を「合計してから丸める」に変えます。2つの計算が本当に違う値を出すかは、先に小さなコードで確かめておきます。次を rounding_check.py として保存し、python3 rounding_check.py で実行します。

from decimal import Decimal, ROUND_HALF_UP

CENT = Decimal("0.01")

def per_line(lines):
    return sum(
        ((Decimal(p) * q).quantize(CENT, rounding=ROUND_HALF_UP)
         for p, q in lines),
        Decimal("0"),
    )

def after_total(lines):
    total = sum((Decimal(p) * q for p, q in lines), Decimal("0"))
    return total.quantize(CENT, rounding=ROUND_HALF_UP)

lines = [("0.005", 1), ("0.005", 1)]
print(f"明細ごと: {per_line(lines):.2f}")
print(f"合計後: {after_total(lines):.2f}")
assert per_line(lines) == Decimal("0.02")
assert after_total(lines) == Decimal("0.01")

明細ごと: 0.02
合計後: 0.01

0.005円の明細が2つあると、明細ごとに丸めれば0.02、合計してから丸めれば0.01になります。式は似ていても、出力が変わる変更です。どちらの丸め方が正しいかは業務の規則で決まることで、ここで見たいのは「今の挙動から変わったら、テストが気づくか」です。

壊した版は、billing.py を一時的なコピーで書き換えて作ります。元のファイルやAIの成果物は書き換えません。

手順3：既存テストを走らせ、どのテストが落ちるかを見る

壊した版ごとに、既存の8テストを走らせました。

3行目の版に2明細（0.005円×2）の見積を渡すと 0.01、Codexが共通化した版では 0.02 が返ります。値は変わっているのに、8件はすべて合格しました。見積のテスト test_quote は明細が1つだけで、1明細では丸めの順序を変えても金額が変わらないからです。

テストの件数が8件あっても、請求書の丸め順序を見張っていたのは1件、見積の丸め順序を見張っていたのは0件でした。もし共通化の途中で見積だけ計算の順序が変わっていたら、8件の合格はそれを知らせなかったことになります。

手順4：AIの「未テストの挙動」を、壊す対象の候補にする

Codexの完了報告には、次の一覧がありました（報告の原文の一部）。

未テストの挙動:

• 不正な価格・数量・明細構造に対する例外互換性

• quote() の空入力、複数明細、負数、ジェネレーター入力

• 非常に大きい値や特殊な Decimal コンテキスト

2行目の「quote() の…複数明細」は、手順3で見つけた穴そのものです。今回、依頼でまだテストしていない挙動の報告を頼んだところ、AIは見積側の複数明細を挙げていました。この一覧を、手順1で書き出す挙動の候補として使えます。

使い方は次のとおりです。

1. 報告の「未テストの挙動」を、手順1の一覧に加える。

2. 加えた挙動ごとに手順2・3で壊した版を作り、既存テストが落ちるかを見る。

3. どのテストも落ちなかった挙動に、テストを1件足す。

今回なら、見積の複数明細のテストを足します。

import unittest
from billing import quote
class QuoteRounding(unittest.TestCase):
    def test_quote_per_line(self):
        self.assertEqual(quote([("0.005",1),("0.005",1)]),{"amount":"0.02","currency":"JPY"})

このテストは、Codexが共通化した版では合格し、見積だけを壊した版では失敗しました。足したテストが本当に穴をふさいだかも、壊した版で落ちることまで見て確かめます。

報告に挙がった挙動のすべてが、守りたい挙動とは限りません。「非常に大きい値」のように今の業務で起きない入力は、一覧に残して後回しにしてかまいません。

任せる前に、テストを補うかを決める

手順3の表で「どのテストも落ちなかった挙動」が残ったら、次のどちらかを選びます。

• テストを足してから任せる：金額・権限・日付のように、変わると困る挙動。今回の見積の丸め順序はこちらです。

• そのまま任せて、差分を読む：変わっても影響が小さい挙動。リファクタリングの差分で、その箇所に手が入っていないかを目で確かめます。

変更が大きくなるときも、同じ確かめ方を「抜き出す」「呼び出し元を置き換える」「古い経路を消す」のような段階ごとに挟むと、どの段階で挙動が変わったかを追えます。どの段階でも、合格の件数ではなく、守りたい挙動ごとに見張っているテストがあるかで判断します。

出典と確認日

• OpenAI: Codex best practices。変更後の検証と差分のレビューを含む進め方の案内。再確認日：2026-10-09。

AIのあるセッションで設計案を作り、実装は新しいセッションや別のAIに任せたい。そのとき受け手が読むのは、承認済みの仕様と、設計者が足した提案が混ざった1枚の設計案です。原仕様にない一文が承認済みの要件と同じ顔で並んでいると、受け手はそれを要件として実装します。

Codexに在庫予約機能の設計案を作らせ、その設計案を原仕様と一緒に別のセッションへ渡して実装させたところ、まさにそれが起きました。設計案は8つの要件すべてに触れ、boolが数量として通ってしまうリスクも正しく指摘していましたが、その対策の一文で、原仕様の「正のint」を「組み込みintだけ」に狭めていました。受け手には「設計案と原仕様が食い違ったら原仕様を優先」と添えましたが、実装はこの制約をそのまま取り込み、テストにはすべて合格しました。今回、原仕様が何も書いていない点への制約の追加は、この優先の一文では防げませんでした。

この記事では、設計案を原仕様の要件ごとに照らして原仕様にない制約を見分ける手順と、原仕様・設計提案・未決事項を欄で分けて渡す引き継ぎ票、受け手に要件とテストの対応を返させる受領確認を、この実例で示します。読み終えたら、自分の設計案から、実装の前に渡せる引き継ぎ票を作れます。

設計案の一文が、実装に入るまで

題材は、Pythonの在庫予約関数 reserve(stock, requests) の追加です。原仕様（SPEC.md）は8つの要件で、数量については次のように書いています（R3）。

R3: quantity must be a positive int; reject bool, zero, negative, float with ValueError.

Codex CLIの新しいセッションに、原仕様・既存コード・15件のテストを渡し、ファイルを変えずに設計案だけを作らせました（2026年9月21日、1回）。設計案の「要件」と「変更案」には、次の2行がありました。

quantity は bool を除く正の組み込み int のみ許可する。

type(quantity) is int and quantity > 0 を検証する。

同じ設計案の「具体的な失敗リスク」には、「isinstance(quantity, int) だけでは True を受理してしまう。」とあります。Pythonの bool は int のサブクラスなので、この指摘は正しく、R3の「boolを拒否」に沿っています。ただ、対策として書かれた type(quantity) is int は、bool以外のintのサブクラス（intを継承したクラスの値）まで拒否します。R3はそこまで書いていません。

この設計案を PLAN.md として原仕様と一緒に置き、別の新しいセッションに実装させました（同じ日、1回）。依頼文には次の一文を入れています。

Read PLAN.md as an advisory design. SPEC.md is authoritative if they differ.

受け取った実装の数量の判定は、設計案のとおりでした。

if type(quantity) is not int or quantity <= 0:

この実装は、事前に渡した15件のテストと、実装後に足した5件のテストにすべて合格しました。完了報告は「数量の厳密な検証（bool、0、負数、浮動小数を拒否）」と書くだけで、原仕様より狭めたことには触れていません。

原仕様だけを渡して実装させた別の実装と、intのサブクラスの値を渡して比べました。class Quantity(int) で作った Quantity(1) などを、在庫5の商品への1件の予約として、保存しておいた2つの実装に渡した結果です（Python 3.13）。

どちらの実装も同じ20件のテストにすべて合格しているので、テストの結果だけを見ると差はありません。原仕様だけで実装した版の点検の手順は、Codexの合格報告を受け入れる前の点検の記事で扱っています。

原仕様はintのサブクラスの扱いを明記していないため、設計案の「組み込みintだけ」は、矛盾ではなく仕様の具体化として取り込まれたと解釈できます。今回確かめたのは、優先順位の一文だけでは追加制約の採用を防げなかったことです。そこで、原仕様にある要件と設計者の提案を欄で分け、追加制約を承認するかどうかも実装前に決める方法を提案します。

手順1：設計案を、原仕様の要件ごとに照らす

渡す前に、設計案の要件や方針の一文ずつを、原仕様の要件番号と照らします。照らした結果には、次の3つの印のどれかを付けます。

今回の設計案に印を付けると、たとえば次のようになります。

設計案が8つの要件すべてに触れていても、この照合は省けません。網羅しているかと、頼んでいない条件を足していないかは、別の問いだからです。今回の「狭い」の一文は、正しいリスク指摘のすぐ隣にありました。指摘が的確なほど、その対策の一文も要件のように読めてしまいます。

印を付けるときに迷ったら、2つの書き方で結果が割れる値を実際に渡してみます。次のコードを int_boundary.py として保存し、python3 int_boundary.py で実行すると、intのサブクラスも受け入れる判定（正のintで、boolを除く）と設計案の判定（組み込みintだけ）の違いが出ます。

class Quantity(int):
    pass

for value in [True, 1, Quantity(1)]:
    positive_int = isinstance(value, int) and not isinstance(value, bool) and value > 0
    builtin_only = type(value) is int and value > 0
    print(type(value).__name__, positive_int, builtin_only)

bool False False
int True True
Quantity True False

3行目の Quantity だけ結果が割れます。割れた値があれば、その記述は「同じ」ではなく「狭い・広い」です。

手順2：引き継ぎ票に、原仕様・設計提案・未決事項を分けて書く

照らした結果を、次の引き継ぎ票に書き写します。受け手が読む資料はこの票と、原仕様・テスト・対象のコードです。設計案は添えてもかまいませんが、判断の根拠は票の欄で示します。

目的：誰のどの問題を解決するか
対象：リポジトリ、基準コミット、作業ブランチ
原仕様：承認済みの要件を番号つきで（R1〜）。設計案で言い換えた文ではなく原文を書く
設計提案：原仕様より狭い・広い記述と、原仕様にない方針。それぞれ「承認済み」か「未承認」かを書く
未決事項：決める人、決まるまで実装で触れない部分
調査済み：読んだファイル、関数、確かめた挙動
変更範囲：変更してよい場所、維持する公開API
検査：実行コマンド、合格の条件、既に分かっている失敗
禁止事項：依存の追加、データ移行、外部送信など
復旧：変更を戻せる単位と、戻せない副作用
受領確認：要件ごとに確かめるテストと、採用する設計提案を返してから実装する

今回の例なら、設計提案と未決事項の欄は次のようになります。

設計提案：
- 数量は組み込みintだけを受け入れる（R3より狭い。未承認）
- エラーの文言と優先順位はテストで固定しない（原仕様にない。承認済み）
未決事項：
- intのサブクラスの数量を受け入れるか（決める人：［呼び出し側の担当］）
  決まるまで、数量判定の実装と、その判定を含む機能の取り込みを保留する。独立して進められる部分だけ実装する

未決事項に「決まるまでの扱い」を書いておくのは、受け手が空白を自分で埋めないためです。今回の実装は、空白を設計案の一文で埋めていました。

手順3：受け手に、要件とテストの対応を返させる

実装を始める前に、受け手に次の2つを返してもらいます。

実装の前に、次の2つを返してください。
1. 原仕様の要件番号ごとに、それを確かめるテスト名（なければ「なし」）
2. 引き継ぎ票の設計提案のうち、実装に取り入れるものと、その理由
返した内容に不明点や矛盾があれば、実装を始めずに質問してください。

1で「なし」が返ってきた要件は、テストが守っていない要件です。今回なら、R3に対して返るのは test_05〜test_08（bool・0・負数・float）で、intのサブクラスを確かめるテストはありません。そこが、引き継ぎで受け手の判断に任されている場所です。2で「未承認」の提案を取り入れると返ってきたら、実装の前に止めて決めます。

返答が正しくても、実装がそのとおりになるとは限りません。実装を受け取ったら、差分と、未決事項に当たる値を渡した結果で確かめます。確かめ方は合格報告を受け入れる前の点検の記事の手順4と同じです。

自分の案件で書き換える箇所と、渡す前の確認

引き継ぎ票の各欄は、自分の案件で次のように書き換えます。

• 原仕様：設計案の要約ではなく、承認済みの要件の原文を番号つきで貼る。

• 設計提案：手順1で「狭い・広い」「原仕様にない」の印を付けた記述をすべて移し、承認の状態を書く。

• 未決事項：決める人と、決まるまでの実装の扱いを書く。

• 検査：実行するコマンドと、合格の条件（テスト件数、変更してよいファイル）を書く。

渡す前に、次の3つを確かめます。

1. 設計案の要件・方針の文に、すべて印が付いている。

2. 「狭い・広い」「原仕様にない」の記述が、原仕様欄に混ざっていない。

3. 未決事項のそれぞれに、決める人か、決まるまでの扱いが書いてある。

3つがそろえば、受け手は設計案を「承認済みの要件」と「提案」に分けて読めます。今回の type(quantity) is int の一文も、設計提案の欄に「未承認」と書き、実装前に質問するよう受領確認で求めます。この引き継ぎ票で実装し直す検証は行っていないため、採用後も差分と境界値で確かめます。

出典と確認日

• OpenAI: Codex best practices。難しいタスクで計画を立ててから進める方法の案内。再確認日：2026-10-09。

Codexに関数の追加を頼むと、作業の最後に「テストはすべて成功しました」と返ってきます。採用するかどうかを決めるのは自分ですが、その一行が示しているのは「渡したテストに通った」ことだけです。テストに書いていない入力でどう振る舞うか、頼んでいないファイルを変えていないかは、報告からは分かりません。

在庫予約の関数をCodexに1回実装させ、事前に渡した15件のテスト、実装後に足した5件のテスト、差分の3つで点検すると、すべて合格でした。それでも、仕様が何も言っていない入力が残っていました。数量として「intを継承したクラスの値」（intのサブクラス）を渡すと、この実装は受け入れます。同じ仕様・同じテストで別のセッションが書いた実装は、同じ値を拒否し、こちらも20件すべてに合格していました。合格の件数からは、この違いは見えません。

この記事では、合格報告を4つに分けて読む手順を、この実装で順に示します。読み終えたら、Codexの合格報告を受けたときに、何を足して確かめ、どこを仕様として決めてから採用するかを判断できます。題材のコードとテストは全文を載せるので、同じ点検を手元で再現できます。

合格報告を4つに分けて読む

「テストはすべて成功」を、次の4つの問いに分けます。上の2つはテストで、3つ目は差分で、4つ目はコードを読んで確かめます。

上の3行が合格なら、採用してよい実装の候補です。4行目は合否ではなく、採用の前に「その扱いでよいか」を決める項目です。今回の4行目は、実装の書き方しだいで逆の結果になりました。

題材：在庫予約の関数と8つの条件

既存の inventory.py には、在庫を参照する available() だけがあります。ここに、在庫の辞書と予約の一覧を受け取り、予約後の新しい在庫の辞書を返す reserve(stock, requests) を追加させました。条件は次の8つで、英語の仕様書（SPEC.md）として渡しています。

1. 入力を書き換えず新しい辞書を返し、既存の available() を維持する。

2. 在庫と重複判定をテナント（利用企業）ごとに分け、他テナントの在庫を使わない。

3. 数量は正のintとし、bool・0・負数・floatは ValueError で拒否する。

4. 全件を検証してから反映し、在庫がない・足りないときは ValueError にする。

5. 同じバッチ内で、テナントとIDが同じで商品・数量も同じ予約は、一度だけ消費する。

6. IDが同じで内容が違えば拒否し、別の呼び出しとは重複の状態を共有しない。

7. IDが違う予約は合計して消費し、空の一覧でも新しい同値の辞書を返す。

8. 外部依存・ネットワーク・永続化・並行実行・新しいCLI・シグネチャの変更は対象外。

条件3は、Pythonの bool が int のサブクラスであることを踏まえて、True を数量として通さないための一文です。一方で、bool以外のintのサブクラスをどう扱うかは、8つの条件のどこにも書いていません。この空白が、手順4で問題になります。

手順1：事前テストを固定してから実装を頼む

空のGitリポジトリに、既存の関数だけを置いた inventory.py を作ります。

def available(stock, tenant, sku):
    return stock.get((tenant, sku), 0)

上の8条件を SPEC.md に書き、次のテストを test_contract.py として保存して、3つを同じコミットに入れます。在庫のキーは (tenant, sku)、予約は tenant・sku・quantity・request_id を持つ辞書です。

import unittest
from inventory import available, reserve
def req(t="a", sku="pen", q=1, id="x"):
    return dict(tenant=t, sku=sku, quantity=q, request_id=id)
class Contracts(unittest.TestCase):
    def setUp(self): self.s={("a","pen"):5,("b","pen"):8,("a","book"):3}
    def test_01_legacy(self): self.assertEqual(available(self.s,"a","pen"),5)
    def test_02_happy(self): self.assertEqual(reserve(self.s,[req(q=2)])[("a","pen")],3)
    def test_03_no_mutation(self):
        r=[req()]; before=r[0].copy(); out=reserve(self.s,r)
        self.assertEqual(self.s[("a","pen")],5); self.assertEqual(r,[before]); self.assertIsNot(out,self.s)
    def test_04_tenant(self):
        out=reserve(self.s,[req(),req(t="b")]); self.assertEqual((out[("a","pen")],out[("b","pen")]),(4,7))
    def test_05_bool(self):
        with self.assertRaises(ValueError): reserve(self.s,[req(q=True)])
    def test_06_zero(self):
        with self.assertRaises(ValueError): reserve(self.s,[req(q=0)])
    def test_07_negative(self):
        with self.assertRaises(ValueError): reserve(self.s,[req(q=-1)])
    def test_08_float(self):
        with self.assertRaises(ValueError): reserve(self.s,[req(q=1.0)])
    def test_09_atomic(self):
        with self.assertRaises(ValueError): reserve(self.s,[req(),req(sku="missing",id="y")])
        self.assertEqual(self.s[("a","pen")],5)
    def test_10_shortage(self):
        with self.assertRaises(ValueError): reserve(self.s,[req(q=6)])
    def test_11_same_duplicate(self): self.assertEqual(reserve(self.s,[req(),req()])[("a","pen")],4)
    def test_12_conflict(self):
        with self.assertRaises(ValueError): reserve(self.s,[req(),req(q=2)])
        with self.assertRaises(ValueError): reserve(self.s,[req(),req(sku="book")])
    def test_13_cumulative(self):
        with self.assertRaises(ValueError): reserve(self.s,[req(q=3),req(q=3,id="y")])
    def test_14_empty(self):
        out=reserve(self.s,[]); self.assertEqual(out,self.s); self.assertIsNot(out,self.s)
    def test_15_no_global_cache(self): self.assertEqual(reserve(self.s,[req()]),reserve(self.s,[req()]))

このコミットから作業用のコピーを作り、Codexに「SPEC.mdを実装し、既存テストは変えず、構文検査とテストを実行して報告する」と頼みます。実装前は reserve のimportで失敗しますが、それで正常です。

Codex CLIの新しいセッションに、この依頼を1回送りました（2026年9月21日、Python 3.13）。Codexは inventory.py に reserve を追加し、「15件すべて成功」「変更ファイルは inventory.py のみ」と報告しました。報告を受け取ったあとに修正を頼み直した回数は0回です（Codexの内部で何回書き直したかとは別の数です）。

点検に使う完成コード

今回Codexが返した inventory.py の全文です。同じ結果を確かめる場合は、最初の available() だけのファイルを次の内容に置き換え、python3 -m unittest -v test_contract で事前テスト15件を実行します。自分でCodexに実装を頼む場合は、その返却コードを点検対象にします。

def available(stock, tenant, sku):
    return stock.get((tenant, sku), 0)


def reserve(stock, requests):
    """Return a stock snapshot with an atomic batch of reservations applied."""
    reservations = {}
    required = {}

    for request in requests:
        tenant = request["tenant"]
        sku = request["sku"]
        quantity = request["quantity"]
        request_id = request["request_id"]

        if isinstance(quantity, bool) or not isinstance(quantity, int) or quantity <= 0:
            raise ValueError("quantity must be a positive integer")

        reservation_key = (tenant, request_id)
        reservation = (sku, quantity)
        if reservation_key in reservations:
            if reservations[reservation_key] != reservation:
                raise ValueError("conflicting duplicate request")
            continue

        reservations[reservation_key] = reservation
        stock_key = (tenant, sku)
        if stock_key not in stock:
            raise ValueError("stock item does not exist")

        total = required.get(stock_key, 0) + quantity
        if total > stock[stock_key]:
            raise ValueError("insufficient stock")
        required[stock_key] = total

    result = stock.copy()
    for stock_key, quantity in required.items():
        result[stock_key] -= quantity
    return result

手順2：実装後に境界テストを足す

事前の15件は、Codexが実装中に読める場所に置きました。読めるテストに合わせた実装でも通るので、実装を受け取ってから、別の観点のテストを足します。今回足したのは次の5件です。test_after.py として同じフォルダに保存し、python3 -m unittest -v test_after で実行します。

import unittest

from inventory import reserve


def req(t="a", sku="pen", q=1, id="x"):
    return dict(tenant=t, sku=sku, quantity=q, request_id=id)


class AfterImplementation(unittest.TestCase):
    def test_same_id_in_other_tenant(self):
        stock = {("a", "pen"): 2, ("b", "pen"): 2}
        out = reserve(stock, [req(), req(t="b")])
        self.assertEqual(out, {("a", "pen"): 1, ("b", "pen"): 1})

    def test_resend_after_other_request(self):
        out = reserve({("a", "pen"): 5}, [req(), req(id="y"), req()])
        self.assertEqual(out, {("a", "pen"): 3})

    def test_cumulative_success(self):
        out = reserve({("a", "pen"): 5}, [req(q=2), req(q=3, id="y")])
        self.assertEqual(out, {("a", "pen"): 0})

    def test_other_stock_is_kept(self):
        out = reserve({("a", "pen"): 2, ("b", "book"): 9}, [req()])
        self.assertEqual(out, {("a", "pen"): 1, ("b", "book"): 9})

    def test_requests_unchanged_on_failure(self):
        requests = [req(), req(q=99, id="y")]
        saved = [dict(r) for r in requests]
        with self.assertRaises(ValueError):
            reserve({("a", "pen"): 2}, requests)
        self.assertEqual(requests, saved)


if __name__ == "__main__":
    unittest.main(verbosity=2)

別テナントの同じID、間に別の予約を挟んだ再送、在庫ちょうどまでの合計消費、予約と関係のない在庫、失敗したときの予約一覧。どれも事前の15件とは違う形の入力で、Codexの実装は5件すべてに合格しました。足すテストは、仕様の条件ごとに「事前テストとは違う並び・組み合わせ」を1つずつ考えると作りやすくなります。

手順3：差分で変更範囲を確かめる

テストの結果とは別に、何が変わったかを差分で確かめます。

python3 -m compileall -q .
python3 -m unittest discover -v
git diff --check
git diff --stat
git status --short

git diff --stat は変更をファイルごとに要約し、git status --short はまだGitに登録していない新しいファイルも表示します。今回の変更は inventory.py だけで、test_contract.py と SPEC.md はそのまま、依存の追加もありませんでした。テストのファイルが変わっていたら、合格の意味が変わるので、テストを弱めていないかを先に確かめます。

手順4：テストが決めていない契約をコードで探す

ここまでの3つは、渡した条件と頼んだ範囲の確認です。最後に、仕様が何も書いていない入力を探します。探し方は、入力を判定している行を読み、仕様の言葉と食い違いうる書き方を見つけて、その値を実際に渡すことです。

今回の実装で数量を判定していたのは、次の1行でした。

if isinstance(quantity, bool) or not isinstance(quantity, int) or quantity <= 0:

isinstance(quantity, int) は、intのサブクラスの値も「int」と判定します。boolだけを先に除いているので、bool以外のサブクラスは通ります。

同じ SPEC.md と同じ15件のテストで、設計案を添えて別のセッションのCodexに実装させた版もあります（その引き継ぎの記録は設計案を別のセッションに渡す記事で扱っています）。そちらの判定は次の1行でした。

if type(quantity) is not int or quantity <= 0:

type(quantity) is not int は、組み込みのint以外をすべて拒否します。2つの実装に、class Quantity(int) で作った Quantity(1) と、比べるための値を、在庫5の商品への1件の予約として渡しました（Python 3.13）。

2つの実装は、事前15件・事後5件のテストにどちらもすべて合格しています。テストに Quantity のような値がないので、合格の件数は同じでも、この1行の違いは結果に出ません。Codexの報告も、どちらも「数量の厳密な検証」と書くだけでした。

どちらが正しいかは、仕様からは決まりません。呼び出し側が数量をintのサブクラスで渡す設計なら受け入れる実装が必要で、組み込みのintに限りたい理由があれば拒否する実装が必要です。決まっていないまま採用すると、その扱いは仕様ではなく、たまたま書かれた1行で決まります。

自分の実装で同じ確認をするときは、次のように仕様の空白に当たる値を渡し、結果を表に残します。

from inventory import reserve


class Quantity(int):
    pass


stock = {("a", "pen"): 5}
for value in [Quantity(1), 1, True, 1.0]:
    request = {"tenant": "a", "sku": "pen", "quantity": value, "request_id": "x"}
    try:
        print(type(value).__name__, "受け入れ", reserve(stock, [request]))
    except ValueError as exc:
        print(type(value).__name__, "拒否", exc)

今回の題材で空白になっていたのは数量の型でしたが、文字列の前後の空白、Noneや空文字、非常に大きな数など、仕様に書いていない入力はほかにも考えられます。全部を試すより、判定している行を読み、そこで使っている関数（isinstance・type・strip など）が仕様の言葉より広いか狭いかを見るほうが早く見つかります。

採用するか、何を決めてから採用するか

4つの点検の結果から、次のように判断します。

• 1〜3のどれかが不合格：採用しない。落ちたテストか、想定外の差分を添えて直しを頼む。

• 1〜3が合格で、4で扱いが決まった：採用する。決めた扱いを SPEC.md に一文足し、その値を渡すテストを test_contract.py に加えてから取り込む。

• 1〜3が合格で、4の扱いを決める人がいない：取り込みを待ち、呼び出し側の担当に扱いを確かめる。

今回なら、「数量はintのサブクラスも受け入れる」か「組み込みのintだけを受け入れる」かを決め、Quantity(1) を渡すテストを1件足せば、次に別の実装が来ても同じ扱いになります。テストに足した時点で、4つ目の問いは1つ目の問いに移ります。

点検を続けるなら、合格の件数に加えて、受け取ってから修正を頼み直した回数と、4つの点検にかかった時間を記録しておくと、Codexに任せる範囲を決める材料になります。

出典と確認日

• OpenAI: Codex best practices。計画、編集後の検証、差分のレビューを含む進め方の案内。再確認日：2026-10-09。