Architecture Decision Records: Preserve the Why

TL;DR

An Architecture Decision Record (ADR) is a small, durable record of one architecturally significant decision: its context, alternatives, chosen direction, and consequences.

Its value is preserving why this choice made sense under these constraints, so future engineers can distinguish intentional architecture from accidental legacy.

Know when an ADR is worth writing

Do not write one for every code edit. Write one when reversing the choice later would be expensive, risky, cross-cutting, or coordination-heavy.

Typical triggers include deployment topology, data ownership, integration contracts, consistency models, security or availability strategy, and frameworks that constrain many future components.

That is what architecturally significant means: the decision shapes future choices.

Capture context before the answer

Useful context includes the business goal, scope, current architecture, constraints, quality attributes, operational limits, assumptions, and evidence such as incidents, metrics, benchmarks, or experiments.

If context only says “we need a better architecture,” the ADR cannot explain why the decision was rational.

Compare real alternatives

Record options that were seriously considered, not fake alternatives added after the fact.

For each viable option, capture meaningful trade-offs. Link evidence when it matters: benchmark results, incident reports, cost estimates, proof-of-concept findings, or capacity data.

State the decision plainly

Prefer an explicit statement:

We will publish OrderConfirmed from Ordering to Billing. Billing owns its projection and will not read Ordering tables directly.

Avoid vague language such as “we should probably move toward events.”

A useful ADR identifies the decision owner or decision-makers, date, affected scope, and relevant stakeholders.

Record consequences, not only benefits

Every decision creates a new operating context. Record positive, negative, and neutral consequences.

For the event-contract example, independent private schemas improve, while at-least-once delivery, eventual consistency, schema compatibility, consumer lag, and recovery become explicit responsibilities.

An ADR that lists only advantages is advocacy, not a decision record.

Use a lifecycle

Common statuses are Proposed, Accepted, Rejected, Deprecated, and Superseded. The vocabulary may vary; readers must still be able to tell whether an ADR is current truth.

Preserve history: supersede, do not rewrite

Once an ADR is accepted, preserve the historical decision. If context changes, create a new ADR that references the old one and mark the old ADR superseded.

The old ADR may explain years of code, schema, infrastructure, and incidents. Rewriting it to match today's architecture destroys that explanation. Keep it in the decision log.

Keep the template lightweight

A practical template can stay small:

# ADR-0042: Publish order events to Billing
Status: Proposed
Date: 2026-09-12
Decision owner: Checkout Platform
Scope: Ordering ↔ Billing

## Context
Problem, constraints, evidence, assumptions.

## Options considered
Viable alternatives and trade-offs.

## Decision
What we will do.

## Consequences
Benefits, costs, risks, responsibilities.

## Links
Experiments, incidents, diagrams, tickets, related ADRs.

Add fields only when they improve decisions. A template that takes hours to complete will be bypassed.

Use a practical review workflow

1. Trigger: identify a significant choice.
2. Draft: an owner records context, options, evidence, and a proposed decision.
3. Review: engineers and stakeholders challenge assumptions and consequences.
4. Decide: accept, reject, or keep proposed for more work.
5. Link implementation: connect PRs, migrations, diagrams, or runbooks.
6. Enforce: use design and code review to catch violations of accepted ADRs.
7. Revisit: when context materially changes, create a new ADR and supersede the old one.

Review scope should match decision blast radius; not every ADR needs a large governance meeting.

Production scenario

A commerce platform once let Billing read Ordering's shared tables. After incidents and ownership conflicts, the teams moved to an event contract, but nobody recorded the rationale or constraints.

Two years later, a new team sees event lag and proposes “simplifying” Billing by reading Ordering tables again. The old design looks cheaper because the incidents, ownership conflicts, and accepted consistency trade-offs are invisible.

Impact: the team repeats an old debate, spends weeks rediscovering constraints, and risks reintroducing cross-team data coupling.

Root cause: implementation changed without a durable decision record. Commits show what changed, but not the context, rejected alternatives, evidence, or consequences that justified it.

Correct pattern: create an ADR around the architectural change; record context, options, evidence, decision, consequences, owner, date, and scope; review it with affected stakeholders; link implementation artifacts; and when later evidence changes the answer, create a new ADR that supersedes the old one instead of rewriting history.

Production checklist

• The choice is architecturally significant enough to deserve an ADR.
• Context states problem, scope, constraints, assumptions, and evidence.
• Real alternatives are listed with meaningful trade-offs.
• The decision is explicit rather than aspirational.
• Consequences include costs and operational responsibilities.
• Status shows whether the ADR is proposed, accepted, rejected, deprecated, or superseded.
• Owner or decision-makers, date, scope, and stakeholders are identifiable.
• Important evidence and implementation artifacts are linked.
• Accepted ADRs are referenced during review when relevant.
• Superseded ADRs remain in the decision log and point to replacements.
• The template remains lightweight enough to use consistently.
• Changed context triggers a new decision instead of silent drift.

Agent rule

When a change makes an architecturally significant choice, capture the forces and alternatives before implementation hardens the answer; record one explicit decision with its consequences, then preserve that history and supersede it only through a new ADR when context changes.

Sources

• Michael Nygard — Documenting Architecture Decisions
• ADR GitHub organization — Architectural Decision Records
• ADR GitHub organization — MADR template
• AWS Prescriptive Guidance — ADR process
• AWS Prescriptive Guidance — ADR best practices