Getting to know an unfamiliar codebase

What you’ll be able to do

Go from “never seen this repo” to “I know where to make my change” in under 30 minutes.

Pick a codebase

Use a real open-source project you’re curious about. Any medium-sized repository works. For example:

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

The exploration ladder

Work from broad to specific. Each rung builds on the one before it.

1. The map

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

2. The flow

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.

3. The conventions

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

4. The change

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

Tips that make a big difference

• Ask “how do you know?” if a claim sounds surprising. Claude will show you the code.
• Use git history: “Why was this function written this way? Check git log and blame for context.”
• Ask for a diagram: “Draw the request flow as a Mermaid sequence diagram.” Then paste it into any Mermaid viewer.
• Save what you learn: “Summarise what we’ve learned into docs/ONBOARDING.md.” Your teammates will thank you.

Exercise

On your chosen repo:

1. Climb all four rungs of the ladder.
2. Pick one claim Claude made and check it yourself by opening the cited file.
3. Ask for a Mermaid diagram of one flow.
4. Write docs/ONBOARDING.md (locally, without committing it to the upstream project) with what you learned.

Verify it worked

• You can explain the repo’s main components without looking
• You checked at least one cited claim against the code
• You have a list of the files you’d touch for a specific change