How to Write a CLAUDE.md That Actually Works
Your CLAUDE.md is the difference between Claude Code that guesses and Claude Code that knows your project. Here's how to write one that actually improves your output: THE BASICS CLAUDE.md is a markdown file at your project root. Claude Code reads it automatically at the start of every conversation. Think of it as persistent instructions that survive session resets. WHAT TO PUT IN IT 1. Build/test commands - The exact commands to build, test, and lint your project. Claude Code will use these instead of guessing. Example: - Build: npm run build - Test: npm test -- --watch - Lint: npm run lint:fix 2. Architecture decisions - Things that aren't obvious from the code. "We use server components by default." "Auth goes through middleware, not page-level checks." "The API layer is in /apps/api, not /src/api." 3. Code style rules - Preferences Claude Code can't infer. "No barrel exports." "Use named exports, not default." "Error messages go in /lib/errors.ts, not inline." 4. What NOT to do - Negative constraints are powerful. "Never add Co-Authored-By to commits." "Don't use chore: prefix." "Don't add comments to unchanged code." WHAT NOT TO PUT IN IT - Secrets or tokens (it's committed to git) - Entire API documentation (too long, dilutes focus) - Things obvious from package.json or tsconfig THE STRUCTURE THAT WORKS Keep it under 200 lines. Start with build commands, then architecture, then style rules, then constraints. Claude Code reads the whole thing every time, so every line costs attention. LEVEL UP: NESTED CLAUDE.md You can put CLAUDE.md files in subdirectories. Claude Code reads the one closest to the file it's working on. Use this for monorepos: - /CLAUDE.md (repo-wide rules) - /apps/api/CLAUDE.md (API-specific patterns) - /apps/web/CLAUDE.md (frontend-specific patterns) THE TEST After writing your CLAUDE.md, start a fresh Claude Code session and ask it to make a small change. If it follows your conventions without being told, it's working. If it doesn't, your CLAUDE.md needs to be more specific.