playbook

Map a codebase you've never seen

Point Claude at an unfamiliar repo and get a grounded tour — the real modules, how a request flows, and where the scary parts live — in plain English, naming files that exist.

easy ~15 min

when to reach for this

New job, new repo, or just a corner of the product you've never touched. The README is three rewrites out of date and the person who wrote the auth flow left two months ago. Normally this is a day of grep and guessing. You don't need Claude to write the code — you need it to read forty files faster than you can and tell you the truth about what's actually there.

gather this first

The repo itself — open Claude Code in the project root so it reads your real files, not its memory of how projects like this *usually* look.
One concrete entry point you care about: a route, a user action, a CLI command — "what happens when a user signs up" beats "explain the code."

the workflow

01
Ask for the map, not a lecture

Start wide. You want the top-level shape and the real file names, so you know where to put your hands before you go deep.
you ask
```
Read this repo and give me the map: the top-level modules, how a request actually flows from the route to the database, and where authentication lives. Plain English, and name the real files — don't give me a generic framework lecture.
```
what you get back A grounded tour — src/routes/ → middleware/auth.ts → the session store — naming files that exist. You now know the skeleton.

If it starts describing a generic version of your framework instead of your actual files, it hasn't read the repo — make sure you opened Claude Code in the project root.
02
Trace one real path end to end

Pick the flow you actually care about and have it walk the whole path. This is where a vague map becomes a thing you could change.
you ask
```
Walk me through exactly what happens when a user signs up: which files run, in what order, and where the data ends up. Name each file and the function in it, and flag anything that surprised you.
```
what you get back An ordered trace — handler → validation → user creation → session — with file:function pointers, plus a note on anything non-obvious (a hidden side effect, a queue, a second write).
03
Find the landmines before you touch anything

Before you change code you didn't write, ask what's fragile. Cheaper to hear it now than to discover it in production.
you ask
```
If I had to change the signup flow next week, what would bite me? Point out the tightly-coupled bits, the implicit assumptions, the parts with no tests, and anything that looks load-bearing but undocumented.
```
what you get back A short risk list — "the email send is synchronous and will block," "this assumes a users.id is an int," "no tests cover the duplicate-email path" — so you go in with your eyes open.

make it your own

**Onboarding a teammate:** ask for a ARCHITECTURE.md — "write a one-page map of this repo a new hire could read on day one" — and check it into the repo so the next person doesn't start from zero.
**Big repo:** reach for a subagent for the wide reads ("search the whole repo for every place we read from the database") so the deep dig doesn't crowd out the context you need for the actual work. See /features/subagents/.

watch out for

It's reading, not gospel — spot-check the two or three claims you're about to act on by opening the files yourself. A confident wrong pointer is still wrong.
If the repo is huge, it may summarize the parts it sampled and present them as the whole. Ask "what did you *not* read?" to find the blind spots.

you'll end up with In fifteen minutes you go from "I've never seen this code" to a real mental map — the modules, one full request path, and the fragile parts — that you'll keep using all week.

Ask for the map, not a lecture

Trace one real path end to end

Find the landmines before you touch anything