Starting a new project with Claude Code is straightforward. Starting with an existing 50,000-line codebase is a different challenge entirely. The model has no idea what "our auth middleware" means, why you chose this folder structure, or that you migrated away from Redux six months ago and there are still old patterns scattered around.
The teams that get real value from Claude Code on existing projects fast are the ones who treat onboarding like documentation — not for humans, for the model.
Why Existing Codebases Are Harder
Without context, Claude writes code that compiles but doesn't fit. It suggests patterns you've moved away from, adds abstractions you already have elsewhere, or misses that a certain function has a side effect that matters.
The problems:
- Accumulated decisions not obvious from the code
- Inconsistencies between old and new modules
- Dead code that looks active
- Hidden dependencies (env vars, DB triggers, webhooks)
The /init Command
cd your-project
claude
> /init
/init reads your project structure and generates a starting CLAUDE.md. It's a foundation — generic enough to be a starting point, not complete enough to be useful on its own. Edit it.
Writing a CLAUDE.md That Actually Helps
Architecture decisions and why:
## Architecture
- Next.js App Router with server components where possible
- Server actions for all mutations — no REST endpoints (migrated Q1 2025)
- Prisma for DB access — raw SQL only in /lib/db/queries.ts
- No Redux — Zustand for global UI state, TanStack Query for server state
Current state:
## Current state
- Auth: fully migrated to Clerk (old next-auth code in /archive/old-auth — ignore it)
- Email: Resend with templates in /emails/ — do not use nodemailer (legacy)
- Background jobs: Inngest — see /inngest/ folder
Things to not touch:
## Do not modify
- /lib/generated/ — auto-generated by Prisma, overwritten on next db push
- /public/static/ — managed by marketing, not in our deploy pipeline
- /legacy/reports/ — frozen, consumed by finance integration
Common patterns:
## Patterns we use
- All server actions in /lib/actions/[domain].ts
- Error handling returns { ok: true/false } — never throw from server actions
- Loading states use Suspense, not isLoading boolean
The "do not modify" section is often the most valuable. Claude will try to be helpful and touch things it shouldn't. Explicit constraints prevent most of that.
The First Tasks: Small, High-Learning
Don't start with "refactor the auth system." Start with read-only tasks that teach Claude the codebase:
"Read the /lib/actions/ folder and describe what each action does.
Don't modify anything — just map what's there."
"Look at an existing component in /components/ui/ and write a new
one that follows the same patterns. Show me before saving."
After two or three of these, you can verify Claude understands your conventions before it touches production code.
Always Read Before Editing
Before any editing prompt, add:
"Before making any changes, read [file] and [related file].
Summarize what you find so I can verify you understand the context."
This feels slow. It isn't. It prevents the two-hour debugging session that happens when Claude refactors a file it never actually read, based entirely on what the filename suggests.
For non-obvious dependencies:
"Read src/services/OrderService.ts. What does it import?
What other files import from it? Map the dependency graph
before we make any changes."
Handling Legacy Patterns
Most existing codebases have two generations of patterns. CLAUDE.md handles most of this, but for ambiguous cases, explicit prompting helps:
"We're in /components/. Older ones use class-based React, newer ones
use function components. We only write function components. Treat
class components as legacy — don't follow their patterns."
"Some files use CSS modules, some use Tailwind. We've standardized
on Tailwind for all new code. Ignore the CSS module files as references."
The Vocabulary Problem
Every codebase has its own vocabulary. When Claude uses a term incorrectly, add it to CLAUDE.md:
## Domain vocabulary
- Order: a purchase record in the orders table (not a cart)
- Cart: temporary pre-purchase state, not persisted to DB
- Member: a User who has an active subscription
- Processing: Order status between "placed" and "fulfilled" — triggers warehouse notification
After a few weeks, your CLAUDE.md has a domain model that makes Claude significantly more accurate on business logic tasks.
Context Management
Reading ten files before making a change puts a lot of tokens in the window. Two strategies:
Read summaries, not full files:
"Read src/services/UserService.ts and give me a 5-sentence summary.
Don't show me the full implementation."
Scope the reading:
"Read only the exported functions from /lib/actions/posts.ts —
just signatures, not implementations."
Use /compact after Claude builds its understanding of the codebase, before it starts writing code.
Incremental Trust
Don't let Claude commit autonomously on day one. Start with:
- Claude proposes changes
- You review the diff
- You commit manually
After a week you'll know which task types Claude handles reliably on your specific codebase.
Updating CLAUDE.md Over Time
Every time Claude makes a mistake because it lacked context, that's a CLAUDE.md entry:
- Wrong pattern → add the right one with an example
- Touched something it shouldn't → add to "do not modify"
- Wrong term → add to vocabulary
- Missed a constraint → add to architecture
After a month, your CLAUDE.md captures institutional knowledge that survives session resets — useful for new engineers too, not just Claude.
The First Week Checklist
- Run
/init— get the baseline CLAUDE.md - Edit CLAUDE.md — architecture, current state, do-not-modify, vocabulary
- Run 3 read-only tasks — verify Claude's understanding is accurate
- Pick one small, low-risk task — review the output carefully
- Update CLAUDE.md from what Claude got wrong
- Repeat
The payoff comes after two or three weeks when Claude is writing code that fits your codebase so naturally that reviewers can't tell which parts came from a model.
Full guide at stacknotice.com/blog/claude-code-existing-codebase-guide-2026
