The first thing most people do with Claude Code is explain their project. The second thing they do is explain it again in the next session, because the AI forgot. CLAUDE.md is the fix: a plain markdown file that Claude Code loads automatically at the start of every session, so your project's rules, conventions, and commands are always in context without you retyping them.
But there is a gap between "having a CLAUDE.md" and having one that actually changes Claude's behavior. Here is how the file works and how to write one that pulls its weight.
How it loads
At session start, Claude Code walks up the directory tree from where you launched it, collecting every CLAUDE.md it finds, and concatenates them into context. Files closer to your working directory are read last — which, thanks to recency, gives them the most influence. So a rule in your project's CLAUDE.md naturally outweighs a general preference in your global one.
There are a few levels, from most global to most specific:
- User —
~/.claude/CLAUDE.md. Your personal preferences across every project. - Project —
./CLAUDE.md(or./.claude/CLAUDE.md), committed to the repo and shared with your team. - Local —
./CLAUDE.local.md, for personal project notes you gitignore. - Subdirectory — a
CLAUDE.mddeeper in the tree loads lazily, only when Claude actually reads files in that directory. Handy for module-specific rules.
(Organizations can also deploy a managed policy file that always loads and can't be excluded — but for most people, the user and project files are the whole story.)
Importing other files
You do not have to cram everything into one file. An @path reference pulls another file inline:
See @README.md for the overview and @docs/architecture.md for the system design.
# Commands
@docs/dev-commands.md
Paths resolve relative to the file doing the importing, absolute paths work too, and imports can nest up to four levels deep. One gotcha: backticks disable an import, so `@example` renders as literal text — useful when you want to mention a path without expanding it.
Getting started and editing
Two commands matter:
/initanalyzes your codebase and generates a startingCLAUDE.md— build commands, conventions, structure. If one already exists, it suggests improvements instead of clobbering it./memorylists every memory file currently loaded and lets you open any of them in your editor. When Claude is ignoring a rule,/memoryis where you go to see what it actually loaded.
What actually makes it work: specificity
This is where most CLAUDE.md files fail. Vague instructions get vague compliance. The difference is stark:
| Weak | Strong |
|---|---|
| "Format code properly" | "Use 2-space indentation" |
| "Test your changes" | "Run npm test before committing" |
| "Keep files organized" | "API handlers live in src/api/handlers/" |
Claude cannot follow "use good practices" because it does not know your definition of good. It can absolutely follow "run npm test before committing." Write rules a new hire could execute without asking a follow-up question.
Keep it short
CLAUDE.md loads in full at session start — there is no truncation — so every line costs context and, past a point, dilutes adherence. A good target is under ~200 lines per file. When a file starts sprawling, that is the signal to factor it:
- Move file-type-specific rules into path-scoped rules (
.claude/rules/*.md) that load only when Claude touches matching files. - Move multi-step procedures into skills, not CLAUDE.md — the memory file is for standing rules, not runbooks.
Smaller and sharper beats comprehensive and ignored.
The mistakes to avoid
A handful of failure modes account for most "why won't it listen" moments:
- Conflicting rules across files. If your global and project files disagree, Claude picks one, and not always the one you meant. Periodically reconcile them.
- Vagueness. Covered above — it is the number-one cause of ignored instructions.
- Bloat. A 500-line file does not get followed 2.5× as well as a 200-line file; it gets followed worse.
- Procedures in the wrong place. A step-by-step deploy process belongs in a skill; CLAUDE.md should say that the process exists and where to find it.
- Assuming subdirectory files survive compaction. After a long session compacts, your root project
CLAUDE.mdpersists, but a nested subdirectory one may not reload. Put anything truly load-bearing in the root file.
The mindset
Think of CLAUDE.md less as documentation and more as configuration you write in prose. Documentation describes the project to a human who will read it once. Configuration tells a system how to behave every single time. The best CLAUDE.md files are closer to the second: short, specific, and unambiguous, so that the version of Claude Code you get on session forty is as oriented as the one you carefully briefed on session one.