AIが変えたAPIは互換性を保てるか。古い呼び出しを試す

AIがAPI実装とテストを同時に変更すると、新仕様どうしは整合していても、変更前の利用側との境界がテストから消えることがあります。新しいクライアントと新しいサーバーを組み合わせた成功だけでは、互換性を確認できません。差分に加えて、旧利用側が送る入力と受け取る出力をレビュー対象に含めます。

2026年10月3日に確認した[Google AIP-180](https://google.aip.dev/180)は、互換性を三つの側面に分けています。以前のコードが新しいクライアントライブラリでもコンパイル・実行できるソース互換性、旧コードと新サーバーの入出力や直列化の期待が合うワイヤ互換性、旧コードが合理的に期待する挙動を受け続けるセマンティック互換性です。同資料はProtocol BuffersとJSONを前提とする指針であり、網羅的な判定一覧ではありません。

スキーマの差分だけを見て「破壊的変更なし」と結論づけるのは早計です。型が読めても、追加項目がないと失敗するなら旧リクエストの挙動は変わっています。レスポンスを受信できても、未知の列挙値で旧コードの分岐が止まれば、利用側の処理は保てません。旧クライアントがコンパイル・実行できるか、旧リクエストと新レスポンスを期待どおり直列化・解釈できるか、同じ入力への挙動が維持されるかを確かめます。三つの側面は合否を自動で出す規則ではありません。契約テストを置く場所を特定するために使います。

レビューの基準には、変更前に利用側が成立させていた契約を使います。保存済みの旧リクエスト、期待する成功または明示的な失敗、確認したい既定動作を一つのケースとして残します。AIが更新した仕様書は変更内容を読む資料であり、旧契約の代わりにはなりません。新実装へ同じケースを再生し、結果の差をPull Requestで読めるようにします。

台帳には「変更種別」「向き」「旧利用側の入力または処理」「新実装に期待する結果」「不一致時の扱い」を置きます。項目追加なら、追加項目を送らない旧リクエストを入力にする。必須化なら、以前は省略可能だった項目を欠いた入力を使う。列挙値なら、リクエスト側とレスポンス側を別行にする。この分類は出典の一般原則を基に記事が提案する実務上の方法で、原典所定の分類や義務ではありません。

テストを現行実装から自動生成しただけでは、変更された挙動まで正解として固定するおそれがあります。項目追加では追加項目を含まない旧リクエスト、必須化では以前は省略できた項目を欠く入力を保存します。列挙値は利用側が送る値と受け取る値を分け、観測結果と承認可否を別々に記録します。期待結果は旧契約を根拠に人が読み、意図的な差分であっても互換変更として承認できるかを判断します。APIサービスの提供終了やメジャー版移行の経営判断は、この台帳の対象外です。対象は、同じ契約を維持する前提での実装差分に絞ります。

項目追加のケースでは、追加前に保存したリクエストを新実装へ送ります。追加項目を含まなくても従来の成功条件を満たし、その項目の既定動作が追加前と一致するかを確認します。レスポンスへの項目追加は別ケースにし、未知項目を含む応答を旧利用側が受けても処理を継続できるかを確かめます。これはAIP-180の一般原則を基に記事が提案する方法であり、原典が定める一律の試験手順や義務ではありません。

根拠は、2026年10月3日に確認した[AIP-180のAdding components](https://google.aip.dev/180)です。同資料は、同一メジャー版への新しいフィールドなどの追加を一般に認めています。その条件として、旧API表面だけを知るコードを従前どおり扱うことを挙げています。さらに、新しい必須フィールドを既存のリクエストメッセージやリソースへ追加せず、クライアントが設定する新フィールドの既定動作を追加前と一致させるとしています。判定点は追加という構文より、省略時の挙動にあります。

必須化はさらに明確に分けます。旧契約で省略可能だった項目を欠くリクエストを固定し、新実装でも従来どおり受理されるかを確認します。2026年10月3日に確認した[Google AIP-203](https://google.aip.dev/203)は、既存のOPTIONALフィールドへのREQUIRED追加と、既存リクエストメッセージへのREQUIREDの新フィールド追加を、後方互換性のない変更例に挙げています。

固定ケースが新たに欠落エラーへ変わった差分は、同一メジャー版の互換変更として承認しない判断材料にします。この停止条件も、AIP-180とAIP-203の一般原則を基に記事が提案する実務上の方法で、原典所定の承認義務ではありません。合格には、追加項目なしの旧リクエストが以前と同じ成功条件を満たし、省略時の既定動作が一致することを求めます。レスポンス追加では、未知項目を受けた旧利用側が処理を継続できることも確認します。新機能のために項目が必要なら、旧呼び出しの受理を維持する設計へ直すか、互換性を保たない別の変更として扱うかを、実装前提から選び直せます。

列挙値の追加は、入出力の方向によって確認先が変わります。2026年10月3日に確認した[AIP-180](https://google.aip.dev/180)は、リクエストだけで使うenumには値を自由に追加できるとしています。レスポンスまたはリソースで使うenumへの新値追加は、利用者コードが適切に扱えない可能性があるため、新値追加予定を文書化し注意して行うという扱いです。変更方向からテストケースを決めます。

リクエスト側には、旧利用側が送っていた既知の値を残します。新しい値が増えても、旧値が新実装で引き続き受理され、旧値に対する挙動が維持されるかを見るためです。値の追加に伴って旧値を拒否したり、別の意味へ読み替えたりする変更を、単なる列挙値追加として通しません。

レスポンス側では、新実装が返し得る未知の値を旧利用側へ与えます。安全なフォールバック、または明示的なエラー処理へ進めるかを確認し、未処理ならリリース判断上の要対応差分として台帳へ記録します。入力ケースでは既知の値が引き続き受理されること、出力ケースでは未知値への処理経路が説明できることが合格条件です。この入出力別の試験と台帳の扱いは、AIP-180の一般原則を基に記事が提案する実務上の方法で、原典所定の試験分類や義務ではありません。必ず成功する設計を求めているわけではありません。説明できない停止や誤った分岐の可能性を、公開前の判断材料として露出させます。

契約テストが任意実行のままでは、AIが作る差分のたびに確認の有無が変わります。項目追加・必須化・列挙値変更の旧呼び出しケースを、一つの契約チェックとしてCIで実行します。テスト名から、どの旧契約が崩れたかを台帳の行へたどれる状態にしておくと、失敗を実装修正で解消するのか、互換性を保たない変更として再設計するのかをレビューできます。

2026年10月3日に確認した[GitHub DocsのStatus checks](https://docs.github.com/en/pull-requests/reference/status-checks)によると、ステータスチェックはCIのビルドやテストなどがリポジトリの条件を満たすかを示し、保護ブランチで必須にしたチェックはPull Requestのマージ前に通過する必要があります。この仕組みに契約チェックを置けば、確認結果をマージ条件にできます。これは同資料と互換性資料の一般原則を基に記事が提案する運用であり、各原典がAPI契約テストの設置を義務づけているわけではありません。

チェック通過が示す範囲は、固定した旧呼び出しに対する結果までです。固定していない利用方法を網羅した証明にはならず、AIP-180自体も指針が網羅的ではないとしています。旧呼び出しのケースを単一のCIチェックへまとめ、対象ブランチの必須ステータスチェックにしたうえで、失敗時には期待値を安易に更新せず、旧契約と差分を人が照合します。通過後も、テスト対象外の変更、期待値の更新理由、互換性を意図的に外す判断が混ざっていないかを確認します。レビュー、テスト、CIを人の判断へつなぐ全体設計は、AI駆動開発の開発フロー｜レビュー・テスト・CIで人の判断を残すとも合わせて整理できます。

自社で始める条件は、利用側として残すべき旧契約を選べること、変更前の入力と期待結果を固定できること、失敗をマージ前に止められることです。まず対象APIを一つに絞り、追加項目を含まない入力、旧契約で省略できた項目を欠く入力、既知または未知の列挙値という三種のケースを台帳へ置きます。実際の利用経路から期待を説明できないケースは、先に契約そのものを確認します。

項目追加では省略時の既定動作、必須化では旧入力の受理、列挙値では入出力の方向が合否を分けます。この具体性があれば、AIが仕様、実装、現行テストを同時に書き換えても、変更前の利用側を基準として残せます。旧入力を保存できない、期待結果の責任者を決められない、失敗してもマージを止められないという状態なら、先にその三条件を整えます。契約テストの追加はその後です。

AIエージェントへ実装を任せる範囲には、API互換性とは別に権限とデータ管理の境界もあります。Claude Codeのセキュリティ｜法人導入前に決める権限とデータ管理で実行環境の守りを確認しつつ、API差分については古い呼び出しを再生する責任を利用側に残します。三種の固定ケースとCIの停止条件がそろえば、「追加かどうか」だけでは決まらない互換性を、変更方向と旧利用側の期待に基づいて承認できます。