Claude Project Instructions That Change Behavior

Every project instructions file starts the same way: an afternoon of enthusiasm, a page and a half of good intentions, and then nobody ever checks whether a single line of it is read. It gets loaded before every task, which makes it the one document in the repository with a recurring cost and no owner.

The useful question is not what to put in it. It is which lines actually change what the model does, and which are decoration you are paying to send on every request.

Why this exists

The failure mode is a file that has grown long enough to be treated as noise. Length competes for room with the task itself, and when everything is written down, nothing is emphasized. Because nobody can tell which lines are working, nothing is ever removed — so the file only grows, and the growth is what kills it.

Underneath that sits a smaller, more fixable mistake: prohibitions with no named replacement. Do not use the old HTTP client leaves the model to pick a substitute, and it will pick whichever appears most often in the code — usually the one you are migrating away from. Use the client in lib/http; lib/legacy_http is deprecated gives it a destination. Same rule, different outcome.

How to use it

Derive it from observed failures, not from imagination. Ask the tool to make a small change somewhere nobody has touched recently and watch exactly where it goes wrong. A deprecated pattern copied is a missing current-pattern line. A wrong test command is a missing verification section. Each mistake is a line you have now earned the right to write.

Then run the deletion test. Remove one line, run the same task three times in a fresh session, and compare the output to three runs with the line present. If nothing changes, the line was comfort, not instruction. This is the only check that separates a rule that works from a rule that feels responsible, and it is the reason a good file can stay short.

Sort by lifetime, not by topic. A rule that holds for every task here belongs in the file. A rule that holds for one task belongs in that prompt. A rule that will change next week belongs in the ticket. Most bloated files are bloated with the third kind.

Attach the reason to every non-obvious line. One clause is enough. Without it, a future reader cannot tell a stale rule from a load-bearing one, and removing an unexplained rule feels risky, so it stays forever.

Budget a page. Keep it in the stable part of your prompt so it sits inside the cached prefix rather than being re-billed in full on every call.

Where it goes wrong

It is not retrieval. Instructions change how the model works, not what it knows. If the model is missing a fact, no line in this file supplies it.

It cannot encode a decision you have not made. If two patterns are both live and nobody has chosen, the file will honestly describe both, and the model will pick one — usually the older one. The file is downstream of the decision, so make the decision first.

One person’s preference silently becomes everyone’s rule. A line about comment style added on a Tuesday governs every AI-assisted change after it, without a conversation. Review changes to this file with the seriousness you would give a change to the linter configuration, because that is functionally what it is.

Verification lines have to be true. A test command that is subtly wrong is worse than none, because the agent will run it, watch it pass, and report done. Run every command in the file yourself before you commit it.

Do not write one for a repository you touch twice a year; the maintenance will cost more than it returns. And when you catch yourself adding a rule to stop something that happened once, put it in the ticket instead.