A Rule Without Its Reason Can Only Be Obeyed or Ignored.
Watch the video version:
On October 16, I read one line and felt a jolt of alarm: "Here's the reply, sent from your personal address." For a second, I thought an email had gone out under my name without my yes. It hadn't. The AI assistant I use for email had prepared a draft and described it as if it were already sent. I asked the only question that mattered: "Did it send or you drafted?"
That day I wrote a rule. Every email is shown to me as a labeled draft first, opening with a plain line that says it has not been sent, and nothing goes out without my explicit yes. Under the rule I wrote the reason: the October 16 draft, the words "sent from your personal address," and my question back. The rule and the failure it came from sit in the same file, a few lines apart.
Three weeks later, the rule was wrong for part of my work. A one-line reply to my book printer was arriving with the same ceremony as an email to a client. I said so: "that's far more sign off for that email than I need with a vendor, this is no different than responding to Greenlamp." The rule was revised in one sentence. Vendor replies are drafted right away, stated plainly, with one status line. Every email still waits for my yes. The revision took a minute, because the reason was on the page. I could see what the rule was guarding against, a send I had not approved, and I could see that a lighter draft for a vendor did not bring that failure back.
Most teams adopting coding agents treat their rules file the way companies once treated the values poster in the lobby. Write it once, commit it, done. The agent reads it on every run, so getting it into the repo feels like the finish line. The appeal is real: the file is concrete, it is versioned, and it looks like governance.
A study of 441 repositories this fall, RAMP, found that 73.8% of AI configuration files were committed once and never changed. Among repositories where agents do most of the work, the ones with no committed configuration showed cognitive complexity rising 53%, against 27% for the ones with it, along with 1.7 times the increase in static-analysis warnings. The authors call their work hypothesis-generating, and it is observational: teams disciplined enough to write a rules file may be disciplined in other ways too. What the numbers do show is how the files are treated. Three of every four are written once and left alone.
Here is what happens to a file nobody revises. Every rule went in because something failed. The rule made it into the file; the reason stayed in someone's head, or in a chat thread from last spring. Months later, nobody can tell whether a rule still holds. Changing it feels like inviting the old failure back, so nobody does, and the file grows and freezes. That gap is the one The Persistence Layer exists to close: a team's memory has to carry the reasoning behind a decision along with the decision itself.
When a rule fits badly, your team works around it instead of changing it. They override it in the prompt, throw out the agent's output, or fix the result by hand. Each correction stays with whoever made it. The system learns that the file is something you obey or route around, never something you edit, and that editing it is someone else's job. New corrections keep landing in chat and review comments, where no agent and no new hire will ever read them.
The cost lands on whoever reviews the agent's output and whoever knows the workarounds. A new engineer, and the agent itself, meet the file as written and follow last spring's rules. A system is rated by what a new person encounters, not by what the document says. The file says one thing and the work does another. That is what I call The Flip: one face on the poster, a different one in what the team actually does, and only one visible at a time. A rules file nobody revises is the agent era's values poster. It hangs in the repo, nobody remembers approving it, and it stops describing the work.
The teams whose files stay current aren't more disciplined than yours. Their rules carry the correction they came from, so any rule can be checked against its reason and changed without fear. A rule that carries its reason can be revised. A rule without its reason can only be obeyed or ignored.
Write the reason next to the rule: one line on the failure each rule came from. Then give corrections a path into the file. When someone works around a rule, the workaround becomes an edit, not a chat message. A rules file is only as current as the last correction that reached it, and what your new engineer and your agent read on day one has to be the rules your team works by today.
Open your team's rules file this week: the agent instructions, the coding standards, whatever the agent reads on every run. Take the three oldest rules and write next to each one the failure it came from. Any rule nobody can explain goes in front of the team: does it still hold, or is someone already working around it? Revise it or delete it this week. The next time someone fixes the agent's output by hand, ask them to put that correction in the file.
I send a short daily email to technical leaders on exactly this kind of design question; today's was about why a rule without its reason freezes, and how a team keeps its rules file describing the work. Get the next one here: https://technicalleader.coach/daily-email
