Writing rules for agents: every line of our AGENTS.md cost us an incident

At the root of our repository sits a file that every agent reads before touching anything. It is not documentation: it is a contract. And the interesting part is not what it says, but how it came to say it.

Almost none of its rules came out of an architecture discussion. Almost all of them came out of something breaking.

The rsync rule

One day a configuration file needed to go up to production. The correct path was the deploy script, but copying it by hand was faster. Someone ran a command with two source files and one destination directory.

What went unconsidered is that the tool discards the source path and copies by base name. An application's configuration file landed on top of the server's root configuration file. In production.

That rule now takes a full paragraph, with the correct example, the incorrect one, and the date of the incident. It is one of the longest in the file, and it is long on purpose: whoever reads it should understand why it exists, not just what it forbids.

Concrete prohibitions, not principles

The difference between a rule that gets followed and one that gets ignored is how specific it is.

"Write clean code" does not work. It is not actionable, and everyone reads something different into it.

"No hard deletes, use soft deletes with status: deleted" does work. It is verifiable: either the record is still there or it is not.

Our file has an entire section that is just a list of prohibitions, one per line, each with its reason in parentheses when the reason is not self-evident. It is the most consulted section by far.

The detail that surprised us most

Writing these rules for agents improved how the humans work.

Things that used to live in somebody's head are now written down. When a new person joins the project, they read the same file the agent reads and start out knowing where the live wires are. The documentation we would never have written "for ourselves" got written because an agent needed it.

There is something faintly comic about that: we got organized because we had to explain to a machine how not to break things.

What goes in and what stays out

After a fair amount of iteration, the criterion settled here.

Into the file goes anything you cannot deduce by reading the code: conventions that are not obvious, decisions already made that we do not want to relitigate, and everything that broke something once.

Out of the file stays anything the code already says. Listing the folder structure guarantees that in three months the list will be stale and the agent will trust false information. A stale rule is worse than no rule, because both get read with the same confidence.

The acid test

Every so often we read the whole file line by line, asking whether each rule is still true. The ones that no longer are get deleted without sentiment.

A contract with dead clauses stops being a contract and becomes folklore.