An architecture decision record (ADR) can remain an accurate account of what a team chose while no longer being a reliable guide to what the team should choose now. The warning sign is a change in the context, requirements, constraints, or consequences that supported the decision. Review the assumptions behind the ADR; if the decision itself changes, preserve the old record and document the new choice in a linked, superseding ADR.
How do you know when an ADR is out of date?
An ADR does not become historically false just because the system or business changes. It becomes less useful for current decisions when the reasons for choosing an option may no longer apply. Microsoft Learn cautions that without justification, future stakeholders cannot evaluate whether a decision still fits as circumstances change. Microsoft’s ADR guidance therefore recommends maintaining records throughout a workload’s life.
Review an ADR when a relevant change raises a concrete question about its fit—not simply because a calendar reminder has arrived. Examples include:
- Business needs or functional requirements have shifted.
- Non-functional requirements, such as performance or availability expectations, have changed.
- System boundaries, constraints, costs, or available technologies have changed.
- The consequences or trade-offs of the chosen option now look different.
The GOV.UK framework recommends regularly reviewing ADRs for changes in context or consequences, while Google Cloud identifies evolving business needs, technical requirements, and available solutions as reasons to revisit a record. GOV.UK Architectural Decision Record Framework · Google Cloud Architecture Decision Records overview
#1 Best Overall
What assumptions should an ADR make visible?
Treat an assumption as a claim about the environment in which the team made its decision: for example, that a particular requirement will remain stable, a dependency will be available, or a constraint will continue to apply. Record the assumptions that materially shaped the choice, along with the context and rationale that make them understandable.
Useful ADRs commonly capture the decision’s context, options, relevant requirements, consequences, and trade-offs. GOV.UK also recommends including the title, date, status, consulted stakeholders, and links to supporting material. Microsoft guidance includes options, trade-offs, status, and confidence. These details let a future reader check whether the original reasoning still holds instead of guessing what the team meant.
Rank #2
Where helpful, state what evidence or change should prompt another look. Martin Fowler recommends recording confidence and changes in product context that should trigger reevaluation. This is a practical aid, not a universal scoring scheme: the useful triggers depend on the decision and its system. Martin Fowler’s Architecture Decision Record article
Should you edit an old ADR or write a new one?
Separate maintaining the record from changing its historical decision. A team can review an ADR and update its status or maintenance information without rewriting the accepted reasoning as if it had always been different. If the accepted decision changes, preserve the original and create a new ADR that supersedes it.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Clear out junk files and repair common Windows errorsFree Scan →Rank #3
This reconciles a difference in emphasis across published guidance: GOV.UK says to review and update ADRs, while Microsoft, AWS, Fowler, and BC PIES describe preserving accepted decisions and recording changes through linked superseding records. The practical point is to keep the history trustworthy while ensuring readers can find the current decision.
A new ADR should explain the new context, options considered, rationale, and consequences, and briefly say why the previous decision no longer holds. BC PIES states this directly: “In the new ADR, briefly explain why the old decision no longer holds (context or assumptions changed).” BC PIES Architecture Decision Records
A practical method for reviewing an ADR
This process applies the guidance above; it is not a formally standardized checklist.
- Read the original context and rationale. Identify the requirements, constraints, alternatives, trade-offs, and confidence that informed the choice. If the ADR does not record them, mark what is unknown rather than presenting a reconstruction as fact.
- Check the material assumptions against current evidence. Look for changes in requirements, business needs, system boundaries, costs, available technologies, and consequences. Connect each proposed change to the decision under review.
- Choose whether to retain, investigate, or supersede. Retain the decision if its assumptions still hold. If evidence is incomplete, record what needs validation. If the choice changes, write a new ADR with the current context, options, rationale, and consequences.
- Connect the records. Mark the old ADR as superseded, link the records where the repository allows, and note the change date, owner, and reason. AWS recommends preserving history, assigning ownership of changes, and marking replaced records superseded. AWS ADR best practices
- Keep the record findable. Store ADRs where the people who need them can access and use them—such as a versioned repository or a wiki—and keep them close to relevant workload documentation where practical. Microsoft and Google Cloud both discuss maintaining ADRs alongside workload documentation; AWS notes Git repositories and wikis as options.
How to compare options when a decision is being revisited
If there are multiple viable choices, compare them against the drivers that mattered in the original decision and the evidence available now. Depending on the system, relevant criteria may include functional and non-functional requirements, constraints, consequences, trade-offs, and how difficult the decision is to reverse. There is no universal ADR scoring matrix established by the cited guidance; choose criteria that explain this decision rather than scoring options against an unrelated template.
Recommended Free Tools
For record structure, AWS recommends capturing context, decision, consequences and trade-offs, status, and a changelog with the change date and responsible person. It also advises the project team to review an ADR at least once before acceptance. AWS ADR FAQ
Give ADRs an owner and a usable history
A decision log only helps if teams can locate it and understand its status. Assign responsibility for maintaining or changing records, preserve the links between decisions, and choose a location suited to the people who rely on them. AWS recommends ownership and regular review meetings; Microsoft advises beginning ADRs early and maintaining them through the workload’s life. Those practices support review without implying that every ADR needs the same review schedule.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
