What a CLAUDE.md file is
A CLAUDE.md file is a plain-text Markdown file at the root of your project that an AI coding agent reads at the start of a session. It's the agent's project memory: the facts it needs to work correctly without you re-explaining them every time.
Because agents are stateless and their context window is finite, this file is how you make a project's conventions and decisions survive between sessions.
What to put in it
Include the things you'd tell a new senior engineer on day one: a short architecture overview, the conventions you enforce, the key decisions and their rationale, and the hard constraints ("never call the payments API directly", "all dates are UTC").
Point to where things live rather than pasting everything. The goal is high signal per token, not a second copy of the codebase.
What to leave out
Leave out anything the agent can read directly from the code, anything that changes constantly, and long generated content. Each of those wastes context budget and pushes the important facts out of the window.
If a section is mostly noise, it actively hurts — the agent spends attention on it instead of the constraint that actually matters.
Keep it current or it backfires
A CLAUDE.md that's three months out of date is dangerous: the agent will confidently follow rules that no longer apply. Stale memory produces wrong work faster than no memory.
Capture decisions when they happen and review the file like code in pull requests. Better still, automate updates so it refreshes without anyone remembering to do it.
CLAUDE.md and other agents
The same idea works across tools — Cursor, Cline, and others read a project context file under different names. The principle is identical: durable, curated memory beats a bigger prompt.
Standardize on one source of truth so every agent and teammate reads the same facts.