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:
- The rejected option is the highest-value field and the one every existing tool throws away. "We tried X, it failed this way, do not bring it back" is what actually prevents the agent from regressing you.
- Decisions are cross-surface. The why is split across Slack and GitHub and Jira, so anything single-surface is blind to most of it.
- Write time beats review time. A constraint the agent reads before generating is worth ten warnings after.
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?
Top comments (0)