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)

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

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

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.