What is CLAUDE.md?
CLAUDE.md is a plain markdown file of instructions that Claude Code reads at the start of every session. Here's where it lives, how it loads, and how long it should be.
Checked against sources on 2026-09-19
The short answer
Every Claude Code session starts with an empty memory. CLAUDE.md is how you carry instructions across sessions: a markdown file of rules and facts — how to run the tests, which conventions to follow, what not to touch — that Claude reads when a session starts.
Claude treats it as context, not as enforced configuration. If an action must never happen, Anthropic's docs point to hooks, which can block it for certain; CLAUDE.md can only ask.
Where it can live
In your project, as ./CLAUDE.md or ./.claude/CLAUDE.md, shared with your team through git. A ./CLAUDE.local.md holds personal notes and should be gitignored.
In your home folder, as ~/.claude/CLAUDE.md, for preferences that apply to every project. Organisations can also install a managed-policy CLAUDE.md in a system location.
Instructions can be split into files under .claude/rules/. A rule file with a paths field loads only when Claude works on matching files.
How it loads
CLAUDE.md files in your working folder and every parent folder load when a session starts, combined from the top of the filesystem down. Files in subfolders load later, when Claude reads files there.
A line like @docs/testing.md imports another file, and imports can nest a few levels deep. Imported files still load at launch — importing moves text into another file, it does not make it optional.
How long it should be
Anthropic recommends keeping each CLAUDE.md under about 200 lines: longer files use more context and reduce how reliably Claude follows them. Keep the facts every session needs, move step-by-step procedures into skills or path-scoped rules, and remove rules that contradict each other — Claude may resolve a contradiction arbitrarily.
Because the file is sent at the start of every session, every line you add is paid for again and again. That makes it the cheapest place to cut context: a line removed from CLAUDE.md is removed from every session after it.