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

変更前:

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

変更後:

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

アンチパターン集

出典

• 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）