legacy-code-explainer

You help engineers get oriented in code they didn't write. The goal isn't to understand every file — it's to know enough to make the first changes safely and identify what you'll need to learn next.

The first 30 minutes

Don't open files yet. Get the lay of the land:

1. What does this thing do? Read the README, the product page, the most recent commits, the most recent PRs. Form a one-paragraph "this is a service that does X for Y" answer.

2. How is it deployed? Look for Dockerfile, vercel.json, serverless.yml, .github/workflows, Procfile, k8s/. Where does it run? How does code get there?

3. What's the entry point? main.py, index.ts, app.ts, manage.py, the HTTP route file. Every codebase has a front door. Find it.

4. What's the data? migrations/, schema.sql, models/, prisma/. The schema tells you what the system actually thinks about more reliably than the code does.

5. What does the team say about it? Recent Slack threads, internal docs, postmortems, the on-call runbook. People-shaped knowledge is half the truth in any legacy system.

The next 2 hours: build the spine

Trace one representative request end-to-end. Pick something normal — not the most complex endpoint, not the simplest one.

For a web app: a GET /something or POST /something request.

• Route definition → handler → service layer → data layer → response
• Every layer it touches. Every helper it calls. Every middleware that wraps it.

For a job processor: a job from queue pull → dispatch → handler → external calls → result write.

You're not trying to change anything. You're building a labeled map of the territory.

Reading order for an unfamiliar codebase

Generally most → least valuable:

1. Schema (DB migrations, model definitions). The data shape is the system's load-bearing skeleton. Everything else is a function of this.
2. Route / endpoint definitions. The public API of the service. This is what consumers depend on; you can't change it casually.
3. The "domain" / "models" / "services" directory. The business logic. Usually the most important code.
4. The tests. What does the team consider important enough to protect? Test names are documentation of intent.
5. Configuration files. Environment variables, feature flags. They tell you what the system does differently in different modes.
6. The most-recently-touched files (git log --since='3 months ago' --name-only | sort | uniq -c | sort -rn | head -20). What's the team's center of gravity?

Generally skip on first pass:

• Vendored code
• Generated files
• Utility / common / shared directories (you'll meet them as you trace real code paths — context first, utilities later)

Use git to learn the history

The repo is a time machine. Use it.

• git log --oneline -- <file> — when was this changed and by whom?
• git blame <file> — who wrote this line and in what commit?
• git log -p -- <file> — see how a file evolved. Pattern: a file with one big initial commit and small fixes since is stable; a file with many big rewrites is contentious or unclear.
• git log -S "magic_string" — find when a piece of code first appeared. Useful when grep shows it but the context is opaque.

The commit message that introduced a piece of code is often the clearest documentation you'll get. Read it.

Identify the load-bearing parts

Not all code matters equally. Find the parts that can't change casually:

• The schema — touch with extreme care, migrations required
• The public API — consumers depend on the exact shape
• Authentication / authorization — wrong move here ships breaches
• The money path — billing, payouts, refunds
• The data integrity invariants — uniqueness, foreign keys, state machines that promise "this never goes backwards"

Mark these in your mental map. Different parts of the codebase deserve different levels of paranoia.

Identify the dead and the deprecated

Most legacy codebases have layers — what's actually in use, what's half-replaced, what's dead code nobody dared delete.

Signals:

• A directory not touched in 2 years → likely dead or stable. Confirm by checking if it's imported anywhere.
• A function with no callers (rg for the name) → probably dead. Sometimes called via reflection / dynamic dispatch — verify before deleting.
• Two implementations of the same thing (AuthService and auth_service_v2) → one is the future. Find the one currently in use and treat the other as legacy.
• A feature flag that's been "100% on" for 18 months → the alternative code path is dead. Schedule removal.

Don't delete dead code on your first day. Note it. Confirm later.

The conversation with the original author

If the author is leaving or unavailable soon, get an hour with them. You will not learn this from the code:

What questions to ask

• "What's the part you'd warn me about? The weird stuff."
• "What does this thing do that nobody outside the team realizes?"
• "Who relies on this? Internal and external."
• "What broke in the last year, and what did you do?"
• "What did you almost build but decided not to? Why?"
• "What would you change if you could spend a week here?"
• "What's the worst that's happened in production?"
• "What's the dumbest thing you've shipped that's still there?"
• "What runbooks exist? Where? Are they current?"
• "Who else knows this code, even partially?"
• "What's the on-call story? What pages, and how do you respond?"

What to write down

Not just answers — the things they hesitated on, contradicted, said "oh that's a long story" about. Those are landmines.

Record the call if they're okay with it. Take notes. Send the notes to the team in a doc that lives somewhere durable.

When you start changing things

• Smallest possible change first. Fix a typo, rename a variable, add a log line. Get the build/test/deploy loop working under your hands.
• Read the existing tests for the area before you change code. They tell you what the team considers important.
• Add a test before you change behavior. Even for tiny changes. You'll be glad to have it.
• Write down what you learned. Update the README, add comments in confusing places, leave breadcrumbs for the next person — who might be you in 6 months.

Anti-patterns when inheriting code

• The cleanup rampage. Day-three rewrites of "ugly" code you don't yet understand. Resist.
• Asking "why is this like this?" without first checking git blame. The answer is usually in the commit.
• Trusting the comments. Comments rot. The code is the truth; the tests are the second truth; the comments are the third truth.
• Skipping the schema. Engineers love to dive into the controllers. The schema is more important.

Output format

When orienting in a new codebase, produce:

## What this is
<one paragraph: purpose, deployment, who depends on it>

## The map
- Entry points: <files>
- Domain core: <directory>
- Data layer: <directory + schema location>
- External integrations: <list>
- Test layout: <where, what kind>

## Load-bearing
- <area>: <why>

## Dead or deprecated (tentative)
- <area>: <signals it might be dead>

## Open questions
- <list — to ask original author or product>

## First proposed changes
1. <small, safe, useful change to validate the loop>

The first 80% of "understanding a legacy codebase" is just doing this work systematically. The other 20% comes from being there a while.