Short answer: CLAUDE.md is a plain markdown file of instructions that Claude Code loads at the start of every session [1]. It works when it is short and specific. Past about 200 lines, Anthropic's own docs say Claude follows it less reliably [1].
Where CLAUDE.md lives
Claude Code looks for it in several places and loads all of them together, broadest first [1]:
- Your user file,
~/.claude/CLAUDE.md, for preferences across every project. - The project file,
./CLAUDE.md, shared with your team through source control. - A local file,
./CLAUDE.local.md, for personal notes you don't commit. - A managed policy file, set by your company's admin.
Run /init to have Claude draft one from your codebase, and /memory to see which files loaded [1].
Why Claude ignores it
Two reasons, both in Anthropic's docs:
- It's context, not configuration. CLAUDE.md is delivered as a message after the system prompt, so there's no guarantee of strict compliance, especially for vague or conflicting lines [1].
- It got too long. Anthropic's target is under 200 lines per file; longer files "consume more context and reduce adherence" [1]. Their best-practices page puts it bluntly: if a line is getting lost, the file needs to be shorter [2].
Adding "IMPORTANT" in capitals doesn't fix it. If a rule truly can't be broken, Anthropic recommends a hook instead [2].
What to put in, and what to leave out
Put in what you'd otherwise re-explain [1]: build and test commands, conventions, decisions that aren't written down anywhere else, and anything you've had to correct twice [2].
Leave out what Claude can find by reading the repo [2], long procedures (make those a skill), and anything about your business that isn't about this codebase.
That last point is where most setups go wrong. Your pricing, your customers and your brand voice don't belong in one repo's CLAUDE.md. They belong in one company folder that every Claude session reads, in Code, in Cowork and in chat. Then CLAUDE.md can stay short: one line pointing at the folder, plus the rules for this repo. Our own index file is 39 lines.
Do it yourself, or have it done
Chet sets up that company folder (we call it Start) from your own documents, grades your Claude setup, and fixes what breaks. $99 a month, cancel anytime.
Maximize Claude with Chet: https://www.coworkers.global/get-chet?utm_source=blog&utm_medium=internal&utm_campaign=chet&utm_content=what-to-put-in-claude-md-cta
FAQ
Is CLAUDE.md the same as Claude's memory? No. CLAUDE.md is what you write. Claude Code also keeps an auto memory it writes itself, and loads the first 200 lines or 25KB of its index at the start of each session [1].
Does a long CLAUDE.md cost more? It's loaded in full every session regardless of length [1], so yes: every line takes context in every session.
Can one CLAUDE.md import another file? Yes, with @path/to/file, up to four hops deep [1].
Sources
- Claude Code docs, how Claude remembers your project: https://code.claude.com/docs/en/memory
- Claude Code docs, best practices: https://code.claude.com/docs/en/best-practices
Regards,
Charles Stack
Founder, Coworkers.Global
Coworkers.Global is not affiliated with Anthropic. Claude is a trademark of Anthropic, PBC.