Rules my agents actually follow

Everyone who works with coding agents ends up keeping some kind of mistakes file. The agent breaks something, you write down what happened, and you hope the note prevents a repeat. I kept one too. What I learned is that the file is the easy third of the problem. The other two thirds are getting the rule enforced, and keeping the record small enough that anyone, human or agent, still reads it.

First, the honest part. A written rule does not survive on its own. I measured this the hard way, a rule broken again 67 minutes after I recorded it, by a session that never lived the incident. Agents also repeat mistakes while remembering the rule, you can watch them acknowledge it and do the thing anyway. Prose loses the fight against a model’s priors. So my decision records stopped being prose and became entries with a fixed anatomy, and the two fields that changed everything are the least glamorous ones.

The first is Why, written for a stranger with no transcript. Not “as discussed”, not a summary of a chat that no longer exists. If the reason can’t stand alone, the decision will be relitigated by the next session and probably lost.

The second is Verify, a runnable command with an expected output. A rule you can only read is checked by luck. A rule you can execute is checked by machines, on schedule, forever. When one of my entries drifted from reality, the audit flagged it as a failing check and the fix was a one-line commit. Decay surfaced as a finding instead of a surprise.

Between the mistakes file and the record there is a path, and I ‘d argue this path is the actual system. An incident gets noted where it happened, cheap and unstructured. Recurrence makes it countable. Only a countable pattern graduates into the record, with an invariant and a verify line, and only recorded rules get wired into hooks that block instead of advise. Evidence, then law, then enforcement. Skip the middle and you get rules nobody believes. Skip the end and you get beliefs nobody follows.

And then there is bloat, which in the agent era is the default outcome. Models write more than anyone reads, records grow faster than they bind, and a 3000-word decision document is just prose with a fancier name. My counterweights are all mechanical. Index lines have a character budget and a hook rejects the commit that exceeds it, I have watched it reject my own agent mid-task, which is exactly the point. Files have word budgets checked by an audit. A fact lives in exactly one document and the same decision recorded twice is treated as a defect, because two copies always drift.

The anatomy itself is the quiet anti-bloat device though. Seven short fields leave an essay nowhere to hide.