A project instruction file lands in the agent's context on every task. That cuts both ways. Everything in it is read again and again, so an extra line costs you on every run, not once.
Why a project needs an instruction file
Without one, the agent guesses afresh each time: how to run the tests, which code style the project uses, which commands are dangerous. Some answers it finds in the code. Some it invents, and not always correctly.
The file settles this once. You write the project context down a single time and the agent reads it before starting, instead of you re-explaining the same things in every task.
What does not belong in the file
The commonest filler is generic advice about code quality: "write clean code," "follow best practices," "be careful." Lines like these change nothing in the model's behavior. There is no checkable criterion in them, so the agent cannot tell what to do differently.
The second mistake is retelling what the code already shows. If the project has one formatting convention and the linter config enforces it, describing it in prose adds nothing. The agent sees the config and applies it.
The third is a long file full of decision history. Why the team picked a framework two years ago matters to a person and almost never to an agent working on today's task. That text takes up room the real rules need.
What is worth keeping in the file
Concrete, checkable instructions work. The exact command that runs the tests, not a loose "test your changes." An exact list of files and directories nobody touches without explicit permission. An exact commit format, if the project uses just one.
Exceptions to the project's usual patterns are especially valuable: places where a normal pattern is broken on purpose, and the reason. Otherwise the agent "fixes" them as mistakes. You cannot infer this from the code, so say it outright.
Record the deploy commands and the order of steps before a deploy as well: what to check, in what order, what to do when one step fails. A strict checklist beats a general description here.
A good concrete rule: "before pushing to main, run npm run lint and go vet ./..., stop and report on failure instead of trying to fix the linter yourself." You can check it. The agent either ran the commands or did not, and the result is visible at once. A vague "watch code quality" gives you nothing to check.
A structure that works
Short sections with headings beat one long block of text. When the layout is predictable, the agent finds the right piece faster. Typical sections: running things and tests, deploy, what not to do, and style, if the linter does not already cover it.
Order matters as much as content. Put the rules that must never be broken near the top of the file. In the middle, among minor notes, they get lost.
How to check the agent is reading it
The test is simple. Add one concrete rule that was not there before, a commit format requirement, say. Give the agent a routine task and see whether the result follows it.
If the rule is broken, there are usually two reasons. Either the wording is too vague, or the file is so long that the rule sank among less important lines. Both are fixed by cutting text, not by adding more.
Keeping the file from going stale
An instruction file ages along with the project, and a stale rule is sometimes worse than none: it confidently points the agent in a direction that stopped working a while ago.
A good habit is to change the file in the same commit that changes the process it describes. If the deploy command changes, the update to the instruction file goes into that same pull request, not a later one.
The short version
CLAUDE.md works when it holds concrete, checkable rules instead of wishes. Cut what the code already shows and the decision history. Keep commands, boundaries, and deliberate exceptions to patterns. An agent follows a short file with precise rules. A long file full of general words it simply does not notice.