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
# 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
/initas 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
# 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.
