TL;DR

  • Ask Claude Code for a plain-language tour of the repo, then save it with /init.
  • Trace one real feature from its entry point all the way to the data.
  • Verify by restating the flow in your own words and letting Claude Code find the gap.

📊 Result Proof Box Minute 0: 200 folders you didn’t write and no idea where to look. Minute 20: a written CLAUDE.md map of the repo, plus one feature traced from its route to the database, in order.

You cloned the repo on day one and it’s a wall of folders you didn’t write. By the end of this you’ll understand a new codebase well enough to start contributing: you’ll have a map of it, one real feature traced from start to finish, and a way to check that you actually got it. Reading code is most of the job in your first week, so feeling lost right now is normal, not a sign you’re behind. One field study found developers spend about 58% of their time just reading and understanding code (Xia et al., IEEE TSE 2018). You’re allowed to spend week one reading.

You’ll need:

  • Claude Code installed and signed in (a one-time setup)
  • The repository cloned to your machine and openable in your editor
  • A terminal open at the repo root
  • About 20 minutes and one feature you’re curious about

Try It Now

  1. In your terminal, at the repo root, run claude.
  2. Type: Give me a tour of this repo: the top-level directories and what each one is for.
  3. When the tour looks right, type /init to save it.

This fits naturally into how teams adopt AI agents; if you want that bigger picture, see where AI coding agents fit in a team’s adoption.

Where do you start to understand a new codebase?

Open the repo in your terminal, run claude to start Claude Code, and ask for a tour. Claude Code reads the actual files in the project and hands you a directory-by-directory map in plain language. It isn’t a chat box guessing from training data; it’s an agentic tool that opens your real files and reports what’s there.

What: Ask for a high-level tour of the top-level folders. Why: You need orientation before any detail, so you know where things live before you go looking.

$ claude
> Give me a tour of this repo: the top-level directories and what each one is for.


This is a web app. The main areas are:
- src/routes/    HTTP routes (where requests come in)
- src/services/  business logic
- src/models/    database models and queries
- tests/         the test suite
…

Verify: You can name the three or four top-level areas out loud and say what each one does. If you can’t yet, ask about one folder at a time until you can.

Key insight: Developers spend about 58% of their time reading and understanding code, more than writing it (Xia et al., IEEE TSE 2018). A good map is the most useful 20 minutes of your week.

How do you turn that tour into a CLAUDE.md you can reuse?

Run /init. Claude Code scans the repo and writes a CLAUDE.md, which is a project memory file the agent reads automatically at the start of every future session. That means the map you just earned doesn’t vanish when you close the terminal, and you never start from zero again.

What: Run the /init command. Why: Your hard-won map shouldn’t live in one throwaway chat that you’ll lose by tomorrow.

> /init


Analyzing repository structure…
Wrote CLAUDE.md at the repo root.
It captures: the main directories, the build and test commands,
and how the pieces fit together.
…

CLAUDE.md is the file Claude Code uses as its memory of your project (project memory docs). It’s the first of two new ideas in this guide.

Verify: A file named CLAUDE.md now exists at the repo root. Open it in your editor and skim it. If a section looks wrong, you can edit it like any other file, and Claude Code will read your correction next time.

Key insight: A map you keep beats a map you re-derive. CLAUDE.md turns one good orientation into something every future session starts from, so the work compounds instead of resetting (project memory docs).

How do you trace one feature from click to database?

Pick one feature you can see in the running app, then ask Claude Code to trace it from the entry point to the data store, and follow the files it names as it goes. A single thread you can follow end to end teaches you more than ten files you skimmed. Tracing one feature is the second new idea here.

What: Trace one real, user-facing feature, like logging in or loading the homepage. Why: One complete path shows you how the layers connect, which is the thing a folder list can’t.

> Trace what happens when a user logs in, from the route to the database.
> List the files in order.


1. src/routes/auth.js   receives POST /login
2. src/services/auth.js validates the password
3. src/models/user.js   looks up the user row
4. the database          returns the user record
…

Open each file it names, in order, as you read the trace. You’re not memorizing it; you’re watching the path connect.

Verify: You can list the files in the path, in order, without looking back at the output. That ordered list is your proof you followed a real thread, not just read about one.

Key insight: One traced feature beats a hundred skimmed files. The path from route to database is the same shape in most web apps, so the habit transfers to whatever stack you joined.

How do you decode a function you don’t understand?

Point Claude Code at the function and ask for a plain-English explanation, then ask one follow-up about the part that’s still fuzzy. Naming your confusion out loud is faster than reading the same function five times and hoping it clicks. Nobody reads a strange function cold and just gets it; asking is the skill, not a shortcut.

What: Ask for a plain-English explanation of one function, then ask a follow-up. Why: Pinpointing the exact line that confuses you turns a vague “I’m lost” into a question someone can answer.

> Explain what validatePassword in src/services/auth.js does, in plain English.


It takes a plain-text password and the stored hash, hashes the
input the same way, and returns true only if they match. It does
not store anything; it just compares.


> What does "hash" mean here, and why compare hashes instead of the password?
…

Verify: You can say what the function takes in and what it gives back, in one sentence, without re-reading it. If you still can’t, that’s your next follow-up question, and that’s a completely normal place to be.

Key insight: Naming the exact line that confuses you turns a vague “I’m lost” into a question Claude Code can actually answer. Precision beats re-reading the same function and hoping it clicks.

How do you check you actually understood it?

Close the explanation, restate the feature’s flow in your own words, and then ask Claude Code to check what you got wrong. Passive reading feels like understanding, but it often isn’t; if you can’t restate the flow, you haven’t understood it yet, and that’s fine. This is the step that turns “I read it” into “I get it.”

What: Write your own short summary, then ask Claude Code to find the gaps. Why: Restating from memory is the only honest test of whether the map stuck.

> Here's my understanding of login: the route in auth.js takes the
> POST, the service hashes the password and compares it to the stored
> hash, and the model reads the user from the database.
> What did I get wrong or leave out?


Close. One thing to add: the route also creates a session after a
successful match, so the user stays logged in on the next request.
…

Verify: Claude Code confirms your summary, or you patch the one gap it found and ask again until it does. When your restatement holds up, you understand the feature, and you have a CLAUDE.md map to come back to. As you start reading other people’s work, trusting AI-written code is a good companion read for the verify habit.

Key insight: If you can’t restate the flow from memory, you haven’t understood it yet, and that’s fine. Restating is the only honest test of whether the map stuck, and it’s the step most people skip.

FAQ

Can Claude Code understand a codebase it didn’t write?

Yes. Claude Code reads the actual files in the repository, so it works on code it has never seen. It’s an agentic tool that opens your real files and runs commands, not a chat box limited to its training data (how Claude Code works in large codebases).

Will /init change my code?

No. /init writes a CLAUDE.md map at the repo root and does not edit your source files. It’s a read-and-summarize step, so it’s safe to run on day one without worrying you’ll break something.

What if the codebase is huge or a monorepo?

Scope Claude Code to the subdirectory you’re actually working in instead of the whole tree. The large codebases docs cover how to point it at one area so the map stays focused and useful.

Should I trust everything Claude Code tells me about the code?

Treat it as a fast first draft of your understanding, then verify it against the running app, which is exactly what the last step does. The same trust-but-check habit applies more broadly in trusting AI-written code.

Is using Claude Code to learn the repo cheating?

No. Reading and understanding code is most of the job, especially in your first weeks. A faster map just means more of your week goes to the work that’s actually yours to do.

You did it

You now have three things you didn’t have this morning: a CLAUDE.md map of the repo, one feature traced from its route to the database, and a habit for checking that you really understood it. A few things that trip people up, and the fix for each:

  • If the tour reads too vague, ask about one directory at a time.
  • If you trusted a trace you never verified, always run the last step before you rely on it.
  • If the repo is enormous, scope Claude Code to one subfolder.

Next, when you open your first pull request, reading a review report is the skill you’ll want right after.