backward-compat-governance

後方互換性ガバナンス

互換性を「残すコード」ではなく「契約と撤去計画」として管理する。

核心原則

後方互換性それ自体が悪ではない。互換性を支える「仕様・テスト・撤去計画・計測」が欠けたとき、互換要求が実装へ流れ込みゴミコード化する。

状態	互換性の扱い	結果
管理あり	契約（仕様）+ テスト + 撤去SLO + 計測	安定性の基盤（資産）
管理なし	実装でのその場しのぎ	互換層の肥大化（負債）

負債化のフィードバックループ

既存クライアント → 「壊すな」の要求
  → 公開APIの固定・増殖
  → 非推奨APIの温存 + 互換アダプタ/分岐追加
  → 複雑性増大・テスト範囲拡大
  → 保守コスト増・変更速度低下
  → 期限圧力で近道実装
  → さらにAPI固定... (ループ)

判断フロー

互換性に関わる変更を検出
    ↓
公開API境界は明確か？
    ├─ NO → 境界を仕様化してから進む
    └─ YES ↓
非推奨化ポリシーはあるか？
    ├─ NO → ポリシーを策定（撤去SLO含む）
    └─ YES ↓
互換処理はどこにあるか？
    ├─ コードベース全体に散在 → 互換層を局所化（Adapter/Strangler Fig）
    └─ 局所化済み ↓
撤去計画はあるか？
    ├─ NO → 撤去タイムライン + 計測を設定
    └─ YES → 計画に従って進行

アンチパターン検出

以下のパターンを見つけたら互換性負債の兆候：

❌ if (version < X) { /* 旧挙動 */ } else { /* 新挙動 */ }  // バージョン分岐の散在
❌ @Deprecated が付いたまま何年も残るAPI
❌ LegacyXxxAdapter, OldXxxWrapper が増殖
❌ "互換性のため" というコメントが散在
❌ 同じ機能の新旧2つのエンドポイントが併存
❌ テストに "backward compat" 系のスキップ/無視がある
❌ 破壊的変更がドキュメント化されていない

対策パターン

1. 公開API境界の明確化

互換対象を限定し、不要な互換コードを防ぐ。

✅ 公開APIを仕様として宣言する（SemVer, OpenAPI等）
✅ 内部APIと公開APIを構造的に分離する
✅ 「何を壊さないか」のスコープを文書化する

❌ すべてのAPIを暗黙的に互換対象にする
❌ 内部実装の変更が外部に漏れる構造

境界の隔離例（Linux kernelの戦略）：

• ユーザ空間ABI: 極力壊さない（安定境界）
• カーネル内部API: 自由に変更可能（進化可能）

2. 非推奨化サイクル（Deprecation Cycle）

撤去を制度化し、コード墓場を減らす。

非推奨宣言 → 移行期間（猶予SLO） → 利用率計測 → 削除

フェーズ	アクション	成果物
宣言	非推奨マーク + 代替案の提示	非推奨注釈、移行ガイド
猶予	移行支援 + 利用率追跡	テレメトリ、移行状況ダッシュボード
削除	利用ゼロ確認後に除去	削除PR、リリースノート

猶予期間の目安（プロジェクト規模に応じて調整）：

• 内部API: 1-2リリースサイクル
• 公開ライブラリ: 最低1メジャーバージョン
• プラットフォームAPI: 2年以上（大規模エコシステム）

3. 互換層の局所化

互換処理を「コードベース全体に散らさない」ことが主戦場。

Adapterパターン: 非互換なI/F同士の差分を一点に集約

// ❌ 散在: あちこちでバージョン分岐
function processOrder(order: Order) {
  if (order.apiVersion < 2) {
    // v1の処理...
  } else {
    // v2の処理...
  }
}

// ✅ 局所化: アダプタで吸収
interface OrderProcessor { process(order: Order): Result }

class OrderV1Adapter implements OrderProcessor {
  constructor(private inner: OrderProcessorV2) {}
  process(order: OrderV1): Result {
    const converted = convertV1toV2(order)
    return this.inner.process(converted)
  }
}