Claude Code with Large Codebases: Strategies That Work
Claude Code handles large codebases well when you feed it the right context — not all of it. The 200K token window is large, but a 100K-line codebase still exceeds it. The developers who get consistent results use CLAUDE.md as a codebase index, feed targeted file subsets per task, and decompose large changes across multiple sessions.
Sections: CLAUDE.md structure, file targeting, the /compact workflow, task decomposition, and where Claude Code reliably delivers versus where it struggles.
The core problem with large codebases
Claude Code's context window holds roughly 150,000 words — large, but a real production codebase of 100K lines often exceeds that three to five times.
The goal is giving Claude the right subset of context per task. Do this well and Claude behaves as if it knows the codebase. Skip it and Claude invents plausible-looking but wrong function names, misses your conventions, and generates code that does not fit existing patterns.
CLAUDE.md as your codebase index
CLAUDE.md is read at the start of every session. Most developers use it only for basic instructions. On large codebases it needs to function as a map of the codebase itself.
What to include:
- Directory structure with a one-line purpose for each directory
- A "read these files first" list for each domain — auth, API, database, UI, etc.
- Architecture decisions and the reasoning behind them
- Patterns Claude must follow (where queries go, how actions are structured)
- Things Claude must never do, specific to your project
Here is a concrete example entry:
## Directory guide
- `src/auth/` — Clerk authentication. Read: middleware.ts, lib/auth.ts
- `src/api/` — tRPC routers. Read: server/routers/index.ts for all routes
- `src/db/` — Drizzle ORM. Read: schema.ts for all table definitions
- `src/components/ui/` — Shadcn components. Don't modify these directly.
## Patterns
- All DB queries go through `lib/db/client.ts`
- Server actions use the pattern in `app/actions/example.ts`
- Never use `any` as a TypeScript type
The "never do" section is equally important. Every codebase has footguns — deprecated utilities, components that must not be modified directly, superseded patterns. Document them explicitly and Claude follows them consistently.
Targeted context feeding
1. Use @file references. List files directly at the start: "Before starting, read: src/auth/middleware.ts, lib/auth.ts, src/db/schema.ts." Claude reads those and nothing else.
2. Let Claude explore on a cold start. Tell Claude the task and let it use ls and cat to find what matters. Goal-directed exploration beats loading everything.
3. State what not to read. "Fix the bug in api/routes/users.ts. Read only that file and its direct imports." This prevents loading adjacent files and preserves context.
Task decomposition for large changes
A large change spanning auth, database schema, API routes, and frontend cannot be completed well in a single session. Context fills before the work is done, and Claude loses track of early decisions. Explicit session decomposition fixes this:
Session 1: Exploration only. Ask Claude to understand the relevant parts of the codebase and output a written plan — what files will be touched, what pattern each change follows, what the dependencies are. No code changes. Save the plan to CLAUDE.md or a scratch file.
Session 2: Implement one module. Start fresh with the plan. Implement one self-contained piece — the database migration, or the API route, or the frontend component — and end the session with tests passing.
Session 3: Implement the next module. Start fresh again. Paste back key decisions from Session 1 and reference Session 2's output. Continue.
Sessions that try everything in one pass routinely fail at the 70% mark when context fills and coherence drops.
The /compact workflow
/compact compresses the session history into a summary, freeing context while preserving key decisions and current state.
When to use it: Run /cost periodically. Above 50% consider compacting. Above 70% it is urgent — coherence degrades fast.
How to use it:
- Run
/compact - Review the summary — it will miss some details
- Paste back critical context the summary omitted: "Also remember: we decided to use server actions not API routes, and
usertable now hasorg_id" - Continue the session
When to start fresh instead: Same feature or bug — compact. Different feature or different part of the codebase — new session.
File targeting for specific task types
Different task types call for different context strategies:
Bug fixes: Read only the file throwing the error and its direct imports. The bug is almost always local. Loading the wider module dilutes context without adding information.
Feature additions: Read the closest existing feature and the relevant schema. One existing route file plus the router index. One existing migration plus schema.ts. Do not read the whole API layer.
Refactoring: Read the module you are refactoring. Do not read anything else. Claude needs depth on the target module, not breadth across the codebase.
Cross-cutting changes: A change that genuinely touches many parts of the codebase is a decomposition problem, not a context problem. Break it into per-module sessions.
What Claude Code does well on large codebases
- Pattern recognition from examples. Show Claude one or two examples of how something is done in your codebase and it applies that pattern consistently. This is where "read the existing feature first" pays off.
- Tracking in-session changes. Claude reliably knows what it has changed within the current session and can reason about self-introduced bugs.
- Iterative test fixing. Running tests and fixing failures in a loop is one of Claude Code's strongest behaviors. It will iterate until the suite passes.
- Following CLAUDE.md constraints. When constraints are written clearly, Claude Code follows them consistently — the "never modify Shadcn components" rule, the "all queries through client.ts" pattern, the TypeScript
anyprohibition.
What Claude Code struggles with
- Cross-cutting changes across 50+ files in one session. This is a hard limit. The solution is session decomposition, not a better prompt.
- Remembering decisions from previous sessions. Claude starts each session fresh. Write down decisions in CLAUDE.md so they persist.
- Implicit conventions not documented anywhere. If your codebase has an unwritten convention — a naming pattern, an unspoken rule about module interaction — Claude will not infer it reliably. Document it.
Frequently asked questions
How do I stop Claude Code from reading files I don't want it to read?
State it explicitly: "Do not read anything outside of src/payments/. If you need information from another module, ask me." Claude Code respects these constraints. You can also add "do not read" rules to CLAUDE.md for persistent enforcement.
What is the best CLAUDE.md structure for a large codebase?
Three sections: a directory guide mapping each directory to its purpose and the 2–3 key files to read; a patterns section describing how common tasks are done; and a never-do section for project-specific footguns. Keep it under 500 lines — CLAUDE.md that is too long gets treated as noise.
When should I use /compact versus starting a new session?
/compact when you are mid-task and context is filling. New session when the next task is genuinely different. New sessions are cleaner; compact preserves in-session state.
How do I handle a bug that could be anywhere in a large codebase?
Start with the stack trace or failing test. Ask Claude to "read only the file and line in this error, then trace the call chain one level at a time." Each step is targeted and context stays manageable.
Can Claude Code handle a 500K-line codebase?
Yes. The constraint is not codebase size — it is how much you load in a single session. A 500K-line codebase worked on in targeted, decomposed sessions behaves the same as a 50K-line one.
Take It Further
Power Prompts 300: Claude Code Productivity Patterns — Section 5 covers Large Codebase Workflows: the CLAUDE.md templates for 8 common stack configurations, the multi-session task decomposition pattern, and the context management system that keeps Claude focused even on codebases with 500K+ lines.
30-day money-back guarantee. Instant download.