画面間遷移の暫定実装を「借金化」させない方法

なぜ書いたか

レガシー移行を画面単位で進めていると、ある画面の「次の遷移先」がまだ移行されていないという状況が普通にあります。とりあえず未移行先のスタブに飛ばしておく、という暫定実装をしたくなるんですが、これを 何も書き残さずに置く と、後で借金になります。今回はその扱い方をルール化した話です。

やったこと

3つだけです。

1. 暫定遷移先には必ずマーカーを残す: コード上にコメント、mapping上に「暫定」と明記
2. 差し替え予定箇所を一覧化: migration_mapping.md に「正式遷移先が確定したら差し替えるべき場所」をまとめる
3. 対象画面の移行が終わったら、差し替えタスクをスライスに切る: 自然消滅させない

具体的には、こんなコメントとログを残します。

// 暫定: 未移行画面への遷移。
// 差し替えタスク: 対象画面の移行完了後、/blog/xxx-page/ に正式遷移するよう変更。
NavigationManager.NavigateTo("/legacy/xxx");

mapping:
- 申請処理画面のフッター 6 ボタン中 1 つは暫定遷移
- 差し替え条件: 受付情報画面の S5 完了後

わかったこと

• 暫定実装そのものは悪ではない。問題は 暫定であることが見えなくなる こと
• コードのコメントだけでなく、mappingにも書かないと忘れる。コメントは「差し替え時の手元情報」、mappingは「差し替えるべきという認識を組織で持つための情報」
• AIに実装させると、暫定遷移を 何の説明もなしに本実装と同じ顔で書いてくる。Orchestrator側で「暫定なら必ずマーカーを残す」をルール化しないと崩れます

借金化の典型パターン

借金として残りやすいのは、こういうやつです。

• 「ログイン後のホーム」がまだ未移行で、各画面のヘッダーから飛ばすリンクが暫定。後でホームを移行したときに、全画面のリンクを直す必要がある
• 検索ダイアログの「詳細表示」ボタンが、未移行の旧画面に飛ばしている。新画面に差し替えるのを忘れて長期間運用される
• 印刷・帳票出力の遷移先が暫定で「未対応」メッセージのみ表示。利用者からは「いつできるんですか」と聞かれるが、開発側のリストには載っていない

どれも 書き残しがなければ確実に忘れます。

次にやること / 未解決の問題

• 「暫定遷移マーカー」の検索をCIで自動化したい（grep -r "暫定:" src/ で残り件数を可視化）
• 差し替えタスクを自動的に発行する仕組みは未着手。今は手動でmappingを見て切っている