Legacy code navigation
Skill goonobu-dot/dev-skills-library/skills/legacy-code-navigation
15 auto-selectable Claude Code skills distilling engineering best practices (Kent Beck, Fowler, Google SRE, OWASP, Anthropic, Netflix…), with a bilingual offline learning site. Make Claude Code write better code — and learn the practices yourself.
npx -y skills add goonobu-dot/dev-skills-library --skill legacy-code-navigationAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
2 things to look at
- 29 days oldThe repository was created 29 days ago. New is not bad, but a brand new repository carrying a familiar-sounding name is the shape a typosquat arrives in, and there has been no time for anyone else to find a problem with it.
- 0 stars0 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
What its author says it does
Copied from the file, not written here
Strategy for safely understanding and modifying unfamiliar or legacy codebases: trace down from entry points, learn up from primitives, characterize before changing. Use when working in a codebase for the first time, before modifying code whose behavior is unclear, or when the user says レガシー, 初めて触るコード, 引き継いだコード, このコードどうなってる. Not for diagnosing a specific bug (use systematic-debugging).
SKILL.md
6.5 KB, as published. Nobody here has run it
Legacy Code Navigation
未知の大規模コードベースを最初から体系的に理解しようとすると挫折する。1つの具体的なユースケースを外側から内側へ辿り、必要な範囲だけを効率的に把握する（trace down, learn up）。
鉄則
- 全体理解を最初から目指さない。 1つの具体的なユースケース・エントリーポイントから入り、実際のタスクに必要な範囲だけを辿る。
- 未知の振る舞いは、変更する前に必ず「今何が起きているか」を確認する。 目視の推測だけでコードの動作を決めつけない。
- 大きなタスクは「デモ可能な単位」に分解し、各チャンクの完了ごとに動作確認する。
作業手順
ステップ1: trace down — エントリーポイントから実装へ辿る
- タスクに関連する1つの具体的なユースケース（例: 特定のAPIエンドポイント、特定のCLIコマンド、特定のUI操作）を選ぶ。
- そのユースケースのエントリーポイント（ルーティング定義、main関数、イベントハンドラ等）を特定する。
- エントリーポイントから呼び出しを実際に辿り、関与するファイル・関数を実行順にメモしていく。
- 辿る過程で「今は理解できないが後で必要になりそうな箇所」に遭遇したら、深追いせずメモに残して先へ進む。
ステップ2: learn up — 基礎的な構成要素から理解を積み上げる
- trace downで頻出したプリミティブ（共通ユーティリティ、基底クラス、共有の型定義）を特定する。
- それらの役割を、使用箇所から逆算して理解する（定義だけを読むより、実際の呼び出しパターンから学ぶ方が早い）。
- 理解した基礎知識を使って、ステップ1でメモした「後回しにした箇所」に戻り、必要な分だけ埋める。
ステップ3: 変更前に現状の振る舞いを特定する（characterize）
- 変更対象の関数・モジュールについて、現在の入出力・副作用を実際に確認する（ログ・print・デバッガでの実行、または既存テストの読解）。目で読んだだけの推測で「こう動くはず」と決めつけない。
- 既存テストがなければ、現状の振る舞いを固定する特性化テスト（characterization test）を書いてから変更に着手する。
- 状態を変化させている箇所（グローバル変数、副作用のある関数、隠れた引数、暗黙の実行順序依存）を特に重点的に洗い出す。
ステップ4: 小さく変更し、都度検証する
- タスクを「デモ可能な単位」（動作確認できる最小の区切り）に分解する。
- 各チャンクの実装後、実際にその部分の動作を確認してから次へ進む。
- 修正が完了したら、動作を裏付ける根拠（ログ出力・テスト結果）を示してから「直った」「動く」と報告する。
チェックリスト
着手前:
- タスクに関連する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）