Resources · 84
Architecture decisions: retain the rationale and know when to reconsider
Document consequential choices without turning every meeting into an oversized dossier.
· 4 min
What this guide helps achieve
- Bound the decision
- Compare plausible options
- Name the decision and consequences
- Preserve historical context
- Define useful review triggers
Quick check
- Does every ticket need an ADR?
- Can an accepted decision change?
- Does a register guarantee a good choice?
Step-by-step method
- 01
Bound the decision
Choose a question with lasting effects, such as hosting, integration, storage or component boundaries. An ADR preserves the rationale of a significant architectural choice. Describe the actual problem and current constraints rather than retrofitting a commercial justification.
Deliverable: decision question and scope.
- 02
Compare plausible options
Describe options genuinely considered, including keeping the current solution where viable. Apply common criteria for use, security, operation, included costs and exit. Separate measurements, documentation-derived claims and remaining assumptions.
Deliverable: criteria and evidence table.
- 03
Name the decision and consequences
Record the chosen option, owner, date and status. Describe accepted effects, including debt, migration and limitations. Approval does not eliminate a known constraint. Link the choice to requirements met and checks still needed.
Deliverable: accepted decision and explicit consequences.
- 04
Preserve historical context
A replaced decision should remain understandable. Link it to its successor instead of rewriting history. The ADR process distinguishes proposed, accepted, rejected and superseded decisions. Retain links to tickets and evidence the team can access.
Deliverable: register with version relationships.
- 05
Define useful review triggers
Specify changes such as volumes exceeding the tested scope, provider unavailability, localization needs or costs outside assumptions. A trigger should initiate an updated comparison rather than automatic abandonment. Check whether a new service owner can explain the choice without consulting its original participants.
Deliverable: review triggers and handover test.
Acceptance case to reproduce
Fictional example: these inputs describe no customer or observed result.
View case inputs
{
"decision": "ADR-7",
"status": "accepted",
"assumption": {
"requests_per_day": 1000
},
"current_requests_per_day": 100000
}Expected decision
The load assumption changed by a factor of 100. Revisit ADR-7 and retain the historical decision.
Fictional variations to test
An ADR is accepted but only one of three services implements it.
Distinguish accepted decision from completed rollout. Track the remaining services with an owner, any exception and evidence of adoption.
The pilot requires p95 ≤ 200 ms; the test measures 350 ms.
The stated criterion is not met. Retain load, window and test result, then decide on revision rather than declaring success.
A temporary exception reaches its review date.
Mark it for reassessment. Silence does not automatically renew an exception; assign a dated decision with conditions and an owner.
Evidence to retain
- ADR status and adoption by service.
- Pilot criteria, procedure and measured result.
- Owner, deadline and exception decision.
Verification procedure
- Record decision, alternatives and load assumptions.
- Compare a failed assumption with current conditions.
- Keep the old ADR and its replacement link. Date the changed assumption, name the review owner and specify evidence needed to decide whether the replacement fits the new context.
AWS Prescriptive Guidance — Architectural decision record process
Reusable worksheet
Complete with your authorised observations. These fields are a working template, not observed results.
| Field | Information to record |
|---|---|
| Question | Problem, scope and constraints at decision time |
| Options | Compared solutions and common criteria |
| Choice | Status, owner, reasons and consequences |
| Review | Trigger and link to any replacement decision |
Worked example
Illustrative situation
Fictional example: a team selects managed search because it cannot provide the required on-call coverage.
Decision and expected evidence
The register records this constraint, expected exports and review triggers for changed localization needs or costs.
Distinguish the mechanisms
| Mechanism | Purpose | Check or limitation |
|---|---|---|
| Meeting minutes | Retain discussion | The decision may be scattered |
| ADR | Retain choice, reasons and consequences | Does not replace specifications or tests |
| Implementation ticket | Track delivery work | May close without retaining the rationale |
Management indicators
| Indicator | What it measures | First action |
|---|---|---|
| Traceable choices | Significant decisions with accessible context and consequences | Address dependencies hardest to take over |
| Checked assumptions | Decisive assumptions tested or measured | Revise criteria where evidence is missing |
| Handover | Choices a new owner can explain | Improve the register instead of adding meetings |
Common pitfalls
- The decision may be scattered
- Does not replace specifications or tests
- May close without retaining the rationale
Frequently asked questions
Does every ticket need an ADR?
No. Reserve it for significant choices whose consequences or reversibility justify retaining the rationale.
Can an accepted decision change?
Yes. Record the new decision, its context and its relationship to the replaced decision without deleting earlier reasons.
Does a register guarantee a good choice?
No. It makes criteria and assumptions open to review; evidence and testing quality remain decisive.
Further reading and tools
Editorial resources to extend the method.
- Française du Numérique — website brief External link
Turn decisions into scope, constraints and delivery criteria.
Official references
References consulted: . The method and worksheet propose checks to adapt to your context; they do not constitute certification.
