AGENTS.md Is a Wish List Until You Add Teeth

The instruction file nobody obeys

Every serious repo now has an AGENTS.md. Most read like this: "Please write clean code. Follow best practices.

Be careful with the database. Thanks!"

The agent reads it, feels inspired, and installs three packages, refactors auth, and drops a column — politely, with clean commit messages.

Agents.md conventions that prevent breaks share one trait: every clause is enforceable by something other than goodwill. If no gate, hook, or reviewer can fail a violation, the clause is decoration.

Wish lists vs law

Three details make wish-lists worse than useless:

1. They create false confidence. "We have guardrails" — no, you have paragraphs. The team relaxes review exactly where protection is thinnest, and the incident lands with documentation claiming it could not happen.
2. Agents obey the letter, not the spirit. "Be careful with the database" parses to nothing actionable; the agent proceeds carefully while dropping the column. Vague clauses get vague compliance — which is to say, none.
3. Length buries the load-bearing lines. A 200-line file with three real rules teaches agents that rules are prose to skim. The file grows because adding feels safer than pruning; protection thins with every well-meaning addition.

The mobile-guard post showed fences surviving small screens. This one writes the four clauses that constitute the fence.

Four clauses, one page, teeth

BoringPush ships two files for this, and the split is deliberate. One is the agents file, which holds behavioral law.

The other is the conventions file, which holds the structural map. Below, the four clauses that do most of the preventing, written so you can adapt them to your own repo.

Step 1: Write the forbidden list first, before any guidance. Four example nevers:

• Never install packages without written human approval.
• Never drop, rename or truncate a table, or delete without a condition.
• Never commit secrets such as production settings files or private keys.
• Never push directly to the main branch from an agent session. Stage branches only.

Prohibitions lead because agents default to action: install, drop, commit, push. Pair each never with an automated backstop, such as a lockfile diff, a destructive-statement check, a secret scan on push and branch protection, so a violation fails loudly instead of landing quietly. Four nevers outrank forty pleases.

Step 2: Specify shapes, not goals. Write down what a compliant route looks like: validate the input, check access, make one call, return JSON, in under about 40 lines. Write down that every database engine exports the same actions with plain data and no driver details. And write down that migrations are additive only.

"Thin routes" is advice, while the four-movement shape with a line count is law. "Consistent data layer" is a wish, while identical action names are checkable.

Every shape clause answers "what does compliant look like" precisely enough that a reviewer, human or script, can give a verdict in seconds. Goals inspire, and shapes constrain.

Step 3: Define done as a command, not a feeling. Done means a syntax check on touched files, a lint run with zero warnings, a smoke test of the changed path and a healthy response from the app. "Done" without pasted output is a draft, with no exceptions.

The "done, but checkout returns a 500" fiasco dies here, because claims require evidence in the session transcript. Agents adapt within two sessions, since pasting the output becomes a reflex when approval depends on it. The definition travels across tools too: Claude, Cursor, OpenCode and Antigravity all run shell commands, so done-means-green works everywhere with no per-tool setup.

So that's the stack: the law fits on one page and holds on every device.

Wish list vs law

The cost side, stated plainly: law-writing demands senior judgment upfront. Deciding the four movements, the forbidden classes and the done-command takes a real afternoon of thought. Teeth need maintenance too, because checks rot as patterns evolve and need the new forbidden pattern yearly.

BoringPush treats both as infrastructure rent: cheap, scheduled and non-optional. Unfenced quarters feel faster until the incident itemizes them.

FAQ

How do the agents file and the conventions file differ? Don't they overlap?

Behavior versus structure: the agents file constrains what the agent may do (never install, additive only, gate before done), and the conventions file maps where things go and what shape they take. Sessions read behavior first ("what am I forbidden"), structure second ("where does this live"). One page each, cross-referenced, zero duplicated clauses to drift.

My AGENTS.md is already 200 lines — trim or rewrite?

Trim in one pass: highlight every clause a script or reviewer can fail mechanically; move the rest to docs. What remains is usually under a page — that is your law.

The moved prose still helps humans, but agents get the short file. Length was the bug; the rewrite is deletion with a save button.

Which clause prevents the most damage per word?

"Never DROP, ever" — four words against total data loss. Second place: the gate definition of done, which catches everything else indirectly (phantoms break builds, fat routes break lint, secrets trip hooks).

If your file holds only two clauses, those two cover the catastrophic and the common. Add the rest as incidents teach you.

How do I keep the file working as vendors change instruction paths?

Symlink, never duplicate: keep law in AGENTS.md, link each tool's expected filename to it, and verify the link resolves after every tooling update. Quarterly, check vendor docs for renamed paths (they rename them). One source of truth survives renames; five copies disagree by spring.

Should agents be allowed to propose changes to the law?

Yes — as separate diffs to the file, reviewed like code, never as drive-by violations inside feature work. "This rule cost me an hour, here's the amendment with evidence" is how law improves.

Agents operating under constraints spot bad constraints reliably; the amendment process converts their friction into better fences. Frozen law rots; amended law compounds.

Does the law slow down experienced human contributors?

Barely, and only where slowing helps: humans also skip gates and eyeball migrations. The exception-free version: same file, same gate, same shapes — seniors pass on autopilot and juniors (carbon or silicon) get guardrails.

Uniform law removes the "do as I say" tax that makes contributors resent process. Everyone ships under the same four clauses.

Keep reading

• OpenCode SaaS Starter: Stop the Every-Session Redesign — the structural half of this split
• Thin Routes: Why Agents Fear Your 250-Line Handler — Clause 2, defended at length
• Migrations AI Can't Nuke: Additive Only, Never Drop — Clause 3, with the 3-deploy pattern