外部依存システムのデバッグ・プロトコル
外部APIやWebサービス（以下、外部依存先）に依存するシステムにおいて挙動の変化や不具合が発生した際、迅速かつ正確に原因を特定し、恒久的な対策を策定するための標準的な手順を定義する。
1. 基本原則：現物確認優先 (Verify Before Code)
「コードを疑う前にデータを疑え」。プログラムのロジックを修正し始める前に、必ず外部依存先から提供される生のデータを「現物」として確認することを徹底する。
2. 調査フェーズ
フェーズ1：状況の切り分け (Triage)
問題の発生源を「自社コード」「外部サービス」「実行環境」のいずれかに特定する。
- •自社コードの変更履歴:
git log等を使用し、問題発生のタイミングと符号するコード変更がないか確認する。 - •外部サービスの稼働状況: サービスのステータスページや障害情報を確認する。
- •再現環境の確認: ネットワーク環境（Proxy, DNS, タイムアウト設定など）に起因する問題でないかを確認する。
フェーズ2：生データの検証 (Live Data Verification)
アプリケーションのロジックを介さず、CLIツールや外部ツールを用いて直接リクエストを発行し、レスポンスの内容を確認する。
- •直接検証:
curlやPostman等を用いて、プログラムを介さずにリクエストを実行する。 - •構造と値の分析:
- •構造定義の変更: JSON/XMLのキー名の削除、階層の移動など。
- •意味（セマンティクス）の変更: 同じキー名であっても、返される値の単位、粒度、精度が変更されていないか。
- •データの欠落: 以前は存在したデータフィールドが空（null, 空文字）になっていないか。
3. 分析フェーズ：変更パターンの特定
確認したデータの差異を以下のいずれかに分類し、影響範囲を特定する。
- •構造的変更 (Structural): スキーマの変更。パーサーの修正が必要。
- •意味的変更 (Semantic): データ構造自体に変更はないが、返される値の意味や性質が変化したもの。
- •例：緯度経度の精度の変更、地点名称の抽象度の変化（広域名から詳細名へ、またはその逆）、通貨単位やタイムゾーンの解釈の変更。
- •一時的/過渡的障害 (Transient): ネットワーク遅延、レート制限、一時的なバグ。
- •認証/認可の問題 (Auth): トークンの有効期限切れやアクセス権限の変更。
4. 対策フェーズ：堅牢な設計への反映
対策の優先順位
- •アダプター層の調整: データの変化を吸収するためのマッピング処理の修正。
- •ハイブリッド取得/フォールバック: 単一のリクエストで不足する場合は、複数のパスで補完するロジックの実装。
- •例外処理の強化: 想定外のデータ構造が返された際、システム全体をクラッシュさせずに優雅に縮小運用（Graceful Degradation）できる実装。
恒久的な改善案
- •データの正規化: 外部からの生データを内部で使用する前に、プロジェクト固有のデータモデル（DTO等）に変換して抽象化する。
- •モニタリング: 外部依存先からのレスポンス構造の変化を早期に検知するためのCIテストや監視を検討する。
5. 記録と共有
調査の過程で取得した生のレスポンスデータや、特定した外部仕様の差異は、将来的な参照のために記録（イシューやナレッジベースへの記載）に残すこと。