For a materially changed accepted architectural decision, keep the original ADR’s decision content intact, approve a new ADR that records the replacement, then mark the original Superseded and link the two records. That preserves what the team decided and why, while making the current choice clear.
Should you edit an accepted ADR?
It depends on whether you are clarifying the record or changing the decision. The UK Government Digital Service (GDS) allows clarification of an existing ADR in some cases. It advises creating a new ADR when implementation of the original decision has begun and a different decision is needed. Microsoft and AWS recommend a stricter convention: treat accepted decisions as immutable and record a change in a new ADR. See Microsoft Learn, AWS Prescriptive Guidance, and GDS.
As an Amazon Associate I earn from qualifying purchases.
For a material change, the successor-record approach is the safer default: it preserves the original reasoning and leaves a traceable account of what changed. Limit edits to an old accepted ADR to lifecycle information, such as its status and a link to its successor, following your team’s version-control and records-retention rules.
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchHow to supersede an ADR
- Decide whether the choice has materially changed. A correction or clarification may not require a new decision record under your team’s policy. If the architectural choice itself is changing, create a successor ADR. Implementation of the original decision is a particularly useful point to consider: GDS recommends a new record when implementation has begun and the decision needs to change.
- Draft the successor using your team’s template. Explain what changed, state the new decision, capture the alternatives and tradeoffs that matter, and describe the consequences. Use the team’s established format so the new record fits the rest of the collection.
- Review and approve the successor first. Do not identify a proposed alternative as the replacement for the current accepted decision. AWS’s process describes approving the new ADR before updating the old ADR’s status; GDS advises adding the link to the new record once it is accepted.
- Update the old ADR’s lifecycle metadata. Mark it
Supersededand link to the accepted successor. Do not revise its original context, decision, options, or consequences to make them match the present architecture. - Link back from the successor. Add a
Supersedesfield or a clear prose link to the earlier ADR. Readers should be able to follow the chain in either direction. - Make both records discoverable. Keep ADRs with the system documentation or in the team’s version-controlled documentation repository. Maintain an index, log, or searchable view that shows each record’s status.
What to include in the replacement ADR
The new ADR should explain the decision well enough to stand on its own, without turning into a migration runbook. Include:
#1 Best Overall
- Title: the new architectural choice.
- Status and date: the lifecycle state and approval date, using the team’s convention.
- Context: what changed and why the previous choice no longer fits.
- Decision: the replacement choice and its scope.
- Options and rationale: relevant alternatives and the decision drivers behind the selection.
- Consequences: benefits, costs, migration work, and risks.
- Supersedes: a link to the earlier ADR.
- Related implementation material: links to migration plans or technical designs where useful.
Choosing a template and keeping the history navigable
For a concise record, Michael Nygard’s ADR template uses Title, Status, Context, Decision, and Consequences, with “superseded” among its example statuses. MADR provides more explicit space for options and decision drivers, which can help future readers understand why alternatives were rejected. Choose the format that captures the reasoning your team needs and apply it consistently. See Nygard’s ADR template and MADR.
Ordinary Markdown and version control are enough to keep the records; dedicated ADR tools are optional. If you evaluate one, check whether it fits your repository and Markdown workflow and can keep an index that exposes status and links. The ADR tools directory is a discovery list, not evidence that any particular tool is mature or best for your team.
Rank #2
Example status and links
The old ADR can receive a small lifecycle update such as:
Status: Superseded by ADR-0042
In ADR-0042, add a reciprocal reference such as Supersedes: ADR-0017. The identifiers here are illustrative; use your repository’s existing numbering and link conventions. Leave the earlier ADR’s historical rationale unchanged.
Quick Recap
Rank #4
Rank #3
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.
