Resources · 84
Architecture decisions: retain the rationale and know when to reconsider
Document consequential choices without turning every meeting into an oversized dossier.
· 3 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.
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.
Continue exploring
Related analysis
