Architecture
Bit Rot Is Not a Metaphor
An architecture decision record gets written in sprint three. By sprint forty, three engineers have left, two new services were added, and the rule it documented is broken in seven places. Nobody deleted the ADR. Nobody overruled the decision. The rule just stopped existing anywhere except the document.
Neal Ford, Rebecca Parsons, and Patrick Kua called this bit rot in Building Evolutionary Architectures. The term comes from storage: physical bit rot is what happens when data on a medium degrades over time, without any external cause. Files corrupt because the medium changes under them, not because someone wrote bad data. They used it for the same thing in software: the architecture degrading without a visible failure, without anyone actively breaking it.
Most people use it as a colorful way to say things decay. But the thing it describes is concrete.
The rule that lives only in a document
ADRs were designed to capture context, not just decisions. The format varies, but the intent is the same: someone made a choice, here is why, here is what was considered and rejected. A future engineer finds the record and understands why the code is shaped the way it is.
But an ADR has no authority over the code. Nothing in the build pipeline checks it. A PR that imports directly across a boundary documented as indirect in ADR-007 will pass every automated check. The reviewer looks at the logic. The tests pass. The rule is in the document. The code does something else.
This is not a documentation quality problem. Teams with careful, detailed ADRs see the same decay. The gap is not in the writing. A rule that only exists in a file does not exist in the system. That is where the rot starts.
What 18 months looks like in git
The first violation usually has a reason. A developer needed to move fast, or did not know the rule existed, or knew it and made a different call in the moment. The PR gets reviewed for correctness. It is correct. It ships.
The second violation has a precedent. The code already does this. The third follows the second.
By month eighteen, the pattern is the codebase. A developer reading the code without the ADR would conclude that direct cross-boundary imports are fine, because every recent example says so. The ADR says the opposite. Both are accurate, but they describe different things: one describes the intent, one describes what actually happened. They drifted apart one PR at a time, and no single commit was the obvious turning point.
The first violation is an exception. The fifteenth is the convention. Nothing in between flags the change.
Not negligence. Not malice. A rule that had no presence in the work itself, invisible to reviewers, invisible to CI, invisible to anyone reading the code later.
When the agent is doing the coding
The problem pre-dates AI. But something does change when agents do most of the coding. A lot of architectural enforcement never lived in ADRs. It lived in code review conversations, in a senior engineer catching something informally, in someone looking at the approach and not just the output.
When an agent generates a PR, that channel gets thinner. Not because anyone decides to skip it, but because the review shifts toward output validation: does it work, do the tests pass, does it do what was asked. The architectural question, is this the right shape, gets quieter.
That is not a problem with agents. It is a pressure on something that was already informal.
Why documentation quality is not the answer
The natural reaction is to ask whether better documentation would have helped. More detailed ADRs. Clearer language. More visible placement. These are reasonable questions, but they address the wrong thing.
The ADR in month three may have been good. Clear context, alternatives considered, tradeoffs explained. A developer reading it in month six would have understood the rule and why it existed. But the developer in month eighteen is not reading the ADR. They are reading the code. And the code tells a different story.
The decay does not accelerate because documentation gets worse. It accelerates because documentation and code are maintained by different forces. Code changes constantly, driven by features, fixes, and deadlines. Documentation changes when someone decides to update it, which is less often. The gap opens on its own.
Building Evolutionary Architectures proposes fitness functions as the answer: automated checks that encode architectural rules directly into the build pipeline. A layering rule becomes a test that fails when violated. The ADR still captures the reasoning, but enforcement no longer depends on someone reading it.
That answer is correct. It is also underused.
Most codebases have neither fitness functions nor anything else that would have caught violation fifteen. They have the ADR, and an assumption that developers will read it and follow it. That assumption holds for a while. Then a few engineers leave. A few new ones join. The context that made the rule feel obvious is no longer obvious.
Architectural knowledge does not live in documents. It lives in the people who were present when the decisions were made, in conversations, in code reviews, in the patterns that shaped what new contributions looked like. Documents try to transfer that knowledge. But the transfer is incomplete, and no one measures how much gets lost.
The question is not how to document better. It is what to do with the documentation after it is written. Most teams do not have an answer to that.
The ADR is still there. Correct, complete, unread.