CLAUDE.md
Most people either ignore CLAUDE.md entirely or stuff it with garbage.
This single file shapes every interaction Claude has with your codebase.
"Bad CLAUDE.md looks like documentation for a new hire.
Good CLAUDE.md looks like notes you'd leave yourself if you knew you'd have amnesia tomorrow."
What is CLAUDE.md?
CLAUDE.md is the first thing Claude reads in every session. It's automatic
onboarding material—persistent context that carries across conversations. Write it in
Markdown; Claude handles it well.
The Rules
- Keep it short: ~150-200 lines max. The system prompt already uses ~50 tokens. Every line here consumes context on every message.
- Be specific to YOUR project: Don't explain what a "components" folder is. Claude knows. Tell it what's unique about yours.
- Tell it WHY: "Use strict mode because we had production bugs from type coercion" beats "Use strict mode."
- Update constantly: Press
#to add instructions on the fly. Good CLAUDE.md evolves.
Good vs Bad Examples
Bad
This project uses React for the frontend. Components are in the components folder. We use TypeScript. The API is in the api folder.
Good
Legacy API uses snake_case (don't change). New endpoints use camelCase. Auth tokens expire in 1hr—check expiry before API calls. Never use any in TypeScript.
The bad example tells Claude things it can figure out by reading the code. The good example tells Claude things it can't infer—conventions, gotchas, and context that would otherwise require asking a senior developer.
What to Include
- Project-specific conventions that differ from defaults
- Known gotchas and why they exist
- Where to find examples of common patterns
- What NOT to do (and why)
- Testing requirements and how to run them
Think: "If I had amnesia tomorrow and only this file to guide me, what would I need to know to not break things?"
Key Takeaways
- CLAUDE.md is read on every message—keep it concise
- Tell Claude what's unique, not what's obvious
- Include WHY, not just WHAT
- Update it constantly as you discover new gotchas