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:
