Legacy Code Archaeology

# Legacy Code Archaeology Changing code you don't understand produces fixes that work by coincidence. Spend the first session building a map; the change itself becomes small. ## Phase 1 — Survey the territory (15 minutes, no deep reading) 1. Read the README, then ignore its claims — verify against reality. Docs in legacy repos describe the system as it was two rewrites ago. 2. Inventory: `ls` the top level, read the dependency manifest (package.json, go.mod, requirements) — dependencies tell you the architecture (web framework, queue, ORM, test runner). 3. Find the entry points: `main`/server bootstrap, route registrations, CLI command table, cron/queue consumers. List them. Everything in the codebase is reachable from one of these or it's dead. 4. Run the thing. Build, test suite, dev server. The errors you hit are your first real documentation of hidden setup requirements — write each one down with its fix. ## Phase 2 — Trace the one flow that matters Don't read the codebase; read the *path your task touches*, end to end. - Start from the entry point (the route, the command, the consumer) and step through to the data store and back. At each hop, note file:line and what the data looks like at that point. - Use search as your debugger: grep for the user-visible string (error message, button label, log line) and walk backwards from where it's produced. This is usually the fastest way in. - When the flow is hard to follow statically (DI containers, event buses, metaprogramming), follow it dynamically: set a breakpoint or add a temporary `console.trace`/stack-dump log at the suspected handler and exercise the feature. Delete the probes after. - Distinguish the load-bearing path from the decoration. Feature flags, A/B branches, and "temporary" fallbacks from 2019 — note which branch actually runs in production (check the flag's default and config). ## Phase 3 — Mine the history - `git log --follow -- <file>` and `git blame` on the confusing parts. The commit message (and linked ticket) for a weird conditional often explains the bug it guards against. - `git log -S "<symbol>"` finds when something was introduced or removed and what came with it. - A hack with a ticket number is a constraint; a hack without one is a candidate for careful removal — but only after Phase 4 pins its behavior. ## Phase 4 — Write the map, then probe it - Write down (scratch file or PR notes): entry point → key modules in order → data shapes at boundaries → side effects (DB tables, events, external calls) → the invariants you *think* hold. - Test your map with a prediction: "If I change X, the response field Y will become Z." Make a throwaway change, run it, check. A wrong prediction means the map is wrong — fix the map before touching real code. - Mark the danger zones you found: shared mutable state, ordering dependencies, code with zero test coverage on your path. ## Signals worth collecting along the way - Test suite shape: which areas have real tests vs. none — that's your risk map for the change. - TODO/FIXME/HACK density per module, and whether the names in code match the names the team/docs use (mismatches mark half-finished renames and conceptual drift). - Files with the highest churn in `git log --since="1 year" --name-only` — that's where the system actually lives today, regardless of what the architecture diagram says. ## Rules - No refactoring during archaeology. Resist cleaning up while reading — you don't yet know which ugliness is load-bearing. - Before changing anything on the path, pin current behavior with a characterization test at the nearest seam (often the route/handler level when units are untestable). - Keep the map. Promote the useful parts into the repo (module README, architecture note) in a separate docs commit — the next archaeologist is probably you.