CLAUDE.md
CLAUDE.md is a Markdown file of standing instructions that Claude Code loads at the start of every session, which makes its contents part of every request the session sends.
It holds what the agent should know without being told: build and test commands, conventions, architectural decisions, things to leave alone. Claude Code reads it from the project root (./CLAUDE.md or ./.claude/CLAUDE.md), from ~/.claude/CLAUDE.md for personal defaults and from an organization-wide managed file, and concatenates everything it finds rather than letting one file override another. Files in subdirectories load later, when Claude reads something in that directory.
The cost is easy to underestimate. The file enters the session as a message after the system prompt, and since every request re-sends the whole context, each line is paid for on every turn: cheaply while the prompt cache holds, at full price or above whenever the cache has to be rebuilt. A section that matters once a month is billed on every request of every session.
Anthropic's documentation recommends keeping each CLAUDE.md under 200 lines (as of September 2026), noting that longer files consume more context and reduce adherence. Splitting the file with @path imports helps organization but not size, because imported files load at launch too. What does shrink it is moving workflow-specific instructions into skills or path-scoped rules, which load only when relevant, and putting maintainer notes in block-level HTML comments, which Claude Code strips before the text reaches the model.
Two behaviours are worth knowing. The project-root file survives /compact, because Claude Code re-reads it from disk afterwards. And an edit made mid-session does not apply until the next /clear, /compact or restart, since the file is read once when the session starts. /context lists the memory files that actually loaded.