Claude Code for Large Codebases (2026)

The Problem

In codebases exceeding 100,000 lines, Claude Code spends 40-60% of session tokens on code discovery: reading files, searching for patterns, and building mental models of the architecture. A typical exploration sequence in a large monorepo – 8-12 Read calls, 5-8 Grep searches, 3-5 Glob patterns – consumes 50,000-120,000 tokens before any productive work begins. At Sonnet 4.6 rates ($3/$15 per MTok), this discovery tax costs $0.15-$1.80 per session, or $15-$180 per month for a developer averaging 5 sessions per day.

Quick Wins (Under 5 Minutes)

  1. Create an architecture map in CLAUDE.md – a 20-line summary of directory structure and key files saves 10-20 Read calls per session.
  2. Use .claudeignore – exclude node_modules/, dist/, build/, .next/, and vendored code from search results.
  3. Pre-scope tasks – start prompts with “In src/auth/…” instead of open-ended requests that trigger full-codebase exploration.
  4. Run /compact after discovery – once Claude has mapped the code, compact the context to retain findings while freeing 60-80% of the window.
  5. Use directory-level CLAUDE.md files – provide local context in each major directory so Claude does not need to infer structure from exploration.

Deep Optimization Strategies

Strategy 1: Architecture Map in CLAUDE.md

A concise architecture map eliminates the costliest part of large codebase sessions – initial exploration:

# CLAUDE.md
## Architecture Overview (monorepo, ~250K LoC)
### Directory Structure
- `packages/api/` -- Express REST API (TypeScript), entry: src/index.ts
- `packages/web/` -- Next.js frontend, entry: src/app/layout.tsx
- `packages/shared/` -- Shared types and utilities
- `packages/worker/` -- Background job processor (BullMQ)
- `packages/db/` -- Prisma schema and migrations
### Key Files
- `packages/api/src/routes/` -- All API endpoints (one file per resource)
- `packages/api/src/middleware/auth.ts` -- JWT authentication
- `packages/db/prisma/schema.prisma` -- Database schema (source of truth)
- `packages/shared/src/types/` -- Shared TypeScript interfaces
### Data Flow
- Frontend -> API routes -> Service layer -> Prisma -> PostgreSQL
- Background jobs: API enqueues -> BullMQ -> Worker processes
### Build & Deploy
- `pnpm build` from root builds all packages
- `pnpm -F api dev` runs API in dev mode
- `pnpm -F web dev` runs frontend in dev mode

This ~300-token map replaces 10-15 exploration tool calls that would cost 4,000-8,000 tokens. The map pays for itself in the first 2 minutes of every session.

Savings: 3,700-7,700 tokens per session (initial exploration eliminated)

Strategy 2: Aggressive .claudeignore Configuration

Large codebases contain vast amounts of irrelevant content that pollutes search results and wastes Read tokens:

# .claudeignore
# Build artifacts
dist/
build/
.next/
out/
coverage/
# Dependencies
node_modules/
.pnpm-store/
# Generated code
*.generated.ts
*.d.ts
prisma/client/
# Large data files
*.sql.bak
fixtures/large-*.json
seed-data/
# Vendored code
vendor/
third-party/
# Lock files (enormous token sinks)
pnpm-lock.yaml
package-lock.json
yarn.lock

A pnpm-lock.yaml in a medium project can be 50,000+ lines. If Claude Code accidentally reads even a portion, that single Read call wastes 5,000-20,000 tokens. The .claudeignore file prevents this entirely.

Savings: 5,000-30,000 tokens per session (prevents accidental large-file reads)

Strategy 3: Task Scoping in Prompts

The most cost-effective strategy requires no configuration – just better prompts:

# Expensive: triggers full-codebase exploration
claude -p "Fix the authentication bug"
# Claude will: Glob for auth files (245 tokens), Read 5-8 files (3,000-6,000 tokens),
# Grep for auth patterns (245 tokens x 3), then start fixing.
# Discovery cost: ~8,000-12,000 tokens
# Cheap: pre-scoped to exact location
claude -p "In packages/api/src/middleware/auth.ts, the JWT verification
on line 42 does not check token expiration. Add an exp check that
returns 401 if the token is expired."
# Claude will: Read auth.ts (150 + ~800 tokens), make the fix (245 tokens)
# Discovery cost: ~1,200 tokens

The scoped prompt costs 85-90% less in discovery tokens. When the developer knows the location, encoding that knowledge in the prompt is the single highest-ROI optimization.

Savings: 7,000-11,000 tokens per task (pre-scoped vs. open-ended)

Strategy 4: Strategic /compact Usage

After Claude Code completes discovery and builds understanding of the relevant code, run /compact to compress the context:

# Session flow for large codebase work:
# 1. Discovery phase (expensive but necessary)
> "Understand the payment processing flow in packages/api/src/services/payment/"
# Claude reads 6 files, traces the flow. Context: ~60,000 tokens.
# 2. Compact (retain understanding, free context)
> /compact
# Context drops to ~15,000 tokens (75% reduction).
# Claude retains: file structure, key functions, data flow understanding.
# 3. Implementation phase (now cost-efficient)
> "Add retry logic to the Stripe charge function with exponential backoff, max 3 retries"
# Claude works with compressed context. Implementation cost: ~20,000 tokens.
# Total session: ~95,000 tokens instead of ~160,000 tokens without compact.

Savings: 40,000-65,000 tokens per long session (25-40% total session reduction)

Strategy 5: Subdirectory CLAUDE.md Files as Local Context

Place context where it is needed to prevent cross-codebase exploration:

# packages/api/src/services/CLAUDE.md
## Service Layer Conventions
- Each service file exports a single class
- Constructor takes dependencies (Prisma client, external clients)
- All public methods return Promise<Result<T, Error>>
- Error handling: throw typed errors from shared/errors.ts
- Logging: use the injected logger, never console.log
## Key Services
- PaymentService: Stripe integration, handles charges + refunds
- UserService: CRUD + auth token management
- NotificationService: Email (Resend) + push notifications
## Dependencies
- Prisma client from packages/db
- Types from packages/shared/src/types/

This file (~200 tokens) loads only when Claude works inside packages/api/src/services/, providing immediate local context that prevents 3-5 exploration calls to understand the service layer patterns.

Savings: 1,500-3,000 tokens per service-layer task

Strategy 6: Subagent Decomposition for Large Tasks

When a task spans multiple subsystems in a large codebase, use subagents to prevent context bloat in the parent session:

# .claude/skills/large-task-decomposition.md
## When to Use Subagents
- Task touches 3+ packages in the monorepo
- Task requires reading 10+ files
- Task involves both frontend and backend changes
## Decomposition Pattern
1. Parent agent: reads CLAUDE.md, understands task, creates subtask list
2. Subagent 1: handles backend changes (starts with fresh ~5,000 token context)
3. Subagent 2: handles frontend changes (independent context)
4. Subagent 3: handles test updates (independent context)
5. Parent agent: verifies all changes, runs integration tests

Each subagent operates with ~5,000 tokens of base overhead instead of inheriting the parent’s 80,000+ token accumulated context. For a task that would have run 50 turns in a single session (with context growing to 200K tokens), splitting into 3 subagents of 15 turns each (context staying under 60K per agent) saves 40-60% on total input tokens.

# Example: refactoring a service across the monorepo
claude --max-turns 30 -p "Refactor UserService to AccountService.
Split into subagents:
1. Backend: rename in packages/api/src/services/ and routes/
2. Frontend: update imports and components in packages/web/src/
3. Tests: update all test files
Run the full test suite after all subagents complete."

Savings: 80,000-150,000 tokens per large cross-cutting task

Strategy 7: Incremental Context Building

Instead of reading everything upfront, build context incrementally as needed:

# CLAUDE.md -- Incremental Discovery Rule
## Large Codebase Protocol
1. Start with the architecture map in this file (150 tokens)
2. Read only the ENTRY POINT file for the feature being worked on
3. Follow imports ONE level deep -- read only directly imported files
4. Do NOT read files that are not directly imported by the target
5. If more context is needed, run /compact first to free space, then read more
6. Maximum files to read per task: 8 (unless explicitly permitted to read more)

This rule prevents the common pattern where Claude Code reads 15-20 files “to understand the full picture” when only 3-5 files are relevant to the change. The 8-file limit (NASA P10 bounded loops principle) keeps discovery costs predictable.

Measuring Your Savings

# Track session costs with ccusage
npm install -g ccusage
# Compare sessions before and after optimization
ccusage --sort cost --limit 10
# Look for:
# - Reduced average session cost
# - Fewer Read/Grep calls per session (visible in conversation history)
# - Shorter time-to-first-edit (less discovery overhead)

Strategy 8: Workspace-Specific Entry Points

For monorepos, document the entry point for each workspace so Claude Code starts in the right place:

# CLAUDE.md
## Workspace Entry Points
- To work on the API: start in packages/api/, entry is src/index.ts
- To work on the frontend: start in packages/web/, entry is src/app/layout.tsx
- To work on background jobs: start in packages/worker/, entry is src/index.ts
- To modify the database: start in packages/db/, schema is prisma/schema.prisma
- To update shared types: start in packages/shared/, exports from src/index.ts
## Cross-Workspace Changes
If a task requires changes in multiple packages:
1. Identify all affected packages first (max 3 per task)
2. Complete changes in one package before moving to the next
3. Run /compact between packages to free context
4. Run `pnpm build` from root to verify cross-package compatibility

This guidance prevents the expensive pattern where Claude Code reads files across all workspaces to understand where a change belongs. With entry points documented, it goes directly to the correct package.

Savings: 3,000-8,000 tokens per cross-workspace task (eliminates wrong-package exploration)

Cost Impact Summary

Technique Token Savings per Session Monthly Savings (Solo Dev)
Architecture map in CLAUDE.md 3,700-7,700 $1.11-$2.31
.claudeignore for large files 5,000-30,000 $1.50-$9.00
Task scoping in prompts 7,000-11,000 $2.10-$3.30
Strategic /compact usage 40,000-65,000 $12.00-$19.50
Subdirectory CLAUDE.md files 1,500-3,000 $0.45-$0.90
Combined 57,200-116,700/session $17.16-$35.01

Monthly estimates: 20 working days, 5 sessions/day, Sonnet 4.6 rates ($3/$15 per MTok). These are large-codebase figures; smaller projects will see proportionally lower absolute savings but similar percentage reductions.

Monorepo-Specific Optimization: Package Boundaries

Large monorepos benefit from strict package boundary enforcement in CLAUDE.md:

# CLAUDE.md -- Package Boundary Rules
## Monorepo Boundaries
- Each package has its own CLAUDE.md with local conventions
- NEVER read files from packages not directly related to the current task
- If a task requires cross-package changes, split into subtasks per package
- Use the shared types package (packages/shared/) for cross-package interfaces
- Run package-specific tests first: `pnpm -F <package> test`
- Only run full test suite (`pnpm test`) after all package-specific tests pass

Without these boundaries, Claude Code in a 10-package monorepo may read files from 6-8 packages to understand a change that only affects 2 packages. Each unnecessary package exploration adds 5,000-15,000 tokens. With boundary enforcement, exploration stays within the relevant 2 packages, saving 20,000-75,000 tokens on cross-cutting tasks.

The combination of architecture maps, .claudeignore, task scoping, /compact, and subdirectory context files transforms large codebase sessions from $0.80-$2.00 per session to $0.30-$0.80 per session – a 60-70% reduction that compounds across every developer on the team and every session they run.

Find the right skill → Browse 155+ skills in our Skill Finder.

Estimate tokens → Calculate your usage with our Token Estimator.

Try it: Estimate your monthly spend with our Cost Calculator.

See Also