An architecture decision record (ADR) is a short log entry for one significant design decision, and it works only if it is brief, specific and easy to find. Teams that skip ADRs tend to repeat old debates. Teams that write them badly end up with a folder nobody opens.
This article covers which decisions deserve a record, what to put in one, and how to keep the records useful as the system changes.
What is an architecture decision record?
An ADR is a log of a workload's key decisions that shows how and why the system took its shape. That is how Microsoft's Azure Well-Architected guidance, updated April 13, 2026, describes it. The record captures the reasoning behind a choice, not only the choice.
The reasoning is the part that disappears. Microsoft's guidance says undocumented decisions tend to be forgotten, which leads to repeated debates. A new engineer sees a design that looks odd, proposes the obvious fix, and the team spends time rediscovering why it was built that way.
Which decisions deserve a record?
Write an ADR only for architecturally significant decisions, meaning choices that are costly to reverse. Martin Fowler's guide says an architect's key task is to reduce irreversibility, and it adds that what counts as architectural depends on what the developers consider important.
In this author's judgment, these usually qualify:
Choosing an architectural style, such as a modular monolith or microservices.
Choosing a data store or a way to share data between components.
Choosing synchronous calls or asynchronous messaging between parts of the system. Setting a boundary that a team will have to respect for years.
Naming a variable does not qualify. If reversing the decision takes an afternoon, skip the record. If reversing it takes a quarter, write one.
What goes in an ADR?
A useful ADR holds the problem and its context, the options considered, the decision with its trade-offs, and a status such as Proposed or Accepted. Keep each part to a few sentences.
How do fitness functions fit with ADRs?
A fitness function checks that the system still follows the decision the record describes. Wikipedia says architects should use fitness functions, which are tests of a quality goal such as response time, to keep the architecture in check as the system changes.
This pairing matters because of architecture erosion. Perry and Wolf described the problem in 1992, according to Wikipedia: the implemented system drifts from the intended architecture. A record states the intent. A fitness function tests it. Without the test, the record becomes a statement about a design that no longer exists.
For example, if a record says the checkout service must not call the email provider directly, a test can fail the build when someone adds that call. This example is illustrative.
Where do ADRs sit among other architecture documents?
ADRs record decisions, and other documents show structure. No single diagram serves every reader, which is this author's judgment. Wikipedia notes that Philippe Kruchten's 4+1 view model, published in 1995, separates concerns across views, and that the C4 model helps teams model "just enough." The international standard for architecture description is ISO/IEC/IEEE 42010.
Use views to show what the system looks like and ADRs to explain why. TekRevol's software architecture guide includes a worked decision record for keeping order management in one deployable application next to a comparison of six architectural styles, which shows how a record can sit beside a style choice.
The takeaway
Write ADRs for decisions that are costly to reverse. Keep each one short, name the options and the consequences, append instead of rewriting, and test the intent with fitness functions. A good record answers the question a future engineer will ask: why did we build it this way?
Top comments (0)