A project instruction file lands in an agent's context on every task. That is both its strength and its weakness: everything written there gets read again and again, so the cost of extra lines is not a one-time thing, it is paid on every single run.
Why the file matters at all
An agent with no instruction file guesses fresh every time: how to run tests, what code style the project uses, which commands are dangerous. It works some of this out from the code, and gets some of it wrong.
The file removes that uncertainty once. Instead of re-explaining project context on every task, you write it down a single time, and the agent reads the file before it starts working.
What ends up in there for no reason
The most common mistake is generic advice about code quality: "write clean code," "follow best practices," "be careful." Phrases like that change nothing in the model's behavior, because they give no checkable criterion. The agent has no idea what to do differently.
A second common mistake is duplicating what the code already shows. If the project has one formatting convention and it is enforced by the linter config, there is no need to spell it out in words in the instruction file, the agent will see and apply it anyway.
A third mistake is a long file full of decision history. Explaining why a framework got picked two years ago is useful for a human and nearly useless to an agent working on a specific task today. That context eats space that could go to rules the agent actually needs.
What is genuinely worth keeping in the file
Concrete, checkable instructions work. The exact command to run tests, not a vague "test your changes." An exact list of files or directories that must not be touched without explicit permission. An exact commit format, if the project has a single one.
Instructions about deliberate exceptions to the project's usual patterns are especially valuable, places where a normal pattern is intentionally broken and why, so the agent does not "fix" it as a mistake. That kind of thing cannot be inferred from the code itself, it has to be stated outright.
It is worth recording deploy commands and the order of steps before one: what to check, in what order, what to do if one of the steps fails. This is exactly the case where a strict checklist beats a general description.
A good example of a 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." A rule like that is checkable: the agent either ran the commands or it didn't, and the result is visible right away, unlike a vague "watch code quality."
A structure that works
Short sections with headers work better than one long block of text: it is easier for an agent to find the right piece when the structure is predictable. A section for running things and tests, a section for deploy, a section for what not to do, a section for style if the linter does not already cover it.
Order matters as much as content. The most critical rules, the ones that must never be broken, belong near the top of the file, not buried in the middle among minor notes.
How to check the agent is actually reading it
The best test is simple: add one concrete, easily checkable rule that was not there before, a commit format requirement, for example. Give the agent a routine task and see whether the result follows it.
If the rule gets broken, the reason is usually one of two things: the wording is too vague, or the file is too long and the rule got lost 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 no rule at all: it confidently points the agent toward something that stopped being true a while ago.
A good habit is updating the file in the same commit that changes the process it describes. If the deploy command changes, updating the instruction file belongs in that same pull request, not in a later one.
In short
CLAUDE.md works when it holds concrete, checkable rules instead of general wishes. Cut what the code already shows, cut the decision history, keep commands, boundaries, and deliberate exceptions to patterns. An agent follows a short file with precise rules. It simply does not notice a long file full of general words.