How to Use Claude Code on an Existing Large Codebase

Claude Code on an existing codebase is not the same as starting fresh. Drop it into a 100,000-line repo with no configuration and you get technically correct code that ignores your conventions, your dependencies, and your architecture.

The setup work takes under an hour. CLAUDE.md, targeted file inclusion, and bounded task sizing change everything about the quality of what comes back. This guide shows you exactly what to do.

Key Takeaways

• CLAUDE.md is essential: Without it, Claude Code has no knowledge of your conventions, approved libraries, or architectural rules.
• Targeted file inclusion wins: Point Claude Code at the specific service or module relevant to the task, not the entire repo.
• Start with bounded tasks: Bug fixes and test generation reveal how well Claude Code understands your codebase before you trust it with structural changes.
• Context management is active: You will regularly decide which files to include, when to start fresh sessions, and how to structure tasks.
• Legacy code is a valid first use: Feed Claude Code a poorly documented module and ask it to explain what it does.
• Review is non-negotiable: Claude Code does not know your codebase as well as your senior engineers. Always review generated changes before merging.

AI App Development

Your Business. Powered by AI

We build AI-driven apps that don’t just solve problems—they transform how people experience your product.

Let's talk

Why Large Codebases Require a Different Approach

Without deliberate configuration, Claude Code generates code that is technically correct but architecturally wrong on an existing codebase. The fix is not capability. It is configuration.

A 200K token context window sounds large. A 200,000-line codebase exceeds it comfortably. Claude Code works with whatever subset it can see.

• Context limits are real: Claude Code cannot hold a large repo in context and will work from whatever files are visible in the session.
• Wrong conventions by default: Without CLAUDE.md, Claude Code may use the wrong logger, wrong ORM method, or wrong error handling pattern for your stack.
• Greenfield vs existing codebase: On a new project, Claude Code shapes conventions as it builds. On an existing project, it must learn and follow conventions already baked into hundreds of decisions.
• Team consistency matters: If every developer runs sessions without a shared CLAUDE.md, each session makes different convention choices and the codebase drifts faster than before.
• The fix is configuration: Claude Code is fully capable on large codebases. The setup work is what unlocks that capability.

For teams rolling this out at scale, the guide to enterprise Claude Code adoption covers the full organisational setup, including team rollout and governance.

How to Write a CLAUDE.md for an Existing Project

A CLAUDE.md for an existing codebase tells Claude Code what already exists: your stack, your conventions, and what it must never do. The "must never do" section is the most important part.

If you want to go deeper on structuring your project for Claude Code beyond the CLAUDE.md, that guide covers folder structure, file naming, and the project organisation patterns that produce the best results.

• Tech stack with exact versions: Write "Next.js 14 App Router with TypeScript" not "Next.js." Write "Prisma ORM with PostgreSQL" not just "PostgreSQL."
• Approved and forbidden libraries: List what is approved and explicitly name what is forbidden. This prevents Claude Code from introducing new dependencies.
• Naming and structural conventions: Document your component naming pattern, file naming pattern, and folder structure rules so generated code fits without manual cleanup.
• Error handling and logging patterns: Specify which logger utility to use and how errors should be handled. This is where most convention drift originates.
• The "must never do" section: Include explicit prohibitions. Examples: "never add a new npm dependency without asking," "never use console.log," "never modify database schema files directly."
• Testing expectations: Specify your testing framework and minimum coverage expectations so generated tests match your project's standards.

CLAUDE.md is a living document. Assign ownership to a lead developer and update it every time a new convention gap surfaces in a Claude Code session.

How to Manage Context So Claude Code Stays Accurate

For the full set of context management strategies for large codebases, that guide covers the technical controls, including file exclusion patterns and session planning.

Context management on a large codebase is an active skill. The targeted inclusion principle is the foundation: always start by telling Claude Code exactly which files are relevant.

• Targeted inclusion at session start: Tell Claude Code which directory or module is in scope. "I am working on the authentication module in /src/auth" is better than "I am working on our app."
• Use @file references explicitly: Reference specific files directly in your session so Claude Code reads them rather than inferring what might be relevant.
• Session boundaries per task: Start a new session for each distinct task. Carrying context from a bug fix into a feature build reduces accuracy.
• --continue vs fresh session: Use --continue when iterating on the same task with still-relevant context. Start fresh when the task changes or when answers seem confused.
• Chunk large refactors: Break multi-file tasks into a sequence of bounded sessions. "Update the data model first" then "update the service layer" then "update the API routes."

Developers who manage context deliberately get consistent, accurate output. Those who let sessions drift get the generic answers that make teams lose confidence in the tool.

What Task Types Give the Best Results on Existing Code?

Start with verifiable tasks, move to bounded feature work, and hold off on architectural changes until you have established Claude Code's accuracy on your specific stack.

The best first tasks are ones where you can confirm correctness quickly. That confirmation builds the baseline you need before trusting Claude Code with higher-stakes work.

• Best starting tasks: Bug fixes with a clear reproduction case, test generation for untested functions, inline documentation and JSDoc generation, and explaining what a poorly documented module does.
• High-value mid-level tasks: Refactoring a specific function to match a new pattern, adding a well-defined feature to an existing service, generating migration scripts for schema changes.
• Tasks requiring more oversight: Cross-module refactors touching multiple service boundaries, performance optimisation on critical paths, and security-adjacent changes like auth or permissions.
• Tasks to defer: Architectural changes, database migration runs, and anything that modifies production config. Wait until you have a track record on your codebase.
• The progression principle: Complete five small, verified tasks successfully before moving to complex ones. This gives you a real sample of how well Claude Code understands your conventions.

For an existing codebase with significant technical debt, legacy code refactoring with Claude Code covers the specific approach for modernising code without breaking behaviour.

What Are the Common Mistakes When Using Claude Code on Existing Code?

Most teams that abandon Claude Code on existing codebases do so after a frustrating first week caused by avoidable setup mistakes. These are the five failure modes.

Each mistake below has the same root cause: treating Claude Code like a greenfield tool when it is operating in a context that already has rules.

• Loading the entire repo: Sessions that load every file are slow, expensive, and less accurate than targeted sessions. They hit context limits faster and return generic answers.
• No CLAUDE.md: Without one, every developer session makes different implicit convention choices. Within a week, the codebase has more inconsistency than before Claude Code arrived.
• Starting with a complex task: The first session should be something verifiable. A test generation task or well-defined bug fix gives you a baseline before trusting Claude Code with structural changes.
• Merging without review: AI-generated code on an existing codebase can be technically correct and architecturally wrong. A correct function that uses the wrong abstraction or misses a required side effect still ships a problem.
• Treating output as final: Claude Code produces a first draft. It is almost always worth a follow-up prompt: "Is this the most idiomatic way to do this in our stack?" or "What edge cases am I missing?"

Conclusion

Claude Code on a large existing codebase is a configuration problem, not a capability problem. The tool can handle the scale.

Write your CLAUDE.md today, before your next session. Cover your stack, your most important convention, and one "must never do" rule. Scope your sessions, start with bounded tasks, and review everything. Teams that build this habit get real output from the first week.

AI App Development

Your Business. Powered by AI

We build AI-driven apps that don’t just solve problems—they transform how people experience your product.

Let's talk

Need Claude Code Running on Your Codebase — Without the Guesswork?

Getting Claude Code installed is the easy part. Getting it to produce output that fits your conventions, respects your patterns, and passes your code review is where most teams stall.

At LowCode Agency, we are a strategic product team, not a dev shop. We write the CLAUDE.md, establish the task framework, and run the first sessions on your specific stack to validate output quality before handing it to your team. AI consulting for your codebase is the fastest path from "we have Claude Code installed" to "Claude Code is producing production-ready output."

• CLAUDE.md authoring: We document your tech stack, conventions, approved libraries, and the "must never do" rules that prevent drift from the first session.
• Context management setup: We define the file inclusion patterns and session boundaries that keep Claude Code accurate across your specific codebase structure.
• Task framework design: We identify the right starting tasks for your stack and build the progression plan that builds trust before moving to complex work.
• First session validation: We run and review the first set of bounded tasks on your codebase so you have a documented accuracy baseline before rollout.
• Team onboarding: We walk your development team through the session workflow, the review process, and the escalation points so every developer uses Claude Code consistently.
• Code review integration: We integrate Claude Code output into your existing PR and code review workflow rather than creating a parallel process.
• Ongoing refinement: We update the CLAUDE.md and task framework as your codebase evolves so Claude Code accuracy improves over time, not degrades.

We have built 350+ products for clients including Coca-Cola, American Express, and Medtronic.

If you want Claude Code producing accurate, convention-compliant output on your existing codebase from day one, talk to our team.