Reading a codebase with Claude — patterns that actually work

You can build a working mental model of an unfamiliar codebase in about two hours with Claude instead of two weeks — but only if you ask in the right order: architecture first, then one critical path end to end, then the gaps. Pasting files in and asking "what does this do?" is what wastes the tool.

This is the day-one workflow we run on AI transformation engagements, where we're usually reading someone else's system before we're allowed to change it — inherited monoliths, half-finished integrations, and the custom builds we're asked to take over.

By Uwa Ujam, founder of Autore — we design and ship AI transformation systems for ambitious teams across London and the UK.

Reading a codebase with Claude starts with architecture, not grep

Most people open Claude, paste a file, and ask "what does this do?". That's backwards. You want the map before the streets.

We start every codebase engagement the same way: ask Claude to infer the architecture from the project structure alone. No code yet. Just the directory tree, package.json or requirements.txt, and any top-level config files. The prompt is direct:

Given this project structure, describe the architecture: what are the main subsystems, how do they likely communicate, and what does the dependency graph tell you about coupling?

Claude is exceptionally good at this. It spots patterns — monorepo vs. microservices, layered vs. hexagonal, Rails-style MVC vs. Next.js app directory — and gives you the vocabulary the team actually uses. That vocabulary matters. When you ask about "the API layer" later, you want Claude to know whether that means Express routes, tRPC procedures, or Django views.

Narrow the scope, then go deep

Once you have the map, pick one critical path. Not the whole system. One user journey, one API endpoint, one background job. Then walk it with Claude in sequence.

The workflow:

1. Identify the entry point. Ask Claude where a specific action starts. "Where does a user login request enter the system?" Claude will point you to the route or controller.
2. Trace dependencies in order. Paste that file. Ask what it calls next. Paste that file. Repeat until you hit the edge (database, external API, file system).
3. Catalogue side effects. As you go, ask Claude to flag side effects: what gets written, what gets queued, what gets cached. Side effects are where bugs hide.

This is faster than reading linearly because you're following causality, not alphabetical order. You build intuition for how data moves, which is what you actually need to change things safely.

Where prompt structure makes 10x the difference

Claude's context window is large, but structure still matters. We've found three patterns that consistently improve output:

One file, one question. Don't paste three files and ask a vague question. Paste one file and ask something specific: "What invariants does this function assume about its inputs?" or "What would break if this cache miss rate doubled?" Specificity forces Claude to read closely.

Provide the schema. If you're reading database-heavy code, paste the schema first. Migrations, Prisma files, SQLAlchemy models — whatever defines the shape of the data. Then when you paste application code, Claude won't hallucinate relationships or column names.

Ask for gaps. After Claude explains a module, ask: "What's missing from this code that would matter in production?" Claude will flag missing error handling, absent logging, unvalidated inputs, or unclear rollback behaviour. It won't catch everything, but it catches more than skimming will.

What Claude misses (and how we catch it)

Claude is not a linter. It won't reliably catch:

• Performance footguns. N+1 queries, accidental O(n²) loops, missing indexes. You still need to profile.
• Concurrency issues. Race conditions, missing locks, improper use of async primitives. Claude can explain what the code intends to do, but it won't simulate interleaving.
• Implicit contracts. If two services communicate via a message queue and one expects a field the other doesn't send, Claude won't know unless both schemas are in context.

Our mitigation: after the initial Claude pass, we run the test suite, check the logs from the last deploy, and read any incident post-mortems. Claude gives you the what and the how. Logs and tests tell you what actually happens.

The workflow in practice

On a recent engagement, we joined a team running a Python monolith with 60k lines and no documentation. The onboarding doc said "read the code". We spent two hours with Claude:

• 20 minutes: architecture pass on the directory structure.
• 60 minutes: traced three critical paths (signup, payment, webhook delivery) from entry point to side effect.
• 40 minutes: flagged gaps in error handling and asked Claude to explain the retry logic in the background worker.

By end of day one, we'd shipped a small fix to a webhook race condition the team had been seeing intermittently for months. Not because we were faster readers. Because Claude let us read with intent.

What this means for you

If you're using Claude to skim code, you're using 10% of the tool. If you're using it to build a queryable mental model of how the system actually works — entry points, dependencies, side effects, gaps — you'll move faster than anyone reading linearly. The codebase doesn't get simpler. Your ability to navigate it does.

Inherited a system nobody wants to touch, or planning a build that has to outlive its first engineer? Talk to us.