Reading a codebase with Claude — patterns that work

Prompt structure matters more than model size

We've put Claude on dozens of codebases in the last year — Rails monoliths, Next.js apps, Python data pipelines, Elixir services. The gap between a vague "explain this repo" and a structured prompt is not 20%. It's 10x.

Here's what changes the game: asking Claude to output structured annotations, not prose summaries. We give it a schema. JSON or markdown tables. Something we can scan, diff, and build on.

Example prompt:

You are reading a codebase. For each file in /src/services, output:
- File path
- Primary responsibility (one sentence)
- External dependencies (libraries, APIs)
- Interfaces exposed (functions, classes)
- Risk score (1-5) based on complexity and external I/O

Output as a markdown table.

This forces specificity. It makes Claude commit to a view. And it gives you something you can compare across runs or hand to a teammate without a 3,000-word essay.

The day-one workflow

When we start an engagement, we don't read code linearly. We map it. Here's the sequence:

1. Directory structure first. Run tree -L 3 or equivalent, feed it to Claude, ask: "What kind of application is this? What's the likely data flow?" This primes the model with architecture, not implementation.

2. Dependency manifest. package.json, Gemfile, requirements.txt, go.mod — whatever. Ask Claude to flag anything unusual, outdated, or high-risk. We've caught unmaintained auth libraries and ancient AWS SDK versions this way.

3. Entry points. Routes, handlers, main.go, app.py. Ask Claude to trace the top 3-5 user flows from entry to database. Not every flow — the critical paths. We use the structured prompt approach here too: output a table with columns for route, controller, model, external calls.

4. Data models. Schema files, ORM definitions, Prisma, SQLAlchemy. Ask Claude to list entities, relationships, and any constraints it finds. Then ask: "What's missing that you'd expect to see?" This surfaces implicit assumptions.

5. Configuration and secrets. .env.example, config files, deploy scripts. Ask Claude to list every environment variable and flag anything that looks like it could leak or break in production. We've found hardcoded staging URLs, missing rate-limit configs, and incomplete Docker setups.

6. Tests. If they exist. Ask Claude to summarise coverage by domain. If they don't exist, ask what would be highest-risk to test first. This tells you where the team has been confident — and where they haven't.

Total time: 30-60 minutes. We walk away with a structured picture of the system, a shortlist of questions for the team, and a sense of where the landmines are.

What Claude misses

Claude is very good at reading code. It's less good at reading between code.

It doesn't catch:

• Naming inconsistencies. If user_id is sometimes userId and sometimes uid, Claude won't flag it unless you explicitly ask about naming conventions.

• Performance anti-patterns. N+1 queries, missing indexes, synchronous calls that should be async. Claude sees the code, but it doesn't simulate load. You have to prompt specifically: "Show me queries that might be N+1."

• Drift between code and docs. If the README says the app uses Redis and the code uses Memcached, Claude might not notice. Cross-reference manually.

• Dead code. Claude assumes everything is live. We use coverage reports and git blame to sanity-check what's actually running.

• Business logic bugs. Claude can explain what the code does. It can't tell you if that's what the code should do. That's still on you.

We catch most of this by running targeted follow-up prompts: "Find all database queries in /src/services. Which ones might have performance issues?" Or by pairing Claude's output with static analysis tools — ESLint, RuboCop, mypy.

What this means for you

If you're using Claude to read code, stop asking it to "explain" and start asking it to "annotate". Structure your prompts. Build a repeatable workflow. And remember: Claude is a very fast junior engineer with perfect recall and no gut instinct. Use it to build the map. But you're still the one deciding where to dig.