Reading an unfamiliar codebase

Do not start at src/ and read top to bottom. That is tourism. Treat the codebase like a crime scene: pick a question, gather evidence, follow one path end to end.

Walking through a single action

Pick a user-visible action — create invoice, submit search, login — and follow it until persistence and back out.

1. Authn / authz checks
2. Validation and domain logic
3. Database, cache, and external calls
4. Response shaping and errors
5. Metrics and logs along the way

Draw this on paper. The drawing is the learning; polish is optional.

Tests as documentation. Golden tests, request snapshots, and happy-path integration tests often describe intended behavior better than comments. When a function confuses you, search for its name under test/ before reading every caller. Characterization tests encode what the system does, not what someone hoped.

Git archaeology. git log -p -- path and blame teach why. Look for the PR that introduced a weird branch, reverts and follow-up fixes, and authors who touch a directory often.

You need to change how refunds calculate tax. Instead of reading billing/ for two days, run git log -S 'refund' -- billing/, open the three PRs that matter, find the design doc link in one of them, and only then read the current RefundService. Three hours with context beats three days without it.

Coding agents can summarize modules and find call sites quickly. Use them to accelerate navigation, then verify by running code and reading the critical path yourself. Shipping an explanation you cannot defend is how you create incidents in month two. See working with AI tools.

Common mistakes

• Reading every file. You will forget it. One traced path sticks.
• Trusting the README as truth. Run the path. Docs lag.
• Letting an agent write a change you cannot defend. Navigation aid, not a substitute for reading.

Check yourself

Where do you start in a new service?

An entry point you can execute — a handler, consumer, or job — then one request all the way through.

You cannot tell why a branch exists. What next?

git log and the PR that introduced it. The description usually has the constraint.

Key takeaways

• Trace entry points and one request. Do not read the tree.
• Tests and git history explain intent better than comments.
• Three hours of archaeology beats three days of undirected reading.
• Verify agent summaries by running and reading the path yourself.

Further learning

Next: asking good questions.

Patricia Aas on reading other people's code with curiosity instead of contempt: