Skip to content
Software Architecture Guide

Architectural Decision Management Cycle

Explanation

Section titled “Explanation”

An architectural decision (see Architectural Decision) is a design choice that shapes a system. The decision management cycle describes how a team works through one such choice. It has five steps. They are logical steps, not a rigid sequence.

Step 1: Identify and prioritize. The team finds the decisions that matter and ranks them. Significance scores, such as an Architectural Significance Test, help. So does a high-high ranking in a quality attribute utility tree. Both point to decisions that deserve early attention.

Step 2: Evaluate options. The team compares options against a set of criteria. These criteria are also called decision drivers. A decision is ready for this step only when at least two alternatives exist.

Step 3: Decide. The team chooses one option. The choice rests on the criteria and analysis from Step 2. Decision making is a team activity. Decisions should be prepared, made and captured at the Most Responsible Moment.

Step 4: Record. The team writes down the outcome, the justification and the consequences. Good practice logs at least one architecturally significant requirement per record. It also names the decision makers, so someone is accountable.

Step 5: Enforce and evaluate. The team monitors whether the design problem from Step 1 is actually solved. Many decisions never reach this step.

Links to ADR formats. The MADR format (see Markdown Architectural Decision Records) has a Decision Drivers section. It holds the desired qualities, forces and constraints behind a decision. Its optional Confirmation section covers Step 5. It describes how the implementation is enforced and evaluated, for example through reviews or tests. MADR’s core is close to Nygard’s 2011 ADR proposal. MADR evolved from that format and from Y-statements.

Iteration. The same decision can run through the steps several times. Teams should also be ready to revise a decision as design work evolves. An outdated record can be marked superseded.

Example

Section titled “Example”

A team must choose how its web shop sends order data to a billing system. Fast response times rank high, so the team treats this as a priority decision. It lists two options and compares them against criteria such as response time and effort. Two named people choose one option. They record the choice, the reasons and the consequences in an ADR. Later, a review checks whether orders now flow fast enough. If not, the team reopens the decision and may supersede the old record.

Trade-offs

Section titled “Trade-offs”

Running the full cycle takes effort, and many decisions never reach Step 5. The steps are logical, so a team can skip around or repeat them. Revising decisions keeps the record accurate. It also means the record needs upkeep, for example by marking outdated ADRs as superseded.

The five logical steps of the cycle. Steps can be repeated for the same decision.

Diagram source 
flowchart LR
  A[1 Identify and prioritize] --> B[2 Evaluate options]
  B --> C[3 Decide]
  C --> D[4 Record in ADR]
  D --> E[5 Enforce and evaluate]
  E -.revisit.-> A

Checks

Section titled “Checks”
  • Each ADR logs the resolution of at least one architecturally significant requirement.
  • Each ADR names its decision makers.
  • Each decision lists at least two options and the criteria (decision drivers) used to compare them.
  • Each ADR records the outcome, its justification and its consequences.
  • Outdated ADRs are marked as superseded.
Section titled “Related”

Sources

Section titled “Sources”