大規模スキーマ移行を6フェーズに分けてADRで管理する

複数モジュールが共有しているリソースの所有モデルを変更するとき、一気にやるとリスクが高い。ADR（Architecture Decision Record）で設計根拠を残しつつ、6フェーズに分けて段階的に移行するパターンがうまくいった。

1. スキーマ追加 — 新しいカラムを追加するだけ。既存コードに影響なし
2. 新規書き込みの切り替え — 新規レコードから新カラムに書き込む
3. 既存データのバックフィル — 既存レコードに遡及的に値を付与
4. 読み取りの切り替え — 新カラムベースのクエリに段階的に移行
5. 旧カラムの参照停止 — 旧キーへの依存を完全に除去
6. クリーンアップ — 旧カラム削除、不要コードの除去

各フェーズが独立してデプロイ・ロールバックできるのがポイント。途中で問題が起きても前のフェーズに戻せる。

ADRとissue管理を連携させると効果的:

• ADRからissueへの参照を張る — 「なぜこの順番か」「完了条件は何か」をトレースできる
• フェーズごとにissueを切る — 進捗が可視化され、レビュー単位も小さくなる
• 設計の根拠がADRに残る — 半年後に「なぜこうしたか」を追える

「書き込みを先に切り替え → バックフィル → 読み取りを切り替え」の順序が重要。逆にすると、バックフィル前の古いデータが新しいクエリで漏れる。