非推奨化とマイグレーション

概要

コードは資産ではなく負債です。コードの1行ごとに継続的なメンテナンスコストがかかります。バグの修正、依存関係の更新、セキュリティパッチの適用、新しいエンジニアのオンボーディングが必要です。非推奨化は価値を生み出さなくなったコードを削除する規律であり、マイグレーションはユーザーを安全に古いシステムから新しいシステムへ移行するプロセスです。

ほとんどのエンジニアリング組織は物を作ることが得意です。しかし、それを削除することが得意な組織はほとんどありません。このスキルはそのギャップに対応しています。

使用する場合

• 古いシステム、API、またはライブラリを新しいものに置き換える場合
• 不要になった機能を廃止する場合
• 重複する実装を統合する場合
• 誰も所有していないが誰もが依存している死んだコードを削除する場合
• 新しいシステムのライフサイクルを計画する場合(非推奨化の計画は設計時に開始します)
• レガシーシステムを維持するか、マイグレーションに投資するかを決定する場合

コア原則

コードは負債です

コードの1行ごとに継続的なコストがかかります。テスト、ドキュメント、セキュリティパッチ、依存関係の更新、および周辺で作業する人に対する精神的なオーバーヘッドが必要です。コードの価値は、コード自体ではなく、それが提供する機能です。同じ機能をより少ないコード、より低い複雑性、またはより良い抽象化で提供できる場合、古いコードは削除されるべきです。

Hyrum の法則は削除を難しくします

十分なユーザーがいれば、あらゆる観察可能な動作は依存されます。バグ、タイミングのクセ、ドキュメント化されていない副作用を含めて。これが、非推奨化には単なる発表ではなく、積極的なマイグレーションが必要な理由です。ユーザーが置き換え版では複製されない動作に依存している場合、「単に切り替える」ことはできません。

非推奨化の計画は設計時に開始します

何か新しいものを構築する場合、次の質問をしてください。「3年後、これをどのように削除しますか?」クリーンなインターフェース、機能フラグ、最小限の表面積を備えたシステムは、実装の詳細があちこちに漏れているシステムよりも、非推奨化しやすくなります。

非推奨化の決定

何かを非推奨化する前に、以下の質問に答えてください。

1. このシステムはまだ固有の価値を提供していますか?
   → はい の場合は維持します。いいえ の場合は進みます。

2. それに依存するユーザー/コンシューマーは何人ですか?
   → マイグレーションの範囲を定量化します。

3. 置き換え版は存在しますか?
   → いいえ の場合は、最初に置き換え版を構築します。代替案がないまま非推奨化しないでください。

4. 各コンシューマーにとってのマイグレーションコストは何ですか?
   → 簡単に自動化できる場合は、実行します。手動で高コストの場合は、メンテナンスコストと比較検討します。

5. 非推奨化しない場合の継続的なメンテナンスコストは何ですか?
   → セキュリティリスク、エンジニアの時間、複雑性のオポチュニティコスト。

アドバイザリーと強制的な非推奨化

タイプ	使用する場合	メカニズム
アドバイザリー	マイグレーションは任意で、古いシステムは安定している	警告、ドキュメント、促促。ユーザーは自分のペースでマイグレーションします。
強制的	古いシステムにセキュリティ問題がある、進捗を阻止している、またはメンテナンスコストが持続不可能である	ハードデッドライン。古いシステムは日付 X に削除されます。マイグレーション用のツールを提供します。

デフォルトはアドバイザリーです。 強制的な非推奨化は、メンテナンスコストまたはリスクがマイグレーションを強制する正当性がある場合にのみ使用します。強制的な非推奨化には、マイグレーション用のツール、ドキュメント、サポートを提供する必要があります。デッドラインを発表するだけでは不十分です。

マイグレーションプロセス

ステップ 1: 置き換え版を構築する

動作する代替案がないまま非推奨化しないでください。置き換え版は以下を満たす必要があります。

• 古いシステムのすべての重要なユースケースをカバーする
• ドキュメントとマイグレーションガイドを持つ
• 本番環境で実証されている(「理論的により良い」だけではない)

ステップ 2: アナウンスとドキュメント

## 非推奨化通知: OldService

**ステータス:** 2025-03-01 以降、非推奨
**置き換え版:** NewService (以下のマイグレーションガイドを参照)
**削除日:** アドバイザリー — 現在のところハードデッドラインなし
**理由:** OldService はスケーリングが手動で、可視性が不足しています。
        NewService はどちらも自動で処理します。

### マイグレーションガイド
1. `import { client } from 'old-service'` を `import { client } from 'new-service'` に置き換える
2. 設定を更新する (以下の例を参照)
3. マイグレーション検証スクリプトを実行する: `npx migrate-check`

ステップ 3: 段階的にマイグレーションする

一度にすべてではなく、コンシューマーを1つずつマイグレーションします。各コンシューマーについて:

1. 非推奨化されたシステムとのすべてのタッチポイントを特定する
2. 置き換え版を使用するように更新する
3. 動作が一致することを確認する (テスト、統合チェック)
4. 古いシステムへの参照を削除する
5. リグレッションがないことを確認する

チャーンルール: 非推奨化されるインフラストラクチャを所有している場合、ユーザーをマイグレーションするか、マイグレーションが不要な後方互換性のある更新を提供する責任があります。非推奨化を発表してユーザーに解決策を見つけさせないでください。

ステップ 4: 古いシステムを削除する

すべてのコンシューマーがマイグレーションした後にのみ:

1. アクティブな使用がゼロであることを確認する (メトリクス、ログ、依存関係分析)
2. コードを削除する
3. 関連するテスト、ドキュメント、設定を削除する
4. 非推奨化通知を削除する
5. 祝う — コードを削除することは成果です

マイグレーションパターン

Strangler パターン

古いシステムと新しいシステムを並行して実行します。トラフィックを古いシステムから新しいシステムへ段階的にルーティングします。古いシステムがトラフィックの 0% を処理する場合、削除します。

フェーズ 1: 新しいシステムは 0% を処理、古いシステムは 100%
フェーズ 2: 新しいシステムは 10% を処理 (カナリア)
フェーズ 3: 新しいシステムは 50% を処理
フェーズ 4: 新しいシステムは 100% を処理、古いシステムはアイドル
フェーズ 5: 古いシステムを削除

アダプターパターン

古いインターフェースから新しい実装への呼び出しを翻訳するアダプターを作成します。バックエンドをマイグレーションする間、コンシューマーは古いインターフェースを使い続けます。

// アダプター: 古いインターフェース、新しい実装
class LegacyTaskService implements OldTaskAPI {
  constructor(private newService: NewTaskService) {}

  // 古いメソッドシグネチャ、新しい実装に委譲
  getTask(id: number): OldTask {
    const task = this.newService.findById(String(id));
    return this.toOldFormat(task);
  }
}

機能フラグマイグレーション

機能フラグを使用して、コンシューマーを古いシステムから新しいシステムへ1つずつ切り替えます。

function getTaskService(userId: string): TaskService {
  if (featureFlags.isEnabled('new-task-service', { userId })) {
    return new NewTaskService();
  }
  return new LegacyTaskService();
}

ゾンビコード

ゾンビコードは誰も所有していないが誰もが依存しているコードです。アクティブにメンテナンスされておらず、明確な所有者がなく、セキュリティ脆弱性と互換性の問題が蓄積しています。兆候:

• 6ヶ月以上コミットがないが、アクティブなコンシューマーが存在する
• 割り当てられたメンテナーまたはチームがない
• 誰も修正しないテストが失敗している
• 既知の脆弱性のある依存関係で、誰も更新していない
• 存在しなくなるシステムを参照するドキュメント

対応: 所有者を割り当ててそれを適切にメンテナンスするか、具体的なマイグレーション計画を立てて非推奨化するかのいずれかです。ゾンビコードは宙ぶらりんの状態にはいられません。投資を受けるか削除されるかのいずれかです。

よくある言い訳

言い訳	現実
「それはまだ機能しています。なぜ削除するのですか?」	メンテナンスされていない動作コードはセキュリティ債務と複雑性を蓄積します。メンテナンスコストは静かに成長します。
「後で誰かがそれを必要とするかもしれません」	後で必要になれば、再構築できます。「念のため」未使用のコードを保持することは、再構築するよりもコストがかかります。
「マイグレーションは高すぎます」	マイグレーションコストを2～3年のメンテナンスコストと比較してください。マイグレーションは通常、長期的にはより安価です。
「新しいシステムを完成させた後、非推奨化します」	非推奨化の計画は設計時に開始されます。新しいシステムが完了したときには、新しい優先事項があるでしょう。今計画してください。
「ユーザーは自分でマイグレーションします」	マイグレーションしません。ツール、ドキュメント、インセンティブを提供するか、自分自身でマイグレーションしてください (チャーンルール)。
「両方のシステムを無期限にメンテナンスできます」	同じことをする2つのシステムは、メンテナンス、テスト、ドキュメント、オンボーディングコストが2倍になります。

危険信号

• 置き換え版がない非推奨化されたシステム
• マイグレーション用のツールまたはドキュメントがない非推奨化アナウンス
• 数年間アドバイザリーのままで進捗がない「ソフト」な非推奨化
• 所有者がおらず、アクティブなコンシューマーがあるゾンビコード
• 非推奨化されたシステムに追加される新機能 (代わりに置き換え版に投資してください)
• 現在の使用状況を測定しない非推奨化
• アクティブなコンシューマーがゼロであることを確認せずにコードを削除する

検証

非推奨化を完了した後:

• 置き換え版は本番環境で実証され、すべての重要なユースケースをカバーしている
• マイグレーションガイドは具体的なステップと例とともに存在する
• すべてのアクティブなコンシューマーがマイグレーション済みである (メトリクス/ログで確認済み)
• 古いコード、テスト、ドキュメント、設定は完全に削除されている
• コードベースに非推奨化されたシステムへの参照が残っていない
• 非推奨化通知は削除されている (役割を果たしました)