CLAUDE.md: where to put it, and how long should it be?
CLAUDE.md is read every session: too long, and it costs on every turn. Here’s where to put it and how to keep it short, from Claude Code’s documentation.
Where to put it
| Scope | Location |
|---|---|
| You, across all projects | ~/.claude/CLAUDE.md |
| The project, shared with the team | ./CLAUDE.md or ./.claude/CLAUDE.md |
| The project, just for you | ./CLAUDE.local.md |
| The organization (macOS) | /Library/Application Support/ClaudeCode/CLAUDE.md |
How it loads
At launch, Claude Code reads the CLAUDE.md files in the working directory and every directory above it, and concatenates them. Those in subdirectories only load when Claude works there. A file over 4 MiB is skipped.
The @path/to/file syntax imports another file, up to four hops deep. But imports enter the context at startup: they organize, they don’t lighten.
Keeping it short
- Aim for under 200 lines per file, as Anthropic recommends.
- Move long procedures into skills: they only load when needed.
- Keep the essentials: conventions, build and test commands, known pitfalls.
Frequently asked questions
Does CLAUDE.md count toward my limits?
It’s part of the context sent to the model, so it weighs on every turn, even though it’s often re-read from the cache at a reduced price.
Does CLAUDE.md survive compaction?
Yes: after compaction, Claude Code reloads it.