What Is a CLAUDE.md File? (And Why Your Agent Needs One)
A CLAUDE.md file is a plain text file in your project that Claude Code reads automatically at the start of every session. It holds standing instructions the agent follows without being reminded: how to behave, which files to read first, and what it must never do without asking. You write it once, and it applies forever.
That last property is the whole point. An AI agent keeps nothing between sessions. When a conversation ends, the model forgets everything you told it. CLAUDE.md is the one instruction set that survives the reset, because the tool loads it every time before the agent does anything else. Instructions you put anywhere else get forgotten; instructions you put here become permanent.
This piece answers the definitional question: what the file is, what goes in it, and how it differs from the AGENTS.md file you may also have seen. If you already know the basics and want the annotated behavioral pattern we run in production, read our companion piece on the CLAUDE.md job contract instead.
What goes inside a CLAUDE.md?
Inside a CLAUDE.md goes anything you would otherwise have to re-explain to a new hire every morning. The file we run in production is about 2 pages long and organized into 5 sections. Each one exists because leaving it out costs us a real, repeated failure.
| Section | What it sets |
|---|---|
| Identity | The agent's role and posture: an autonomous worker, not a passive assistant that waits to be asked. |
| Start protocol | The exact files to read, in order, before touching any work - so context is rebuilt the same way every session. |
| Work rules | One task at a time, log every decision, checkpoint every hour. The habits that keep autonomous work from rotting. |
| Guardrails | What the agent must never do alone: spend money, publish, message people, act under the owner's name. |
| Quality rules | The judgment layer: outcomes over activity, honest data, kill what fails a fair trial. |
Notice what is not in the table: no build commands, no code style, no directory tree. Those belong in a CLAUDE.md too if you write software, and most examples online show only that. They are useful, but they are the low-leverage half. The high-leverage half is behavioral, because behavior is what the agent otherwise has no memory of.
One rule governs the whole file: keep it short. CLAUDE.md is reread every session, and its authority comes from clarity. Ten crisp rules beat forty vague ones, and a rule you cannot imagine being broken is dead weight that dilutes the live ones. Two pages is not a limit we hit by accident. It is the size at which the agent can absorb the whole thing and still get to work.
CLAUDE.md vs AGENTS.md: which one do you need?
For most people, either name works, and you only need one. CLAUDE.md is the filename Claude Code looks for; AGENTS.md is an emerging cross-tool convention that several other agent tools read instead. They serve the identical purpose: standing instructions loaded at the start of a session. The difference is only which tool reads which name.
Pick by the tool you actually run. If your agent is Claude Code, name the file CLAUDE.md and you are done. If you use a different agent, check which filename it loads automatically and use that. If you move between tools, the pragmatic move is to keep the real content in one file and point the other at it, so you never maintain two copies that drift apart.
The content does not change with the name. Everything in the 5 sections above is tool-agnostic, because it describes how you want the agent to work, not how any particular tool is wired. That is why the file outlives model versions and vendor choices: it is a description of the job, and the job is yours. The contract works the same way an agent's second brain of plain text files does, surviving every reset because it lives on disk instead of in a conversation.
FAQ
Does Claude Code read the CLAUDE.md file automatically?
Yes. Claude Code loads the CLAUDE.md file from your project at the start of every session, before it does any work, and it does this without being asked. That automatic loading is the entire reason the file matters. Instructions written anywhere else are forgotten when the session ends; instructions in CLAUDE.md are reloaded every single time, which turns them into standing orders rather than one-off requests.
What if I use a different agent tool, not Claude Code?
Use the filename your tool loads automatically, most often AGENTS.md. The concept is identical: a plain text file of standing instructions read at the start of each session. The content transfers unchanged, because it describes how you want the agent to behave, not how any one tool works. Check your tool's documentation for the exact filename, then paste the same sections in.
How often should I edit a CLAUDE.md file?
Edit it whenever you catch yourself correcting the agent about the same thing twice. A correction typed in chat fixes one session and is forgotten overnight; the same correction added as one line in CLAUDE.md is fixed permanently. In practice the file grows fastest in the first week or two, then settles, reading like the accumulated lessons of your actual operation.
How long should a CLAUDE.md file be?
Short enough to reread quickly - ours is about 2 pages across 5 sections. Because the file is loaded every session, length works against you: a bloated file buries the rules that matter under ones that do not. Start with a start protocol and one guardrail you care about, then add a line only when a real, repeated problem justifies it.