Large Codebase Workflow

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

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

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

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

Sources

• Anthropic Best Practices
• Claude Code Docs
• Subagents Guide