CLAUDE.md Best Practices

CLAUDE.md is the single most important file for Claude Code productivity. It's your project's instruction manual for the AI agent.

Structure

Follow this proven structure (from Anthropic's own projects):

# Project Name

One-line description of what this project does.

## Commands

pnpm dev # Start dev server
pnpm test # Run tests
pnpm lint # Lint code

## Code Style

- TypeScript strict, no `any`
- Named exports, no barrel files
- Server Components by default

## Architecture

src/app/ # Next.js App Router
src/lib/ # Utilities
src/db/ # Database

## Things That Will Bite You

- pgvector requires CREATE EXTENSION first
- ISR revalidate is in seconds, not milliseconds

What to Include

What NOT to Include

Tips

• Target under 200 lines. Every line competes for attention. Anthropic's Claude Code best practices guide emphasizes concise, pruned CLAUDE.md files — "ruthlessly prune; if Claude already does something correctly without the instruction, delete it."
• Use @path/to/file imports to reference detailed docs without bloating the main file.
• Use .claude/rules/ directory for path-scoped rules that only apply to specific directories.
• Run /init first, then edit — don't write from scratch.
• Review and prune regularly. If Claude keeps ignoring a rule, the file is probably too long.

Hierarchy

Each level adds to the previous:

1. ~/.claude/CLAUDE.md — Global (all projects)
2. your-project/CLAUDE.md — Project-level (git committed)
3. your-project/CLAUDE.local.md — Personal overrides (gitignored)
4. your-project/src/**/CLAUDE.md — Subdirectory-scoped, loaded on demand when working in that subtree

Anti-patterns

• The 500-line CLAUDE.md — Claude ignores important rules because they're buried in noise
• Auto-generated and never edited — /init output needs human curation
• Contradictory rules — Two files giving different guidance for the same behavior
• Using it for security — CLAUDE.md is advisory. Use permissions.deny in settings.json for actual restrictions.