Originally written in French. Translated by AI — the meaning has been preserved, not the prose.
Short definition
A short document tracing a software architecture decision: the context that made it necessary, the options considered, the option retained and the consequences accepted. Abbreviated ADR.
Full definition
The practice comes from development teams and is widely established there. Its reason for existing is temporal: several months or years later, someone who wasn't there must be able to understand why a technical choice was made — why a queue was introduced to process certain messages asynchronously, which options were set aside, what the choice enables and what it constrains.
In the articles on this blog, the term is used as the original reference rather than for itself: it serves to situate the Product Decision Record, which takes up its structure while moving the object from the technical component to the product rule. The difference in nature is that of what is traced — an ADR fixes a choice in how the system is built, a PDR a rule applicable to future situations.
The ADR has a property that product vocabulary takes up badly: it commonly documents projects with no visible business value. A month of work on a queueing technology delivers nothing to the end user and can nonetheless remove a bottleneck, absorb ten to thirty times the load by simply adding servers, and free up the sale of new customer accounts.
Usage in the field
The term comes into play in discussions about a team's technical memory, about justifying projects with no functional delivery, and as a point of comparison whenever an equivalent arrangement is proposed on the product side.
Synonyms and variants
"Architecture decision", "ADR", "architecture log". The plural "the ADRs" commonly designates the whole register as much as its entries.
Not to be confused with
- Product Decision Record — Product Decision Record — the same documentary form applied to a cross-cutting product decision rule; it commits to no choice of construction.
- Architecture documentation — a description of the system's state as it is; the ADR describes a moment of choice and isn't updated when the system evolves.
- Technical specification — a description of what must be built and how; it follows from an architecture decision, it doesn't justify it.
Examples
"An application is hit by a surge in load. […] The team then decides to put in place a queueing technology to process certain messages asynchronously." — the typical situation an ADR records.
"Why was it taken? Which options were set aside? What consequences are accepted? What does it enable? What does it constrain?" — the questions the entry answers.
Ambiguities / debates
Ordinary usage wavers on immutability: some teams hold their ADRs as frozen documents and mark replacements, others update them like living documentation. The sense retained here follows the first practice, which is also the one the PDR takes up.