CLAUDE.md

CLAUDE.md is the project-level memory file Claude Code auto-loads at the start of a session: human-authored directives, conventions, and commands that steer the agent as advisory context rather than enforced configuration.

How it works

CLAUDE.md is a markdown file a team commits to a repository, and Claude Code reads it into the model's context at the start of every session, so its contents are present without anyone pasting them in again. CLAUDE.md itself comes in a scope hierarchy: a user-level file carries personal preferences across projects, a project-level file carries the conventions that belong to one repository and travels with it for everyone, and an organization can layer a policy file above both. It holds human-authored material, the directives, conventions, commands, and pointers a person decides the agent should always have, which is what separates it from agent-written memory that the tool accumulates on its own. The load-bearing fact is how it acts on the model: it is read as context the model attends to, not as configuration the runtime enforces, so the model is steered by it rather than bound by it. Everything in the file competes for the same context budget as the task, so a file that grows without curation taxes every session that loads it.

Why it matters

The temptation is to treat CLAUDE.md as configuration, a place to write the rules that must hold, but it is context, and context is followed by default, not guaranteed. That distinction decides where a rule belongs: a rule whose violation is costly and that can be checked mechanically, like blocking a committed secret or a push straight to main, belongs in a deterministic gate that enforces it, while CLAUDE.md is the right home for judgment, scope, and the pointers that tell the agent where the enforced rules and the deeper context live. Treating the file as enforcement is how teams get surprised when the model, under a long or conflicting context, does the thing the file told it not to. The cost runs the other way too, because every instruction in the file is read into the context budget on every session, so a CLAUDE.md that tries to legislate everything both crowds the window and dilutes the few rules that actually matter, which is why the discipline is to keep it short, current, and pointed at enforcement rather than substituting for it.

In practice

A team writes into CLAUDE.md that work always starts on a branch, never on the main line. That instruction is followed almost always, because the model reads it every session, but almost is the problem: the one session where a long context crowds it out is the session that commits to the main branch anyway. So the rule that must hold is moved into a gate that blocks the action outright, and CLAUDE.md keeps the lighter guidance, the conventions and the pointer to where the hard rules live, where being advisory is good enough.

Practical considerations

CLAUDE.md sits in a scope hierarchy, and what loads when is not uniform: the files in the directory tree above the working directory, the project, user, and any organization-policy file, load in full at session start, and imported files load then too, while a CLAUDE.md in a subdirectory loads only when the agent reads files there, so where a rule lives changes how reliably and how early the model sees it. It is human-maintained by design, which is both its strength and its upkeep, because unlike agent-written memory that accumulates on its own a CLAUDE.md only improves if a person curates it, and a stale directive in it misleads exactly as confidently as a fresh one. Pointers earn their place here, since rather than inlining a long standard the file can name where that standard lives and let the agent read it when relevant, which keeps the always-loaded portion small. The recurring failure is bloat, because adding a line is cheap and removing one takes judgment, so a file that is never pruned slowly becomes a wall of low-signal instruction the model reads past. The review cadence that works is the same as for code: revisit it when the conventions it encodes change, and delete what is no longer true rather than appending around it.

Defined by Ready Solutions AI