Large Codebases

The bigger a codebase gets, the more your approach to Claude Code has to change. Let's look at strategies for working efficiently in projects made up of tens of thousands of lines and hundreds of files.

The challenges of a large codebase

Unlike small projects, large codebases bring:

1. Context limits — you can't read every file at once
2. Navigation cost — it takes time just to find the relevant files
3. Unintended impact — a change can affect places you didn't expect
4. Consistency — patterns have to stay consistent across hundreds of files

Core strategy 1: use CLAUDE.md as a map

The larger the project, the more CLAUDE.md matters. Give Claude the key information up front so it doesn't have to explore the codebase every time:

# Project structure

## Core directories
- src/domain/    — business logic (core)
- src/api/       — Express routers
- src/infra/     — DB and external service adapters
- src/shared/    — shared utilities

## Never modify these files
- src/infra/database/migrations/ (auto-generated)
- src/shared/generated/ (code generation output)

## Architecture patterns
- Clean architecture (domain → application → infrastructure)
- Dependency direction: inward only (infra → app → domain)
- Error handling: use src/shared/errors/AppError.ts

## Main entry points
- Adding a new feature: start from src/domain/[feature-name]/
- New API: src/api/routes/[feature-name].routes.ts

Core strategy 2: narrow the scope

Specify a concrete scope instead of making sweeping requests:

# Bad (searches the entire codebase)
> Find the performance problems

# Good (scoped)
> Find N+1 query problems in the src/domain/order/ directory

# Better (specific file)
> Find what can be optimized in the queries in
  src/domain/order/order.repository.ts

Core strategy 3: explore in stages

When trying to understand an unfamiliar large codebase:

# Step 1: map the overall structure
> Explain this project's overall directory structure.
  Summarize the role of each core module.

# Step 2: understand a specific domain
> Explain how the src/payment/ module works,
  focusing on the main classes and the data flow.

# Step 3: the concrete task
> Add refund limit validation to the PaymentService.processRefund() method.

Core strategy 4: lean on git

Track the scope of changes with git:

# Snapshot before you start
git add . && git commit -m "chore: snapshot before starting work"

# Work with Claude Code
claude "Refactor the entire Order module"

# Check the scope of changes
git diff --stat        # list of changed files
git diff               # the actual changes

# Recover if you find unintended changes
git checkout src/config/  # restore a specific directory

Modernizing legacy code

An incremental approach

Don't rewrite legacy code all at once — go step by step:

# Step 1: understand
> Analyze src/legacy/order-processor.js.
  Explain what this code does and what patterns it uses.

# Step 2: tests first
> First write tests that preserve the current behavior.
  (Establishing a safety net before refactoring)

# Step 3: incremental modernization
> Upgrade the ES5 syntax to ES2022.
  Don't change behavior — modernize syntax only.

# Step 4: improve the patterns
> Convert the callback hell to async/await.
  Verify the tests still pass as you go.

Adding types (JavaScript → TypeScript)

> Convert src/services/cart.js to TypeScript.
  Minimize any types and infer accurate ones.
  Don't change the existing behavior.

Requesting codebase analysis

Architecture analysis

> Draw an architecture diagram of this codebase in Mermaid format.
  Show the dependencies between the main modules.

> Find modules with circular dependencies.
  Suggest how to resolve them.

Code quality analysis

> Find files with heavy code duplication (code smells).
  List the top 5 files in refactoring priority order.

> Find the 10 most complex functions in this project.
  Sort them by complexity.

Security audit

> Find places in this codebase that might have SQL injection vulnerabilities.
  Check every file that uses raw queries.

> Check for hardcoded secrets that should be environment variables.
  Look for API keys, passwords, tokens, and the like.

Large-scale refactoring strategies

Project-wide renaming

> Rename "customerId" to "clientId" across the whole project.
  Include the DB schema, type definitions, APIs, and tests.
  But exclude files that talk to external APIs (src/integrations/).

Applying pattern consistency

> Review every router in the src/api/ directory.
  Find the ones where error handling isn't uniform and
  align them with the pattern in src/api/users/users.router.ts.

Dependency upgrades

> Check package.json for deprecated packages.
  Suggest replacements and lay out a migration plan.

Efficient working habits

Use images

For UI work, provide a screenshot. Claude Code understands images:

> Implement the dashboard layout like this screenshot

The checklist pattern

Breaking complex work into a checklist keeps Claude from missing steps:

> Auth module refactor:
  - [ ] Verify the existing tests pass
  - [ ] Convert from session-based to JWT tokens
  - [ ] Update the middleware
  - [ ] Add tests
  - [ ] Write a migration guide

Provide the acceptance criteria up front

> Optimize the getUserById function.
  Success criteria: all existing tests pass + 50% faster response time

Using subagents

Handle complex, large-scale work in parallel with subagents:

> Refactor the following three modules independently:
  1. src/payment/ — clean up the payment logic
  2. src/notification/ — improve the notification system
  3. src/reporting/ — optimize the reporting module

  They don't depend on each other, so work on them in parallel.

A CLAUDE.md template for large projects

# [Project name]

## Quick reference
- Adding a new feature: see [path]
- Bug fixes: see [path]
- DB changes: running migrations is mandatory

## Prohibited
- Do not edit /src/generated/ directly
- Do not modify /config/production.*
- Do not hardcode external API keys in code

## Code rules
- [Rule 1]
- [Rule 2]

## Running tests
- Unit: npm run test:unit
- Integration: npm run test:integration
- All: npm test

## Pre-deploy checklist
- [ ] Tests pass
- [ ] Type check passes
- [ ] Lint passes
- [ ] Confirm migration files are included