Legacy code navigation

Legacy Code Navigation

未知の大規模コードベースを最初から体系的に理解しようとすると挫折する。1つの具体的なユースケースを外側から内側へ辿り、必要な範囲だけを効率的に把握する（trace down, learn up）。

鉄則

1. 全体理解を最初から目指さない。 1つの具体的なユースケース・エントリーポイントから入り、実際のタスクに必要な範囲だけを辿る。
2. 未知の振る舞いは、変更する前に必ず「今何が起きているか」を確認する。 目視の推測だけでコードの動作を決めつけない。
3. 大きなタスクは「デモ可能な単位」に分解し、各チャンクの完了ごとに動作確認する。

作業手順

ステップ1: trace down — エントリーポイントから実装へ辿る

1. タスクに関連する1つの具体的なユースケース（例: 特定のAPIエンドポイント、特定のCLIコマンド、特定のUI操作）を選ぶ。
2. そのユースケースのエントリーポイント（ルーティング定義、main関数、イベントハンドラ等）を特定する。
3. エントリーポイントから呼び出しを実際に辿り、関与するファイル・関数を実行順にメモしていく。
4. 辿る過程で「今は理解できないが後で必要になりそうな箇所」に遭遇したら、深追いせずメモに残して先へ進む。

ステップ2: learn up — 基礎的な構成要素から理解を積み上げる

1. trace downで頻出したプリミティブ（共通ユーティリティ、基底クラス、共有の型定義）を特定する。
2. それらの役割を、使用箇所から逆算して理解する（定義だけを読むより、実際の呼び出しパターンから学ぶ方が早い）。
3. 理解した基礎知識を使って、ステップ1でメモした「後回しにした箇所」に戻り、必要な分だけ埋める。

ステップ3: 変更前に現状の振る舞いを特定する（characterize）

1. 変更対象の関数・モジュールについて、現在の入出力・副作用を実際に確認する（ログ・print・デバッガでの実行、または既存テストの読解）。目で読んだだけの推測で「こう動くはず」と決めつけない。
2. 既存テストがなければ、現状の振る舞いを固定する特性化テスト（characterization test）を書いてから変更に着手する。
3. 状態を変化させている箇所（グローバル変数、副作用のある関数、隠れた引数、暗黙の実行順序依存）を特に重点的に洗い出す。

ステップ4: 小さく変更し、都度検証する

1. タスクを「デモ可能な単位」（動作確認できる最小の区切り）に分解する。
2. 各チャンクの実装後、実際にその部分の動作を確認してから次へ進む。
3. 修正が完了したら、動作を裏付ける根拠（ログ出力・テスト結果）を示してから「直った」「動く」と報告する。

チェックリスト

着手前:

• タスクに関連する1つの具体的なユースケースを選んだか（コードベース全体を理解しようとしていないか）
• エントリーポイントを特定し、そこから実際の呼び出しを辿ったか
• 「後で必要になりそうだが今は不明な箇所」をメモに残したか

変更前:

• 変更対象の現在の振る舞いを実行・ログ・テストで確認したか（目視の推測のみで済ませていないか）
• 保護テスト（特性化テスト含む）は存在するか
• 状態を変化させる副作用箇所（グローバル変数・隠れた引数・実行順序依存）を洗い出したか

変更後:

• 変更をデモ可能な単位に分解し、各単位ごとに動作確認したか
• 「直った」と報告する前に、ログ・テスト等の根拠を提示したか

アンチパターン集

やりがちな進め方	現実・対処
いきなりディレクトリ全体を読んで「全体像を理解してから」着手しようとする	大規模コードベースでは挫折するか時間切れになる。1ユースケースに絞って辿る
コードを目で読んだだけで「多分こう動く」と判断する	人間もAIも読解による脳内シミュレーションは高確率で誤る。実行・ログ・テストで確認する
保護テストがないまま既存コードを変更する	既存の振る舞いを壊しても気づけない。先に特性化テストを書く
状態変化（グローバル変数・副作用）を見落として変更する	レガシーコードのバグの多くは隠れた状態依存に起因する。重点的に洗い出す
巨大なタスクを一度に実装し、最後にまとめて動作確認する	途中で間違った方向に進んでも気づくのが遅れる。デモ可能な単位で都度確認する
「動いたはず」で報告を終える	検証の根拠（ログ・テスト結果）を示さない報告は信頼できない。必ず根拠を添える
後回しにした不明箇所をそのまま放置して次のタスクへ進む	メモを残さないと同じ調査を繰り返す羽目になる。メモに残し、必要になった時点で回収する

出典

• Mitchell Hashimoto — Contributing to Complex Projects（"trace down, learn up"アプローチ）
• Mitchell Hashimoto — My Approach to Building Large Technical Projects（デモ可能な単位への分解）
• John Carmack — デバッガでの実行トレース・推測に頼らない検証の考え方（Errata Security: Use the freakin' debugger）