ADR Deprecation: When to Retire or Keep an ADR

An Architecture Decision Record (ADR) should be deprecated or superseded when a new decision directly contradicts or replaces the context and consequences of the original, and left unchanged when the decision still holds true even if the surrounding technology has evolved. This article explains the precise triggers for deprecation, supersession, and retention, with practical guidance for keeping your ADR set honest and useful.

What Is an ADR and Why Does Its Status Matter?

An Architecture Decision Record (ADR) is a short document that captures a single architectural decision, including its context, the decision itself, and its consequences. ADRs were popularized by Michael Nygard in 2011 as a lightweight way to record design choices without heavy documentation. Teams use them to preserve institutional memory, onboard new engineers, and avoid rehashing the same debates.

The status of an ADR—whether it is accepted, deprecated, or superseded—tells readers whether they can trust it as a current guide. A stale ADR that looks active can lead a developer to implement an obsolete pattern. A deprecated ADR that is still referenced can cause confusion. Getting the status right is not bureaucratic; it is a communication act.

When to Leave an ADR Unchanged

The default action for any ADR is to leave it unchanged. An ADR should only be touched when the decision it records is no longer the best guide for new work. Many teams make the mistake of updating ADRs whenever the codebase changes, but that conflates implementation details with architectural decisions.

Leave an ADR unchanged when:

The decision still holds, even if the specific libraries or tools have been upgraded.
The context has changed but the decision remains the best option under the new circumstances.
The ADR is historical and you want to preserve the reasoning at the time, even if you would decide differently today.
No new decision has been made that directly contradicts it.

For example, an ADR that says “use PostgreSQL as the primary database” should remain unchanged even after you upgrade from PostgreSQL 12 to 16. The decision is about the database system, not the minor version. Similarly, an ADR about using REST for public APIs might remain valid even after you introduce GraphQL for one internal service, as long as the public API still uses REST.

When to Deprecate an ADR

Deprecation means the ADR is no longer recommended for new work, but it is not replaced by a single new decision. This often happens when a decision becomes obsolete due to external factors, or when a whole area of the architecture is being phased out.

Deprecate an ADR when:

The technology or approach is no longer supported by the vendor or community (e.g., a library that is end-of-life).
The decision was a temporary stopgap that has served its purpose and is now being removed.
The ADR covers a component that is being retired or replaced by a completely different system, and no single new decision covers it.
The decision is still in effect for existing code but should not be applied to new code (e.g., “use SOAP for the legacy integration” while new integrations use REST).

When you deprecate an ADR, you should add a short note explaining why it is deprecated and what to use instead, if anything. For example: “Deprecated 2024-06-01: The legacy payment gateway is being decommissioned. New integrations should use the new payment service ADR-042.” This preserves the history while clearly signaling that the old decision is not a guide for the future.

When to Supersede an ADR

Supersession is the most common status change. It happens when a new decision directly replaces an old one. The old ADR is not wrong historically, but it is no longer the current decision.

Supersede an ADR when:

A new ADR explicitly reverses the previous decision (e.g., “we are moving from monolith to microservices” supersedes “we will use a monolith”).
The context has changed so fundamentally that the original decision no longer applies, and a new decision has been made.
A new ADR covers the same topic with a different outcome, and keeping both as “accepted” would create ambiguity.

When you supersede an ADR, you should link the new ADR to the old one. The old ADR should have a status of “superseded by ADR-123” and the new ADR should reference what it supersedes. This creates a clear lineage that helps readers trace the evolution of the architecture.

For example, a team might have ADR-010 “Use MySQL for the primary database” and later decide to move to a distributed SQL database like CockroachDB. ADR-020 “Use CockroachDB for the primary database” supersedes ADR-010. ADR-010 is not deprecated—it is still a valid historical record—but it is no longer the current decision.

How to Choose Between Deprecate and Supersede

The key difference is whether there is a single new decision that replaces the old one. If yes, supersede. If no, deprecate. Here is a simple test:

Is there a new ADR that says “we now do X instead of Y”? If yes, supersede.
Is the old decision simply no longer relevant, with no direct replacement? If yes, deprecate.
Is the old decision still true for a subset of the system? If yes, leave it unchanged, or deprecate if you want to discourage new usage.

Sometimes the choice is ambiguous. For example, an ADR that says “use Angular for the frontend” might be superseded by “use React for new frontend projects” if the team is standardizing on React. But if the team is moving to a micro-frontend architecture where each team chooses its own framework, the old ADR might be deprecated because there is no single new decision.

Common Mistakes and Best Practices

One common mistake is updating an ADR to reflect a change in implementation. For example, changing “use Redis for caching” to “use Memcached for caching” because you switched libraries. This is not an architectural decision change—it is a tactical swap. Instead, you should leave the ADR unchanged and note the change in the codebase or a separate changelog.

Another mistake is deleting ADRs. Never delete an ADR. Even if the decision is completely obsolete, the record has historical value. Future engineers may wonder why the system looks the way it does, and the ADR provides the answer. Deprecate or supersede, but do not delete.

Best practices for ADR status management:

Review ADRs periodically (e.g., during architecture reviews) to check if any are stale.
Use a consistent status vocabulary: proposed, accepted, deprecated, superseded.
Always add a date and a reason when changing status.
Link related ADRs to create a decision graph.
Make the status visible in the ADR title or header, not just in a metadata field.

Frequently Asked Questions

Can an ADR be both deprecated and superseded?

No. Deprecated means there is no replacement; superseded means there is a specific replacement. If there is a replacement, use superseded. If not, use deprecated. Using both would confuse readers.

Should I update an ADR if the technology version changes?

No. An ADR records the decision, not the version. If the decision is still valid, leave it unchanged. If the version change alters the decision (e.g., a major version changes the architecture), then you may need a new ADR that supersedes the old one.

How long should an ADR stay “accepted”?

There is no time limit. An ADR stays accepted until it is superseded or deprecated. Some decisions may remain valid for years. The age of an ADR is not a reason to change its status.

What if a new decision partially contradicts an old one?

If the new decision only affects a subset of the old decision’s scope, you may need to create a new ADR that covers the new decision and note that it partially supersedes the old one. In that case, you can mark the old ADR as “partially superseded” if your tooling supports it, or simply leave it unchanged and add a note.

Who is responsible for deprecating or superseding an ADR?

Typically the same person or group that owns the architecture—an architect, a tech lead, or the team that made the original decision. It is a good practice to have a designated ADR owner who reviews and updates statuses.

Can I deprecate an ADR that is still in use?

Yes. You might deprecate an ADR to indicate that the approach is no longer recommended for new work, even though existing code still uses it. This is common when a technology is being phased out.

Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.

More cards in this drawer

The whole Numbers and Powers drawer →