Getting to know an unfamiliar codebase

What you’ll be able to do

Go from “I’ve never seen this repository” to “I understand how it’s organised and know where to make my change” in under an hour, and check that what Claude tells you is actually true.

Why this matters

Joining a new team, picking up an old project or contributing to open source all start the same way: a large codebase you don’t understand yet. Traditionally, that means hours of clicking through files, reading half-documented code and asking colleagues. Claude Code can read a codebase much faster than you can, and explain it at whatever level you need.

But speed only helps if the explanation is right, and if you ask questions in an order that builds real understanding. This lesson gives you a sequence of questions, the exploration ladder, that works from the big picture down to the exact place you’ll change, plus the habit of checking what Claude claims.

Pick a codebase

Use a real open-source project you’re curious about; a medium-sized repository works best. For example, Express, a popular Node.js web framework:

git clone https://github.com/expressjs/express
cd express
claude

The exploration ladder

Work from broad to specific. Each rung builds on the one before, so resist jumping straight to “where do I change X?”. Without the big picture, you can’t judge whether the answer makes sense.

Rung 1: the map. What are the main parts, and how do they relate?

Give me an architectural overview of this repository: the main modules, what
each is responsible for, and how they relate. Cite file paths.

What you’ll see: Claude lists folders and reads key files (README, entry points, package configuration) before answering. You get a structured overview with file paths you can open.

Rung 2: the flow. How does one real operation move through the code?

Trace what happens when an HTTP request comes in, step by step, from the entry
point to the response being sent. Cite file:line for each step.

What you’ll see: a numbered walkthrough with file:line references. This is the single most useful view of an unfamiliar system, because it connects the parts from rung 1.

Rung 3: the conventions. How does this team write code?

What patterns and conventions does this codebase follow (error handling, testing,
naming)? Show one representative example of each.

What you’ll see: short excerpts showing how errors are handled, how tests are structured, and how things are named. Follow these when you make changes, so your code fits in.

Rung 4: the change. Now you can ask about your actual task:

I want to add <your feature or fix>. Which files would change, what's the risk,
and what existing tests cover this area?

What you’ll see: a list of files, the risky spots, and the tests to run. This is effectively an impact assessment before you’ve written a line.

Trust, but verify

Claude’s explanations are usually accurate, but it can occasionally misread code, especially in large or unusual codebases. Build two habits:

• Spot-check a claim by opening the cited file and line. If it doesn’t match, say so. Claude will re-read and correct itself.
• Ask “how do you know?” when something sounds surprising. Claude will show you the code it based the claim on.

Going deeper

• Use git history to learn why code is the way it is: “Why was this function written this way? Check git log and git blame for context.” Commit messages and old changes often explain decisions that the code alone doesn’t.
• Ask for a diagram: “Draw the request flow as a Mermaid sequence diagram.” Paste the result into any Mermaid viewer, such as the live editor at mermaid.live, to see it as a picture.
• Save what you learn: “Summarise what we’ve learned into docs/ONBOARDING.md for the next new developer.” An exploration session becomes documentation your teammates can use.

Exercise

On your chosen repository:

1. Climb all four rungs of the ladder. For rung 4, pick a small, realistic change.
2. Verify one claim: open a file:line Claude cited, and confirm the code does what it said.
3. Use history: ask about the reasoning behind one function, using git log and blame.
4. Draw it: ask for a Mermaid diagram of the flow from rung 2, and view it in a Mermaid viewer.
5. Write it down: have Claude create docs/ONBOARDING.md with what you learned. Keep it local; don’t push it to the upstream project.

Common mistakes

• Starting at rung 4. Without the map and the flow, you can’t judge whether the suggested change is sensible.
• Accepting explanations without citations. Ask for file:line references so you can check.
• Never checking. Spot-check at least one claim per session.
• Losing what you learned. Ask Claude to write it down before you /clear.

Verify it worked

• You can explain the repository’s main components without looking
• You checked at least one cited claim against the code
• You used git history to explain why some code exists
• You have a list of the files you’d touch for a specific change