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. At team scale it's the same move repeated: onboarding a whole team onto a repo nobody currently owns, where the map you produce becomes the shared starting point instead of five people grepping in parallel.
- The repo itself — in Claude Desktop, open the project's root folder so Claude reads your real files, not its memory of how projects like this usually look. (Power Track:
claudein the project root from a terminal does the same thing.) - 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."
-
Ask for the map, not a lecture
Open the folder in Claude Desktop and ask in the chat — no terminal needed to read a repo. 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 askRead 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 the project's root folder is the one open in Claude Desktop (or that you launched
claudefrom the project root in the terminal). -
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 askWalk 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).
-
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 askIf 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.idis an int," "no tests cover the duplicate-email path" — so you go in with your eyes open.
- Turn the map into your project context: distil this read into a checked-in
CLAUDE.mdso it becomes a durable asset every later task inherits, not a one-time conversation you lose when the chat closes. That's the next playbook in the path —project-context. - 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/.
- 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, and you're the author of record on anything you do next.
- 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.
- Keep the read in-boundary: the open folder is the boundary, so point Claude at the repo and approve each read, but keep anything proprietary or under NDA out of a context your company hasn't approved.
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.
Questions people ask
- Do I need to prepare anything before starting, or can I just open the repo?
- Open the project's root folder in Claude Desktop — that's the one thing that matters, and it needs no terminal. Without it, Claude reads its training memory of how repos like yours usually look, not your actual files. Have one concrete entry point ready (a route, a user action, a CLI command) so the first question is specific rather than "explain the whole codebase."
- How do I know if Claude actually read my files versus hallucinating a plausible structure?
- Ask it to name specific files and functions, then spot-check two or three against the real tree. If the file paths it quotes don't exist or the function names are wrong, it's describing a generic version of your framework, not your repo — make sure the root folder open in Claude Desktop is the project's, not a parent or sibling directory (or, in the Power Track, that you launched `claude` from the project root).
- Can I use this on a huge monorepo with hundreds of modules?
- Yes, but reach for a subagent for the wide reads so the broad search doesn't crowd out your working context. Ask Claude to "search the whole repo for every place we read from the database" via a subagent, then use the results to focus the mapping conversation on the areas you actually care about.
- What if I want to onboard a teammate with the same map?
- Ask Claude to write an `ARCHITECTURE.md` — "write a one-page map of this repo a new hire could read on day one" — and commit it to the repo. The map you just got is the raw material; the `ARCHITECTURE.md` is the artefact that means the next person doesn't start from zero.