Architecture Decision Records exist to solve a recurring and expensive problem: six months after a significant technical decision was made, nobody remembers why it was made, the person who made it has left, and the team is either relitigating it or making a downstream decision that conflicts with it. ADRs are the solution. The problem is that most ADRs are either never written or written in a format that nobody reads.
"An ADR that nobody reads is worse than no ADR. It creates false confidence that decisions are documented while the actual institutional knowledge lives only in the heads of engineers who were in the room. The test of an ADR is not whether it was written — it is whether someone six months later can understand why the decision was made without asking anyone."
— Michael Nygard, Author of Release It! and architect at Cognitect, on architectural documentation practices (2022)## The minimal ADR format that works
The classic ADR format from Michael Nygard is short and effective: Status (proposed, accepted, deprecated, superseded), Context (what is the problem we were solving and what were the constraints), Decision (what we decided to do), and Consequences (what becomes easier and what becomes harder as a result).
