Template

Keep the old decision when you replace it

Deleting the old rationale makes the past look less reasonable than it was.

About 1 min read

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.

Keep reading

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.

Use email
Keep exploring

Connected ideas

You are readingKeep the old decision when you replace it

Evidence and sources
Supports

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.

Read this idea as JSON · Release details