Skip to content
Software Architecture Guide

Architectural Decision Record

Explanation

Section titled “Explanation”

An Architectural Decision Record (ADR) records one architectural decision. It explains why the team chose a design, so later readers see the rationale and not just the result. This helps teams avoid needless reconsideration of settled choices.

Why write ADRs. The CALM mnemonic names four benefits: collaboration, accountability, learning and management support.

Templates. Several templates exist. The Markdown Architectural Decision Record (MADR) template dates from 2017. It grew out of earlier ADR templates, including the Y-statement, and follows a decision journey from identification to enforcement. The article “Markdown Architectural Decision Records” covers it.

A Y-statement is a single structured sentence. It starts with “In the context of” and “facing”, which state the situation and the concern. It continues with “to achieve” and “accepting that”, which state the goal and the trade-off. An optional “because” adds the reason. The article “Y-Statement” covers it.

Title. A MADR title should convey the problem solved and the solution chosen.

Consequences. MADR lists consequences as “Good, because …” and “Bad, because …”. It also has a neutral form for arguments that are neither.

Length. Keep an ADR short. It can range from a slide-sized note to a few pages. Avoid “Mega-ADRs”. Move architecture details into separate design documents.

Common flaws.

  • Missing options: only one option is considered, or the alternatives are dummies. All neglected options should be evaluated too.
  • Decisions that are not traced to requirements.
  • One-sided “Fairy Tale” rationale.
  • A problem that lacks urgency.

See “ADR Common Mistakes and Review Checklist” for a fuller review list.

Example

Section titled “Example”

A team must pick how its web shop stores sessions. Its ADR has a title naming both problem and solution. It states the requirement that drives the choice. It evaluates at least two real options. It lists consequences as good, bad and neutral. It stays about a page long. Details of the session design live in a separate design document, and the ADR links to it.

Trade-offs

Section titled “Trade-offs”

A short ADR is easy to read, but it cannot hold every detail. Keeping the details in separate design documents solves this. Evaluating all options and listing bad consequences takes effort. Skipping that effort produces the flaws above: dummy alternatives and one-sided rationale.

Checks

Section titled “Checks”
  • The ADR title conveys both the problem solved and the solution chosen.
  • The ADR evaluates more than one real option, not dummy alternatives.
  • The decision is traced to requirements.
  • Consequences are listed as good and bad, with neutral arguments where they apply.
  • The ADR is short, and architecture details sit in separate design documents.
Section titled “Related”

Sources

Section titled “Sources”