name: large-codebase-workflow description: Best practices for using Claude Code with large, multi-part codebases

Large Codebase Workflow Guide

Core Principle

Context is your scarcest resource. Success = divide & conquer + parallel processing + persistent memory.

Project Infrastructure Setup

project/
├── CLAUDE.md                 # Global instructions (<10k words)
├── .claudeignore             # Exclude node_modules, dist, etc.
├── .claude/
│   ├── rules/                # Modular rule files
│   │   ├── backend.md
│   │   ├── frontend.md
│   │   └── testing.md
│   ├── skills/               # Reusable workflows
│   ├── agents/               # Custom subagents
│   └── commands/             # Custom slash commands

CLAUDE.md Rules

Only include what Claude can't infer from code
Monorepo: split 47k → 9k words = major performance gain
Each rule: "Would removing this cause mistakes?" No → delete it

Codemap Strategy: Reduce Session Startup Cost

Problem: Every new session, Claude explores codebase → wastes 50%+ context. Solution: Pre-generate codemaps, Claude reads md files instead of exploring.

Recommended Structure

.claude/
├── CLAUDE.md              # Concise instructions
└── codemaps/              # Pre-generated code maps
    ├── architecture.md    # Overall architecture
    ├── api-endpoints.md   # API listing
    ├── components.md      # Component relationships
    └── data-flow.md       # Data flow diagram

Example: architecture.md

# Architecture Overview

## Entry Points
- `src/index.ts` → App bootstrap
- `src/api/routes.ts` → All API routes

## Core Modules
| Module | Path | Purpose |
|--------|------|---------|
| Auth | `src/auth/` | JWT + session management |
| API | `src/api/` | REST endpoints |
| DB | `src/db/` | Prisma + migrations |

## Key Files (Read These First)
- `src/types/index.ts` → All shared types
- `src/config.ts` → Environment config
- `src/utils/` → Shared utilities

## Common Patterns
- All API handlers in `src/api/handlers/`
- Middleware chain: auth → validate → handler
- Error format: `{ error: string, code: number }`

Auto-Generate Codemap (One-Time)

claude -p "Analyze this codebase and create a comprehensive codemap.
Output to .claude/codemaps/architecture.md. Include:
- Entry points
- Module responsibilities
- Key files to read first
- Data flow
- Common patterns"

Reference in CLAUDE.md

# CLAUDE.md

## Codebase Quick Start
Read these BEFORE exploring:
@.claude/codemaps/architecture.md
@.claude/codemaps/api-endpoints.md

## Commands
- `pnpm dev` - Start dev server
- `pnpm test` - Run tests

Result

New session: read 2-5k tokens (md files)
Without codemap: explore 50k+ tokens
10x context savings

Keep Codemaps Updated

# After major refactors, regenerate
claude -p "Update .claude/codemaps/architecture.md based on current codebase structure"

Session Strategy: One Goal Per Session

# Wrong: Multiple unrelated tasks in one session
# Right: Clear goal, then /clear between tasks

claude  # "Migrate auth middleware to v2"
/clear
claude  # "Add rate limiting to API"

Key Commands

Command	When to Use
`/clear`	Between tasks (mandatory)
`/compact`	At 70% context capacity
`--continue`	Resume last session
`--resume`	Pick from history

Workflow: Explore → Plan → Code → Commit

1. EXPLORE (Plan Mode)

"read /src/auth and understand session handling"

Read-only, no code changes

2. PLAN

"I want to add OAuth. What files need to change? Create a detailed plan."

Output to SPEC.md or plan.md

3. IMPLEMENT (Normal Mode)

"implement the OAuth flow from your plan. write tests, run them, fix failures."

Always provide verification: tests, screenshots, expected output

4. COMMIT

"commit with descriptive message and open a PR"

Subagent Strategy (Key for Large Projects)

Why Subagents

Each has independent context window
Won't pollute main session
Can run 7 in parallel

Usage Patterns

# Investigation
"use subagents to investigate how authentication handles token refresh"

# Parallel review
"use subagents to run security-scanner, style-checker, and test-coverage simultaneously"

# Verification
"use a subagent to review this code for edge cases"

Built-in Subagent Types

Agent	Purpose	Access
Explore	Code search, understanding	Read-only
Plan	Architecture design	Read-only
security-reviewer	Security audit	Read, Grep, Glob
code-reviewer	Code review	Read, Grep, Glob

Parallel Development with Git Worktrees

# Create independent worktrees
git worktree add ../project-auth feature/auth
git worktree add ../project-api feature/api

# Run separate Claude sessions in each
# Session A: Refactor auth
# Session B: Build API
# Session C: Write tests

Writer/Reviewer Pattern

Session A writes code
Session B reviews with clean context (avoids self-bias)

Batch Processing & Automation

# Batch migrate files
for file in $(cat files.txt); do
  claude -p "Migrate $file from React to Vue. Return OK or FAIL." \
    --allowedTools "Edit,Bash(git commit:*)"
done

# CI integration
claude -p "Analyze this PR for security issues" --output-format json

Anti-Patterns to Avoid

Anti-Pattern	Symptom	Solution
Re-explore every session	50% context gone on startup	Pre-generate codemaps
Kitchen sink session	N unrelated tasks in one session	`/clear` between tasks
Repeated corrections	3+ corrections still wrong	`/clear` + better initial prompt
CLAUDE.md overload	Claude ignores your rules	Keep <10k words, use skills
Infinite exploration	"investigate" reads 100 files	Use subagent for exploration
Trust without verify	Code looks right but has bugs	Always provide tests/verification
Long session exhaustion	Context full, Claude "forgets"	Document & Clear method

Quick Reference

# Start new task
/clear

# Explore codebase (use subagent to save context)
"use subagents to investigate [X]"

# Complex task
Plan Mode → output plan.md → /clear → execute

# Context management
/compact "Focus on API changes"  # At 70%
/clear                           # Between tasks

# Resume previous session (preserve context)
claude --continue                # Resume last session
claude --resume                  # Pick from history

# Document & Clear (for long tasks)
"Output current progress to progress.md"
/clear
"Read progress.md and continue from where we left off"

# Parallel work
git worktree + multiple claude sessions

# Generate/update codemap
claude -p "Create codemap for this project → .claude/codemaps/"

Context Budget Rule of Thumb

Action	Token Cost	Recommendation
Read codemap	2-5k	Always do first
Explore codebase	30-50k+	Use subagent instead
Read single file	1-10k	OK if targeted
Full investigation	50k+	Document & Clear method

Large Codebase Workflow

Description