CLAUDE.md is a text file in your repository with the project rules that a coding agent like Claude Code reads at the start of every session. AGENTS.md plays the same role in many other tools. It holds what the code does not say: conventions, useful commands and what not to touch. It is usually loaded in full every time, so keep it short.
A question from the app. Pick an answer.
Your instructions file says "run the tests before finishing." What does that get you?
It is guidance: the agent can skip it. That is why you still check for results.
They are different things. The file says how to work; permissions say which actions are allowed.
If the tool reads that file, it steers the work. It helps a lot, but it does not replace checking the result.
What a coding agent cannot guess by reading the files. A convention: "amounts are stored in cents, as whole numbers; never with decimals". A boundary: "the e-invoicing folder belongs to another team: do not edit it". A command that is not obvious, like the one that builds the app for testing.
What does not belong: things the agent sees on its own (which libraries the project uses is already in its files), long manuals and rules for a task done once a month. And never keys or passwords: the file usually lives in the repo, and anyone with access can read it.
The file enters the context window before you type your first request, and it stays there all session. With example numbers: a 400 line CLAUDE.md can be around 5,000 tokens that travel with every session, used or not. And among so many rules, the important ones carry less weight.
A useful test for each line: if you delete it, would the agent get something wrong? If not, cut it. Long instructions for a one off task, like shipping a new release, usually fit better in a skill, which loads only when needed.
What the file says guides the agent, but does not bind it. In a long session, with lots of text on top, it can miss a rule it followed at the start. Writing it in capital letters or repeating it three times does not make it automatic.
If something must always happen, do not make it depend on the agent's memory: many tools let you set up scripts that run on their own when an event happens (some call them hooks) and permissions that block actions. And what it really did shows up in the diff, not in the rules file.
"I write it once and I am done." If you change a command and not the file, the agent keeps using the old one. "Every tool reads the same file." No: which one each reads depends on the tool and its settings. If your team uses several, make sure there are not two versions that contradict each other: AGENTS.md shows how to share just one.