Skip to content
Software Architecture Guide

Architecture Decision Rationale

Explanation

Section titled “Explanation”

A design choice says what the team picked. The rationale says why. Answers to “why?” questions matter as much as any other part of a design, and a decision log can supply them.

What counts as a decision. arc42 defines a decision as choosing one alternative based on criteria. The aim is that stakeholders can comprehend and retrace it. The ADR community adds that an architectural decision is a justified design choice that addresses an architecturally significant requirement (see Architecturally Significant Requirement).

Where the standard stands. The arc42 quality site summarizes ISO/IEC/IEEE 42010 as requiring that decisions and their rationale be documented (see ISO/IEC/IEEE 42010 Architecture Description Standard).

Record format. An Architectural Decision Record (ADR) captures exactly one decision and its rationale. arc42 recommends Nygard-style ADRs. In them, the consequences list all effects, not only the positive ones. The Y-statement is a leaner template than Zimmermann’s earlier attempts (see Y-Statement).

Which decisions to record. Record only the key decisions, because only those justify the effort. arc42 section 9 covers decisions that are important, expensive, large-scale or risky, together with their rationales.

Quality of the justification. Only crisp and sound justifications convince a reader. Refer to actual requirements and evidence. Avoid pseudo-rationale and killer phrases.

Example

Section titled “Example”

A team chooses a message queue over direct calls between two services. The record states the problem: orders must not be lost when the billing service is down. It names the rejected option, direct calls, and its consequence: lost orders during outages. It states the choice and ties the reason to that requirement. It also lists the downsides of the queue, not only the benefits. Years later, a new team member asks why direct calls were not used. The record answers the question.

Trade-offs

Section titled “Trade-offs”

Writing rationale costs effort. That is why only key decisions deserve a record. Recording too many dilutes the value, and weak justifications convince nobody. A lean template such as the Y-statement saves effort, while a longer one such as a Nygard-style ADR gives room to list every consequence.

Checks

Section titled “Checks”
  • Each recorded decision names the chosen alternative and the criteria or requirement behind the choice.
  • Each ADR covers exactly one decision together with its rationale.
  • Consequences list all effects of the decision, not only the positive ones.
  • Section 9 holds only important, expensive, large-scale or risky decisions.
  • Justifications cite actual requirements and evidence, not pseudo-rationale or killer phrases.
Section titled “Related”

Sources

Section titled “Sources”