AGENTS.md doesn't work. Here's what did.

I spent a long time trying to make AI coding agents follow project rules through instruction files: AGENTS.md, CLAUDE.md, a rules folder. For a handful of basic instructions it works. Put your whole development "bible" in there and it falls apart.

The pattern is probably familiar. The agent breaks a rule, apologizes, promises it won't happen again, and breaks it again two changes later. It isn't being lazy. A rule in the prompt is a wish: it competes with everything else in the context, and the longer the session, the weaker it gets.

What actually worked

While building Semitexa, an open-source PHP framework designed for agent-driven development, I moved the rules out of the prompt and into a command. The only instruction the agent gets about rules is this:

Check every code change you make with ai:verify. If it lets you pass, move forward.

ai:verify looks at what changed and runs the lint and the tests that matter for that diff, plus the structural checks: where logic is allowed to live, what may call what. When it fails, the agent gets a concrete message about the thing it just did.

Three things changed:

1. The rules stopped competing for context. Adding a constraint no longer makes the prompt longer, so I can have as many as the project needs.
2. Failures became specific. "Handler returns a raw Response" is something an agent can fix in one step. "Follow the architecture" is not.
3. The agent got better over the session. The feedback arrives right after the mistake, not at review time, and more and more often the next change passes on the first try.

What the instruction file is still for

I didn't delete AGENTS.md. It got short. Now it's a map: where things live, which commands to run, and the one rule above. Anything that can be checked moved into the check. Anything that can't be checked (naming taste, whether an abstraction pulls its weight, whether the change matches the intent of the ticket) stays with human review.

The trade-off

A check costs more to write than a sentence. Some rules are genuinely fuzzy and never become checks. But every time I noticed myself writing the same review comment twice, it turned out the rule was never fuzzy, just unwritten. Those are the ones worth turning into code first.

Your turn

Where do your project rules live today: in instruction files, in CI, or in reviewers' heads? And has anyone found a good way to measure how often an agent actually follows an instruction file?