A CLAUDE.md file is a markdown file that Claude Code reads automatically at the start of every session. It holds your project’s permanent context: conventions, commands, architecture notes and rules, so you do not have to repeat them in every prompt. You put it at your repository root, and Claude loads it as instructions before it reads a single line of your code.
Why is CLAUDE.md so important?
Most of the friction with an AI assistant comes from re-explaining the same things: how to run the tests, which patterns to follow, what to never touch. CLAUDE.md is where you write that once. Because Claude reads it on every session, a good CLAUDE.md quietly improves every answer you get, without you lifting a finger.
It is the single highest-leverage file in a Claude Code setup. A few precise lines often do more than a long, clever prompt.
Where do you put it?
CLAUDE.md works at three levels, and they stack:
| Location | Scope |
|---|---|
| Repository root | The whole project (commit it, the team shares it) |
| A subdirectory | Loaded when Claude works in that folder |
~/.claude/CLAUDE.md | Your personal preferences, across all projects |
What should go in a good CLAUDE.md?
Keep it short and concrete. The best ones cover:
- Commands that matter: build, test, lint, run.
- Conventions: code style, naming, the patterns you actually use.
- Architecture notes: where things live, what depends on what.
- What to avoid: the traps, the files not to touch, the anti-patterns.
- Examples over rules: show one good example rather than describing it.
A long, vague CLAUDE.md is worse than a short, precise one. If it grows into a wall of text, trim it.
How do you create one?
Run /init in your project. Claude scans the codebase and drafts a CLAUDE.md for you, which you then edit down to what genuinely matters. From there, every time you correct Claude on the same thing twice, add a line.
The takeaway
CLAUDE.md is how you give Claude Code a memory of your project. Write it once, keep it short and concrete, and every session starts already knowing your conventions, your commands and your traps.
Want to go from a good CLAUDE.md to a full workflow, hooks, MCP, subagents and team setup? The Harness Engineering course takes you there. The first module is free, no card needed.