Install
openclaw skills install phy-large-codebase-workflowPhy Large Codebase Workflow
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 |
Sources
Author
Canlah AI — Run performance marketing without breaking your brand.
- GitHub: github.com/PHY041
- All Skills: clawhub.ai/PHY041