ADR Status and Lifecycle
You'll learn: how ADRs move through different states and how to link related decisions together as your architecture evolves.
Understanding ADR States
An ADR isn't static—it evolves as your system changes. Just like a document in a legal system, an ADR has a lifecycle that reflects its current relevance and authority.
The typical states are:
- Proposed: The decision is under discussion, not yet finalized
- Accepted: The team has agreed and implementation is underway or complete
- Deprecated: The decision is no longer recommended but may still be in use
- Superseded: A newer ADR has replaced this one entirely
Think of it like traffic laws: a proposed law is being debated, an accepted law is enforceable, a deprecated law is discouraged but technically valid, and a superseded law has been officially replaced by a new one.
Managing the Lifecycle
When you first create an ADR, mark it as Proposed. Once the team reaches consensus and commits to implementation, update it to Accepted.
As your system evolves, you might realize an earlier decision no longer fits. Rather than deleting the old ADR (which erases valuable history), you:
- Create a new ADR with status Proposed or Accepted
- Update the old ADR's status to Superseded
- Add a reference linking them: "Superseded by ADR-042" and "Supersedes ADR-019"
For decisions that are outdated but not completely replaced, use Deprecated with a note explaining why it's no longer recommended.
Linking Related Decisions
Always link ADRs that relate to or modify each other. This creates a decision graph showing how your architecture thinking evolved over time. When someone asks "Why did we do this?" they can trace the entire chain of reasoning.
Key Takeaway: ADR statuses (proposed, accepted, deprecated, superseded) track a decision's lifecycle, and explicit links between ADRs preserve your architectural reasoning as a connected history rather than isolated snapshots.