Architecture Decision Record: The One Record Engineers Keep and Founders Don't
The Compass Team
November 10, 2026
In November 2011, Michael Nygard wrote a short post about a specific bad day: a new developer joins a project and finds a decision nobody can explain. The fix he named that day is the architecture decision record.
That person has two moves. Accept the decision without understanding it, or change it without understanding it. Nygard's point is that both are bad.
A project that collects enough unexplained decisions gets afraid to touch anything.
His fix was deliberately small. One file per architecturally significant decision, numbered in sequence, numbers never reused, stored with the code.
Four parts: Context, Decision, Status, Consequences.
The structure does the work. Context is written value-neutral and lists the forces in tension, politics and team skill included.
Decision is the response, in full sentences, active voice. Consequences lists the bad outcomes beside the good ones, because a benefits-only list is a sales pitch.
Status is what makes the collection a history: when a call reverses, the old record stays and gets marked superseded, with a pointer to the new one.
That rule matters more than any template. adr.github.io calls the collection of records a project's decision log, and says a record captures one decision with its rationale, its trade-offs and its consequences.
Microsoft's Azure guidance says keep the log append-only, never edit accepted records, and record the confidence level you had at the time. Martin Fowler adds the second payoff: writing the record surfaces disagreement while it can still be resolved.
His example titles read like sentences a founder would recognise: ADR 1: Deployment on Ruby on Rails 3.0.10. ADR 9: LDAP for Multitenant Integration.
Keep each record to a page or two and write it as a conversation with a future developer.
Adoption went sideways from engineering into government. Thoughtworks moved decision records into the Adopt ring of its technology radar in 2018. The UK government published an Architectural Decision Record Framework in November 2025 for the whole public sector.
Fifteen years of a format winning inside software, and most founders have never kept one for the decisions that set the structure of the company.
Pricing. The first senior hire. Which customer to turn down. Whether to raise.
Those decisions are architecturally significant for a business. They get made on a call, with the reasoning in one head and no status field anywhere.
The company pays Nygard's price. A new hire reads the pricing page and either accepts it or changes it, with no way to tell which forces produced it.
Six months later the call gets reversed and nobody can say what it was buying.
One record per decision, four lines. The forces, the call, the status, the consequence you expect. When it changes, add the next record beside it instead of editing this one.
The engineers worked the format out in 2011. The businesses they work for are still deciding on calls.
Share this article