Shattered Vales Studio Inc.

Using AI to Learn an Unfamiliar Codebase

Joining a project means learning thousands of files you didn't write. An AI coding assistant that can read the whole repository is a patient guide who never minds the same question twice. This guide shows how to use Claude Code to explore safely, ask questions that get useful answers, and check that what it tells you is true.

Step 1: Explore in Read-Only Mode

While you're learning, you don't want anything changed. Start Claude Code in the repository and switch to plan mode by pressing Shift+Tab until the mode indicator shows it. In plan mode Claude reads and searches but doesn't edit files. If you're new to Claude Code, set it up first with Claude Code & GitHub CLI Setup. 

cd ~/Source/<repo>
claude
# then press Shift+Tab to switch to plan mode

You can also simply start your prompt with "Don't change any files." Read any command it proposes before approving it.

Step 2: Get the Map First

Start broad. A good overview tells you where everything is before you dive into details: 

Give me an overview of this repository for a new developer:
- what it does and who uses it
- the main folders and what each contains
- the entry points (where execution starts)
- how to build, run, and test it
- the key external services or packages it depends on
Cite file paths for each point. Where the README disagrees with the
code, tell me.

Asking for file paths matters: it lets you check each claim, and it makes the model ground its answers in files it has actually read rather than in what projects like this usually look like.

Step 3: Trace a Feature End to End

The fastest way to understand a system is to follow one real action all the way through. Pick something concrete from the product:

Game example:

Trace what happens when a player picks up an item, from the input
event to the item being saved in the save file. List each file and
method in order, with file:line references, and one sentence on what
each step does.

SaaS example:

Trace an HTTP request to GET /tenants/{tenantId}/invoices from the
route to the database query and back. Where is authentication checked,
where is the tenant filter applied, and where are results cached?
Include file:line references.

Then open each file it lists in your editor and read the code yourself, following the path. The AI gives you the route; reading the code is how you learn it.

Step 4: Ask About the Code in Front of You

Ask one focused question at a time, and run /clear when you move to an unrelated area. Short, focused conversations are cheaper and give more accurate answers.

Step 5: Find Where a Change Should Go

When you pick up your first issue, use the AI to plan before writing anything: 

Read issue #42 (gh issue view 42). Don't write code yet.
1. Which files and methods would need to change?
2. Is there existing code I should reuse or follow as a pattern?
3. Which tests cover this area today, and what new tests are needed?
4. What could this change break?
Cite file paths for each answer.

Check the plan with your onboarding buddy or lead before starting. It's the quickest way to catch a misunderstanding of the issue or the codebase.

Step 6: Use History to Learn Why

Code shows what the system does; history shows why. Claude Code can run Git commands for you and summarize the results: 

Look at the git history of src/Billing/InvoiceCalculator.cs. Summarize
the important changes and the reasons given in commit messages and
linked pull requests. Who has worked on it most?

To run these commands yourself, see Reading History & Finding Bugs.

Step 7: Verify What You're Told

An AI can describe code it hasn't read, mix up two similar functions, or repeat what an out-of-date comment says. Treat every explanation as a lead to check, not a fact:

  1. Open the cited files and confirm the code says what you were told. If there's no file reference, ask for one.
  2. Run it. Set a breakpoint or add a temporary log line and watch the path you were shown actually execute.
  3. Ask a teammate about anything important, especially business rules. The AI only knows the code, not the decisions behind it.
  4. Write down what you learn, and if the README or architecture document was missing it, improve them in a pull request. The next new hire will thank you.