CLAUDE.md

CLAUDE.md is a markdown file you put in your project root. Claude Code reads it at the start of every session, every time.

That is the entire mechanism, and it is the highest-leverage configuration in the product — because everything else in Claude Code is conditional, and this is not.

What belongs in it

• Coding standards and conventions the code itself does not make obvious
• Architecture decisions and the reasoning behind them
• Preferred libraries, and ones to avoid
• How to run the tests, the build, the linter
• Review checklists
• Anything you would otherwise repeat at the start of every session

What does not belong in it

• Anything the code already says. Directory structure and function signatures are readable.
• Long reference material. It costs context on every request. Put procedures in a Skill, which loads only when relevant.
• Secrets. It is a file in your repository.

That first point is the most common failure: a CLAUDE.md that has grown into a project encyclopedia makes every session more expensive and, past a certain length, less obeyed.

Where it sits relative to everything else

Mechanism	When it applies
CLAUDE.md	Always, every session
Auto memory	Always, but written by Claude rather than you
Skills	When the task matches
Hooks	On specific events
MCP	When a tool is called

It travels across surfaces

Because every Claude Code surface runs the same engine, one CLAUDE.md applies in the terminal, VS Code, JetBrains, the desktop app and the web. Checked into the repository, it is also the cheapest way to give a whole team the same baseline.