I've read a lot of bad CLAUDE.md files. Most of them have the same problem: they're a wishlist, not a brief. Page after page of "please write clean code" and "follow best practices" — instructions so generic they change nothing. If your CLAUDE.md could belong to any project on earth, it's dead weight.
A CLAUDE.md file is the note Claude Code reads at the start of every session in your repo. It loads automatically. It's persistent context. And here's the part people miss: every word in it costs tokens on every single request. So the question isn't "what could I tell Claude?" It's "what does Claude get wrong without this, that I'm tired of correcting?"
That reframe changes everything. Let me show you what to put in your CLAUDE.md file.
Start with the stuff Claude can't guess
Claude can read your code. It cannot read your mind. The highest-value lines in any CLAUDE.md are the facts that aren't visible in the files themselves.
## Project
This is a Next.js 14 app using the App Router. We deploy to Cloudflare Pages.
Package manager is pnpm — never npm or yarn.
## Commands
- `pnpm dev` — local server on :3000
- `pnpm test` — runs Vitest, must pass before any commit
- `pnpm typecheck` — run this after editing any .ts file
That command block alone saves you a dozen corrections a week. Without it, Claude will cheerfully run npm test and watch it fail, or skip the typecheck you always run. With it, the agent does the right thing unprompted.
Notice I said "never npm or yarn." Specifics beat vibes. "Use pnpm" is a suggestion. "Never npm or yarn" is a rule, and Claude treats it like one.
Encode the conventions you keep re-explaining
Think back over your last week of sessions. What did you correct more than once? Those corrections are your CLAUDE.md.
## Conventions
- Components go in src/components, one folder per component.
- We use Tailwind. No CSS modules, no styled-components.
- API routes return { data } or { error }, never bare values.
- Dates are always stored as UTC ISO strings.
Each of those is a real decision your codebase already made. Writing it down once means you stop typing it every session. That's the whole game — move the recurring correction out of your head and into the file.
A word on tone instructions
You can shape how Claude works, not just what it knows:
## Working style
- Make only the change requested. Don't refactor adjacent code unless asked.
- For small choices (variable names, file location), just pick one and note it.
Don't stop to ask.
- After editing, run typecheck and tests before telling me you're done.
That middle line is gold if you're on a recent Claude model. The newer ones are more deliberate by default — they'll pause and ask about tiny decisions a lot. A short "just pick one" instruction claws that time back without making the agent reckless on the stuff that matters.
What to leave out
Now the deletions, which matter just as much.
Cut anything generic. "Write secure, maintainable code" does nothing. Claude already tries to. You're spending tokens to restate the default.
Cut anything in the code. Don't paste your whole package.json or list every dependency. Claude can open the file. Describe what's not obvious from reading — like why you chose a library, or which one to prefer when two could work.
Cut the novel. I've seen 600-line CLAUDE.md files. By line 200, the signal-to-noise ratio is so bad that the important rules get buried. A tight 40-line file that Claude actually follows beats a sprawling one it half-ignores. Be ruthless. If a line hasn't earned its place by preventing a real mistake, delete it.
Where the file goes
Drop CLAUDE.md in your repo root and Claude Code finds it automatically. You can also nest one in a subdirectory — say frontend/CLAUDE.md — and Claude layers it on top when you're working in that folder. Handy for monorepos where the backend and frontend have genuinely different rules.
There's also a global one in your home config directory that applies to every project. I keep mine almost empty: just a couple of personal preferences that hold true everywhere. Project-specific knowledge belongs in the project, not your global file.
A template you can steal
# CLAUDE.md
## Project
[One or two sentences: what this is, the stack, where it deploys.]
## Commands
- [dev command]
- [test command — note if it must pass before commits]
- [any check you always run]
## Conventions
- [a decision that isn't obvious from the code]
- [a library preference]
- [a pattern you enforce]
## Working style
- [how thorough/conservative to be]
- [when to ask vs. when to decide]
Fill that in, then live with it for a week. When you catch yourself correcting Claude on something for the third time, that's a missing line — add it. When you notice a line that never actually mattered, delete it.
A CLAUDE.md file isn't a document you write once. It's a thing you tune. The good ones are short, specific, and earned one correction at a time. Start small. Let it grow only where it has to.