Decisions Evolve Over Time
Architectures are not static. A good decision made three years ago might be a poor decision today because technology matured, the team grew, scale increased, or business requirements shifted. The PostgreSQL choice that was perfect for 1,000 users might buckle under 10 million. The self-hosted CI system that saved money in 2020 might be a liability in 2025.
We manage this evolution using the Status field in the ADR header. The key principle is: you never delete or rewrite an old ADR. Instead, you change its status and create new ADRs that reference it.
Common Statuses:
| Status | Meaning | What happens to the document |
|---|---|---|
| Proposed | A draft decision awaiting team review and agreement. | Open for comments and changes. |
| Accepted | The current, active decision the team follows. | Immutable from this point forward. |
| Superseded | Replaced by a newer decision. | Add a note: "Superseded by ADR-0012" with a link. |
| Deprecated | No longer applicable, but not replaced by anything specific. | Add a note explaining why it's deprecated. |
| Rejected | Proposed but ultimately not chosen after discussion. | Keep it! Document why it was rejected. |
Why keep Rejected ADRs? This is counterintuitive but extremely valuable. Rejected ADRs prevent a destructive cycle: someone proposes an idea, it gets rejected after lengthy debate, six months later a new team member proposes the same idea, and the entire debate repeats. A Rejected ADR with clear reasoning short-circuits this loop. The new team member reads it and either accepts the reasoning or — if circumstances have genuinely changed — writes a new proposal that explicitly addresses why the old rejection no longer applies. This transforms a rejected idea from a dead end into a documented learning.
Supersession chains are how you trace architectural evolution. For example:
- ADR-0003: Use Jenkins for CI → Status: Superseded by ADR-0011
- ADR-0011: Migrate CI from Jenkins to GitHub Actions → Status: Accepted
Reading these two documents in sequence tells the complete story: what was chosen, why, what changed, and what replaced it. This chain is the architectural equivalent of a Git blame — it shows not just the current state but the full history of how you got there.
Key Point: The discipline of never deleting ADRs — even rejected ones — creates an institutional memory that survives team turnover. In organizations with high attrition, this chain of records becomes one of the most valuable assets the engineering team owns. It's the difference between "we don't know why it's this way" and "here's the exact reasoning, and here's what changed." Teams that maintain clean supersession chains can onboard new engineers in hours rather than weeks, because the entire decision history is readable in chronological order.