このユニットの結論
連携の窓口（API）は、黙って変えると相手が壊れ、永遠に変えないこともできません。
「相手に影響のない変更」と「影響のある変更」を具体的な種類で分け、影響のある変更は新しい版を作って古い版と並行して提供し、期限を決めて古い版を止める。この手続きを会社の間でそろえることが、版の管理です。
1. 何の話か
このユニットは、システム同士の約束の形（API）を、安全に変えていく方法の話です。
07-02 APIは万能ではない で、API が「約束」であることを学びました。約束は、業務が変われば変える必要があります。しかし約束の片側だけが変わると、もう片側が壊れます。約束を変えるときの手続きを決めるのが、版の管理です。
2. なぜ必要か
版の管理がないと、
- 送り手が「小さな変更」のつもりで項目の名前を変え、受け手の処理が止まる
- 古い形を残したまま新しい形を足し続け、どの受け手がどの形を使っているか誰も分からなくなる
- 変更の知らせが担当者の記憶に頼っており、知らされなかった受け手が壊れる
ということが起きます。複数の会社が約36本の連携を担当する状況では、手続きが会社ごとに違うだけで事故になります。
3. このユニットで分かること
- 影響のない変更と、影響のある変更の分け方
- 影響のある変更の手続き（新しい版・並行提供・通知・停止）
- 受け手の一覧と、自動で確かめる仕組み
4. 変更を分ける
| 変更の種類 | 相手への影響 | 扱い（一般的な例） |
|---|---|---|
| 応答に項目を足す | 受け手が知らない項目を無視するなら、なし | 通知のみ。版は変えない |
| 要求に任意の項目を足す | 送らなくても今までどおり動くので、なし | 通知のみ |
| 項目の名前や意味を変える | 受け手の処理が壊れる | 新しい版を作る |
| 必須の項目を足す | 送っていない受け手が失敗する | 新しい版を作る |
| 項目を消す | 使っている受け手が壊れる | 新しい版を作る |
「大きな変更は新しい版」のような抽象的な決まりでは判断できません。変更の種類ごとに扱いを決め、一覧にしておきます。判断に迷う種類（返す誤りの種類が増える など）は、受け手の作り方の決まりと合わせて、どちらに扱うかを先に決めます。
5. 影響のある変更の手続き
- 新しい版を作る：古い版はそのまま動かし、新しい版を別の窓口（住所や見出しで区別）として足す
- 受け手に知らせる：受け手の一覧の全員に、変更の内容、新しい版、古い版を止める予定日を知らせる。一覧がなければ、まず一覧を作る
- 並行して提供する：受け手が移行する期間、両方の版を動かす。期間は受け手の数と改修の見込みから決める（たとえば最短 90 日）
- 移行を追う：古い版への呼び出しが残っていないかを記録で確かめ、残っている受け手に個別に連絡する
- 古い版を止める：予定日に止め、止めた日と最後まで残っていた受け手を記録する
期限のない並行提供は、古い版を永遠に支える負担になります。期限を決めることが、この手続きの要です。手続きは ARC-009 API互換性・版管理方針 に書き、連携ごとの送り手・受け手は ARC-004 システム連携一覧 で管理します。互換性を壊していないことは、契約テスト（07-07 連携の約束をどうテストするか）で自動的に確かめます。
CASE FACTFROZEN正本に記載されたアステリア案件の事実
アステリア案件の連携に関する記載
- 約36本のシステム連携。正本で個別に定義された連携は IF-01〜IF-12
- 連携の経路に SYS-06 システム連携基盤を通るものと、直接つなぐものがある
- Vendor B クラウドブリッジの担当範囲に 連携 が含まれる。Vendor A は新基幹アプリケーション、Vendor C は FIN-CORE、会計連携、Vendor D は勤怠・工数管理SaaS
- 成果物に ARC-009 API互換性・版管理方針、ARC-004 システム連携一覧 がある
- P-008 黒田 健 — システムアーキテクト
各連携の API の版の付け方、互換性の分類、並行提供の期間、受け手の一覧は、正本に記録がありません。記録なし
6. THINK — 「項目を 1 つ足すだけなので連絡は不要」
送り手の会社の開発者が、次のように言いました。
「応答に項目を 1 つ足すだけです。受け手には影響しないので、連絡せずに出します。」
問題
この判断は正しいでしょうか。何を確かめるべきでしょうか。
判断例を開く
判断
「応答に項目を足す」は、多くの場合は影響のない変更です。しかし、それは受け手が「知らない項目を無視する」作りになっている場合に限ります。
確認すること:
- 互換性の分類で、この変更が「影響なし」に分類されているか
- 受け手が、知らない項目を無視する作りになっているか（厳密に検査して失敗する作りもある）
- 「影響なし」でも、通知は要る決まりになっていないか（通知のみ、と版の変更は別）
- 契約テストで、受け手側のテストが新しい応答でも通るか
- 受け手の一覧で、この連携の受け手が全員分かっているか
「影響しない」は、送り手が決めることではなく、分類と受け手の作りで決まることです。分類にない変更なら、分類を決めてから出します。
7. よくある失敗
- 互換性の分類を決めずに開発を始め、最初の仕様変更で責任の押し付け合いになる
- 新しい版を出したあと、古い版を止める期限を決めず、版が増え続ける
- 受け手の一覧がなく、通知したつもりの受け手が実は一覧になかった
- 「急ぎ」を理由に手続きを飛ばすことが常態化する
8. 成果物との接続
- ARC-009 API互換性・版管理方針：互換性の分類、影響のある変更の手続き、並行提供の期間、通知の方法
- ARC-004 システム連携一覧：連携ごとの送り手・受け手・担当する会社。受け手の一覧の出どころ
9. AI WORKFLOW — 新旧の仕様の差を分類させる
AIは、API 仕様の旧版と新版を比べて変更の種類を挙げ、互換性の分類に当てはめる下書きに役立ちます。
指示例:
「次の API 仕様の旧版と新版を比べ、変更された項目ごとに『変更の種類』（追加・削除・名前の変更・意味の変更・必須化・形の変更）を示し、添付の互換性の分類表に当てはめてください。分類表にない種類は『分類なし』と示し、互換かどうかを推測しないでください。」
10. REVIEW — AIの分類を確認する
- AIが見つけた変更が、仕様の差分と一致しているか（見落とし・誤検出）
- 「分類なし」の変更について、人が分類を決めて分類表に足したか
- API 仕様を AI に渡してよいか（相手の会社との守秘の扱い）を事前に確かめたか
11. 人間が判断すること
- 互換性の分類の境目
- 並行提供の期間と、古い版を止める日
- 急ぐ変更の例外を認めるか
設計承認は、AIへ最終委任しない事項です（正本の方針）。
12. 判断演習
次の 4 つの変更を、「影響なし（通知のみ）」と「影響あり（新しい版）」に分け、理由を書いてください。
- 応答に「更新日時」の項目を足す
- 「金額」の項目を税抜から税込に変える（名前は同じ）
- 要求に任意の「備考」を足す
- 「顧客コード」を 8 桁から 10 桁に変える
2 と 4 について、並行提供の期間を何日にするか、その根拠も書いてください。
あなたの記録あなたの考え。事実ではありません
判断ノート
このユニットで覚えてほしいこと
約束は手続きで変える。変更の種類で影響を分け、影響のある変更は新しい版・通知・並行提供・期限つきの停止で進める。受け手の一覧と自動の確認がなければ、手続きは回らない。