You did the responsible thing. You added a rules file for your AI tool,
.cursorrules
or CLAUDE.md
or an AGENTS.md
, and you wrote down the important constraints by hand. For about a week it was great.
Then entropy showed up. Your team made four new decisions and none of the Slack ones made it into the file. Someone changed the caching strategy and the rules file still describes the old one. A constraint got relaxed and nobody updated the line that enforces it. Now your agent is confidently applying last quarter's architecture, which is strictly worse than no rules at all, because it carries authority while being wrong.
This is the exact failure that kills architecture decision records, and it kills them for a structural reason, not a discipline reason. A hand-maintained context artifact depends on a human stopping, mid-flow, to write down something whose payoff is deferred and uncertain. Humans do not do that reliably. They never have. Betting your agent's correctness on it is betting on the one behavior we have decades of evidence people will not sustain.
And the cost is higher now than in the ADR days, because you are not just informing future humans. You are steering a fast agent that will take a stale rule and propagate it across a dozen files before lunch.
So what is the alternative? Invert the default. Stop asking people to transcribe decisions into a file. Capture them where the decision already happens (the PR thread where you argued it out, the Slack channel where it was settled, the ticket where the constraint was set), pull out the choice and the reasoning and the rejected alternatives, and generate the agent-readable rules from that, continuously. The file stops being a thing a tired human curates and becomes a projection of decisions your team is already making anyway.
A few things I have learned building this:
If your rules file has five obvious entries and none of the hard-won ones, this is why. It is not your discipline. It is the format fighting human nature. What is the oldest line in your rules file, and is it still even true?