Introduction
# CLAUDE.md Optimization Guide
Write CLAUDE.md files that maximize Claude's adherence and performance.
## Core Principle: Less Is More
Long CLAUDE.md = Claude ignores half of it. Critical rules get lost in noise.
**For each line ask:** "Would removing this cause Claude to make mistakes?" - If no → delete it - If Claude already does it correctly → delete it or convert to hook
## What to Include
### Essential (High Value)
| Section | Example | |---------|---------| | Project context | "Next.js e-commerce app with Stripe" (1 line) | | Build/test commands | `npm run test`, `pnpm build` | | Critical gotchas | "Never modify auth.ts directly" | | Non-obvious conventions | "Use `vi` for state, not `useState`" | | Domain terminology | "PO = Purchase Order, not Product Owner" |
### Include Only If Non-Standard
- Branch naming (if not `feature/`, `fix/`) - Commit format (if not conventional commits) - File boundaries (sensitive files to avoid)
### Do NOT Include
- Things Claude already knows (general coding practices) - Obvious patterns (detectable from existing code) - Lengthy explanations (be terse) - Aspirational rules (only real problems you've hit)
## Structure
```markdown # Project Name
One-line description.
## Commands - Test: `npm test` - Build: `npm run build` - Lint: `npm run lint`
## Code Style - [Only non-obvious conventions]
## Architecture - [Brief, only if complex]
## IMPORTANT - [Critical warnings - use sparingly] ```
## Formatting Rules
- **Bullet points** over paragraphs - **Markdown headings** to separate modules (prevents instruction bleed) - **Specific** over vague: "2-space indent" not "format properly" - **IMPORTANT/YOU MUST** for critical rules (use sparingly or loses effect)
## File Placement
| Location | Scope | |----------|-------| | `~/.claude/CLAUDE.md` | All sessions (user prefs) | | `./CLAUDE.md` | Project root (share via git) | | `./subdir/CLAUDE.md` | Loaded when working in subdir | | `.claude/rules/*.md` | Auto-loaded as project memory |
## Optimization Checklist
Before finalizing: - [ ] Under 50 lines? (ideal target) - [ ] Every line solves a real problem you've encountered? - [ ] No redundancy with other CLAUDE.md locations? - [ ] No instructions Claude follows by default? - [ ] Tested by observing if Claude's behavior changes?
## Maintenance
- Run `/init` as starting point, then prune aggressively - Every few weeks: "Review this CLAUDE.md and suggest removals" - When Claude misbehaves: add specific rule - When Claude ignores rules: file too long, prune other content
## Anti-Patterns
| Don't | Why | |-------|-----| | 200+ line CLAUDE.md | Gets ignored | | "Write clean code" | Claude knows this | | Duplicate rules across files | Wastes tokens, conflicts | | Theoretical concerns | Only add for real problems | | Long prose explanations | Use bullet points |
## Example: Minimal Effective CLAUDE.md
```markdown # MyApp
React Native app with Expo. Backend is Supabase.
## Commands - `pnpm test` - run tests - `pnpm ios` - run iOS simulator
## Style - Prefer Zustand over Context - Use `clsx` for conditional classes
## IMPORTANT - NEVER commit .env files - Auth logic lives in src/lib/auth.ts only ```
~15 lines. Covers what Claude can't infer. Nothing more.