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






