liveBook · Manning

Architecture decision record

As explained in Build High Value Software Systems

An architecture decision record is a concise document that records an architectural decision, its rationale, and its consequences.

An architecture decision record captures what was decided, when, why, and what event prompted the decision. Recording the constraints known at the time helps teams revisit the reasoning after an incident or when circumstances change. section 11.2.3

A useful record can include:

  • Decision, date, and status: whether it is pending, decided, or superseded. section 11.2.3
  • Trigger, options considered, and rationale: what prompted action and why an option was chosen. section 11.2.3
  • Constraints at the time and a review date: what was known or assumed, and when to revisit the choice. section 11.2.3

Defer API versioning until it is needed

For an internal API with three controlled callers, a team defers versioning and records the trigger: a partner begins integration. When that happens, usage data informs the choice of URL-path versioning with semantic versioning; changing endpoints are excluded from the first contract. section 11.2.3

Table 11.3 Architectural decision log template
Field
Purpose
Decision
What was decided
Date
When the decision was made
Status
Pending, decided, or superseded
Trigger
What event forced the decision now
Options considered
What alternatives were evaluated (links to spikes if applicable)
Rationale
Why this option was chosen over the others
Constraints at the time
What we knew, what we didn't know, what we assumed
Review date
When to revisit this decision

Use the decision-log template to capture the choice, alternatives, rationale, constraints, and review date. section 11.2.3

How Build High Value Software Systems covers it

How deep it goes
Details decision-log fields and explains how recorded constraints distinguish a flawed decision from one overtaken by change.
Examples
Uses a deferred internal-API versioning decision, triggered by a partner integration and resolved using observed API usage.
What you can do after
Diagnose incidents by tracing decisions to their original rationale and constraints, then assess whether conditions have changed.
How it connects
Connects decision tracking with root-cause analysis and kaizen.

Also explained in

Compare how 7 books explain architecture decision record →

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Build High Value Software Systems. The section links point to the parts of the book it draws on.