Template
Keep the old decision when you replace it
Deleting the old rationale makes the past look less reasonable than it was.
When it fits
- A technical choice is changing and future readers will need to understand both versions.
When to avoid it
- An architecture decision record is not a diary for every minor edit. Preserve confidential details only in approved locations and correct factual errors transparently.
A template to use
Decision: [choice]. Context and constraints: [context]. Status: [status]. Consequences and trade-offs: [effects]. Replaces or is replaced by: [link].
Why it matters
Keep a short decision record with the forces present at the time, the choice and its consequences. When a new decision replaces it, mark the old record as superseded and link the replacement. Preserve history without presenting an obsolete choice as current guidance.
An example
A team replaces a batch interface with an event-based one. The earlier record retains the volume and platform constraints that originally justified batching.
Check your result
A reader can identify the current decision and explain why the earlier one existed.
Keep this limit in mind
- An architecture decision record is not a diary for every minor edit. Preserve confidential details only in approved locations and correct factual errors transparently.
Connected ideas
Useful withTrace a requirement to the reason and test that justify it
Evidence and sources
Nygard's architecture decision records preserve context, decision, status and consequences, retaining superseded decisions with a reference to their replacement.
An ADR records a decision and its rationale, not proof that the decision was correct or remains suitable.
Documenting Architecture Decisions · Format; Status; Consequences