How I use Claude Code to understand an unfamiliar codebase in 30 minutes

You've just been handed a codebase. No documentation. No original author to ask. Just folders, files, and a deadline.

Most developers spend days slowly building up a mental model. I've cut that to 30 minutes using Claude Code — and here's the exact workflow I follow.

Why this matters

The hardest part of working with an unfamiliar codebase isn't writing code. It's understanding the existing code — what it does, why it's structured that way, where the dangerous parts are, and what you can safely change.

Traditional approaches: read every file top to bottom, run it and see what breaks, ask a teammate who might not remember.

The Claude Code approach: structured exploration with an AI that reads everything and synthesizes it instantly.

Step 1: Orient with the entry points

Before asking Claude anything, run:

# Find the main entry points
find . -name 'index.js' -o -name 'main.py' -o -name 'app.rb' | grep -v node_modules
cat package.json | grep -E '"main"|"scripts"'

Then open Claude Code and say:

Read the main entry point file and give me:
1. What this application does in one sentence
2. The top 5 most important files I should understand
3. Any architectural patterns I should know about (MVC, event-driven, etc.)

This gives you a map before you start exploring.

Step 2: Trace the critical paths

Every codebase has 2-3 paths that matter most — the ones where bugs are most expensive and changes are most common.

For a web app, that's usually: request comes in → auth check → business logic → database → response.

Ask Claude:

Trace the path from when an HTTP request arrives to when the response is sent.
Show me each file and function involved in order.
Highlight anywhere error handling is missing or incomplete.

This single prompt has saved me from 3 production incidents in the last 6 months.

Step 3: Find the dangerous code

Every codebase has places where one wrong change causes catastrophic failures. Database migrations, payment processing, auth tokens, background job scheduling.

Ask Claude:

Look through this codebase and identify:
1. Code that touches money, payments, or billing
2. Code that runs as a background job or scheduled task
3. Code with no tests
4. Any TODOs or FIXMEs that suggest known issues

Mark these files in your editor. Never touch them in your first PR.

Step 4: Build a CLAUDE.md file as you explore

As you learn things, have Claude document them:

Based on what we've discovered so far, write a CLAUDE.md file that explains:
- The architecture of this system
- The most important conventions to follow
- Things I should never do in this codebase
- The safest places to make changes

This becomes your persistent context for every future session in this codebase. Claude reads it at the start of every session, so you never have to re-explain the architecture.

Step 5: Write a change and ask for a risk assessment

Before making your first real change, describe what you want to do and ask:

I need to add a new API endpoint that accepts a user ID and returns their last 5 orders.
Based on the codebase, tell me:
1. Which existing files I should modify
2. What patterns I should follow (error handling, auth, validation)
3. What could go wrong with this change
4. What tests I should write

You're not asking Claude to write the code yet — you're asking for a plan and risk assessment first.

The rate limit problem with this workflow

Here's what nobody tells you: this workflow is token-hungry.

When Claude reads 30 files, traces multiple execution paths, and builds CLAUDE.md — you can burn through your daily rate limit before lunch. Especially on large codebases.

I hit this problem constantly when onboarding to a new client's codebase. Claude would cut me off mid-exploration, and I'd lose the thread I was following.

The fix: I use SimplyLouie as my Claude Code API endpoint. It's $2/month and gives me access to the same claude-3-5-sonnet-20241022 model through a proxy endpoint I can point Claude Code at:

export ANTHROPIC_BASE_URL=https://simplylouie.com/api
export ANTHROPIC_API_KEY=your_key_here

No rate limit anxiety. I can run the full 30-minute exploration workflow without watching the clock.

The full workflow at a glance

Day 1 in a new codebase:
├── 1. Find entry points (5 min)
│   └── Ask: "What does this do and what are the top 5 files?"
├── 2. Trace critical paths (10 min)
│   └── Ask: "Show me the request→response flow"
├── 3. Find dangerous code (5 min)
│   └── Ask: "Where's the money/auth/background job code?"
├── 4. Build CLAUDE.md (5 min)
│   └── Ask: "Document what we've learned"
└── 5. Plan first change (5 min)
    └── Ask: "What's the risk of adding X?"

Total: 30 minutes. You now understand more about this codebase than most people who've worked in it for weeks.

Why this works

Claude Code doesn't just read files — it synthesizes across them. It can follow a function call through 5 files simultaneously, notice when a pattern breaks in one place, and connect documentation in a README to actual behavior in the code.

The key is asking structured questions that force synthesis, not just file reading. "What does this do?" is a weak prompt. "Trace the path from request to response and flag missing error handling" is a strong one.

Once you internalize this workflow, onboarding to a new codebase stops being a week-long process and becomes a morning one.

---

If you're hitting rate limits during codebase exploration sessions, SimplyLouie is $2/month — same Claude model, no throttling. 7-day free trial.