I once measured how long a written rule survives a fresh agent session: 67 minutes. The rule was recorded right after one session swept another session's half-finished files into its commit, and it was plain:
- Stage explicit paths only, never
git add -A.
The next session had never lived the incident, read the rule as advice, and did the thing anyway.
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 the 67 minutes taught me 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.
A written rule does not survive on its own, that is the honest part. Agents 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. This is the whole shape, using that staging rule as the worked example:
## D-035 — 2026-08-02 — Stage explicit paths only, never add-all
**Decision:** one imperative sentence, no hedging.
**Why:** written for a stranger with no transcript.
**Invariant:** the line that must stay true for the rule to hold.
**Boundary:** the condition under which this rule stops applying.
**Rung:** law or practice, how hard it binds.
**Verify:** `grep -rn "git add -A" hooks/ scripts/` → nothing
**Scope:** which projects the entry covers.
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. The auditor is the one piece of this system I made public, etymd, it reads the claims your instruction files make and checks them against the actual repo, npx etymd audit and you have it.
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.
incident, noted where it happened cheap, unstructured
│ happens again
▼
countable pattern a count, not a feeling
│ graduates
▼
record entry: invariant + verify law
│ wired into
▼
hook that blocks instead of advising enforcement
Skip the middle and you get rules nobody believes. Skip the end and you get beliefs nobody follows.
- Evidence, then law, then enforcement.
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.
