Template
Keep the old decision when you replace it
Deleting the old rationale makes the past look less reasonable than it was.
Before you use it
- Use when
- A technical choice is changing and future readers will need to understand both versions.
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.
An idea to explore.
Try this idea.
Inspect the example, try the idea in your situation, then check your next move.
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.
Save and practise this idea
My learning
Read. Recall. Repeat.
Save this idea and return to it on any device.
Keep exploring
Connected ideas
You are readingKeep the old decision when you replace 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
All sources (1)
Edition and review
Version 0.1.0
No review details are supplied for this edition.