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 /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

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