DEV Community

Carlos Oliva Pascual
Carlos Oliva Pascual

Posted on • Originally published at stacknotice.com

Bringing Claude Code Into an Existing Codebase (2026)

#claude #productivity #workflow #webdev

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
Enter fullscreen mode Exit fullscreen mode

/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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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."
Enter fullscreen mode Exit fullscreen mode 
"Look at an existing component in /components/ui/ and write a new
one that follows the same patterns. Show me before saving."
Enter fullscreen mode Exit fullscreen mode

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."
Enter fullscreen mode Exit fullscreen mode

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."
Enter fullscreen mode Exit fullscreen mode

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."
Enter fullscreen mode Exit fullscreen mode 
"Some files use CSS modules, some use Tailwind. We've standardized
on Tailwind for all new code. Ignore the CSS module files as references."
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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."
Enter fullscreen mode Exit fullscreen mode

Scope the reading:

"Read only the exported functions from /lib/actions/posts.ts —
just signatures, not implementations."
Enter fullscreen mode Exit fullscreen mode

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:

  1. Claude proposes changes
  2. You review the diff
  3. 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

  1. Run /init — get the baseline CLAUDE.md
  2. Edit CLAUDE.md — architecture, current state, do-not-modify, vocabulary
  3. Run 3 read-only tasks — verify Claude's understanding is accurate
  4. Pick one small, low-risk task — review the output carefully
  5. Update CLAUDE.md from what Claude got wrong
  6. 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

Top comments (0)