A CLAUDE.md is only useful if Claude follows it. The difference between a file that gets ignored and one that shapes every session comes down to how you write it.
Prefer concrete rules over vague guidance
Vague advice gives Claude nothing to act on. "Write clean code" or "be careful with the database" sound nice but mean little. Concrete rules do the work:
## Database
- Always use the `connectDB()` helper in `lib/db.js`; never open a raw connection.
- Comment bodies are output as plain text, never rendered as HTML.
## Commits
- Prefix every commit message with the ticket number, e.g. `AX-123: ...`.
Each line names a specific thing to do or avoid. That is what Claude can reliably apply.
Do not document what Claude can infer
Claude reads your code. It can see the framework, the file layout, and the obvious patterns on its own. Spelling those out just adds noise and pushes the rules that matter further down the file. Save the space for things Claude cannot guess: your team's preferences, non-obvious gotchas, and hard requirements.
Be specific and point at examples
When a rule has a canonical example in the codebase, say so. "Follow the pattern in app/api/articles/route.js" is stronger than describing the pattern in prose. Pointing at real files removes ambiguity.
Keep it tidy
Use clear headings so related rules group together. Short, direct sentences beat long paragraphs. The goal is a file Claude can scan and apply without hunting for the point. Write it the way you would brief a sharp new teammate: concrete, specific, and free of filler.
Comments
Be the first to comment.