CLAUDE.md is a Markdown file in the root of your repository that Claude Code reads automatically at the start of every session. Think of it as an onboarding script for your codebase: it holds what the model needs to know about your project, your stack, your conventions, the commands you run. The contents are appended to your prompt. Claude does not remember your project between sessions, but it reads this file before it does anything else, which comes to the same thing in practice.
Why you want that becomes obvious once you've used Claude Code for more than a day. You open a new session, ask it to build something, and it starts exploring your codebase from scratch. It re-reads your dependencies. It guesses at your conventions. It makes assumptions about your stack that you then have to correct. Every. Single. Time.
Making one
You can bootstrap one instantly:
/initClaude will scan your codebase and generate a CLAUDE.md based on what it finds. It's a solid starting point, but you'll want to refine it.
What Goes In It
A good CLAUDE.md is short and opinionated. It answers the three questions Claude asks itself at the start of every session: What is this project? How should I write code here? What commands do I need?
Here's the structure I follow:
Stack
Tell Claude what it's working with. Framework, language version, ORM, CSS approach. Don't make it guess.
- Next.js 15, App Router
- TypeScript (strict mode)
- Tailwind CSS
- Drizzle ORMPreferences
This is where you encode your conventions. Named exports or default exports? Tabs or spaces? Server actions or API routes? Every team has opinions. Write them down.
- Use two-space indentation
- Prefer named exports
- Use server actions instead of API routes where possible
- All API routes go in app/api/Commands
Tell Claude how to run things. Dev server, tests, linting. Don't assume it knows.
- Dev server: `npm run dev`
- Run tests: `npm test`
- Lint: `npm run lint`That's it. Three sections. Keep it compact. A CLAUDE.md that's three pages long defeats the purpose, you're burning context tokens on instructions instead of actual work.
The Hierarchy
There's more than one place to put a CLAUDE.md. The file system follows a hierarchy:
Project-level (CLAUDE.md in the root of your repository): shared context about this specific project. This is the one you commit to version control. Your entire team benefits from it.
User-level (CLAUDE.md in your Claude configuration folder): personal preferences that apply across all your projects. Things like your preferred comment style, your editor conventions, how you like error messages formatted. This one stays on your machine.
The project-level file takes precedence for project-specific instructions, while user-level preferences fill in the gaps.
Three Tips That Actually Matter
Start without one. Anthropic's own recommendation, and I agree with it: begin a new project without a CLAUDE.md and pay attention to where you have to constantly course-correct the model. Those corrections are exactly what should go in the file. This keeps it lean and relevant instead of bloated with instructions Claude would've followed anyway.
Use @ references. If your project has documentation, architecture decision records, or API specs, don't paste them into CLAUDE.md. Reference them:
Refer to @docs/architecture.md for the system design.
Refer to @docs/api-spec.yaml for endpoint contracts.Claude will read those files when it needs them, keeping your CLAUDE.md compact while giving it access to deep context.
Ask Claude to save corrections to memory. When you correct Claude during a session, like "always use server actions instead of API routes", explicitly ask it to save that to its memory. Next session, it will know. This is the lowest-friction way to evolve your CLAUDE.md over time.
The Difference It Makes
The gap between a frustrating Claude Code session and a productive one is almost always a context problem. Claude is capable, but it's not psychic. Without a CLAUDE.md, every session is a cold start. With one, Claude walks in already knowing your stack, your conventions, and your commands.
It's the same principle I've talked about before with the hooks guide and Superpowers: the less time Claude spends figuring out how you work, the more time it spends doing actual work.
Start with your stack, your preferences, and your commands. Build from there as you go, and prune as often as you add, because stale memory is worse than no memory. That's all there is to it.
One caveat once the file stops being yours alone: a CLAUDE.md in a shared repo behaves differently from one on your own machine, and so does everything else under .claude/. I've written up what a repo can and cannot enforce across a team separately.