Skip to main content

Why Decisions Need to Be Recorded

What This Concept Is​

Recording an architecture decision captures not just what the team picked but why, under what conditions, and what was given up. A recorded decision has four jobs:

  1. Memory. Preserve the reasoning beyond the tenure of the people who made it.
  2. Onboarding. Give new engineers a way to reconstruct current shape of the system without interviewing veterans.
  3. Governance. Give reviewers and auditors something concrete to evaluate instead of tribal lore.
  4. Drift defense. Give the team a reference to check against when implementation starts diverging from intent.

A decision that lives only in the heads of people who were in the meeting is, by definition, not a decision the system can defend.

Why It Matters Here​

Every later concept assumes decisions are visible. You cannot review a decision you cannot read. You cannot supersede one that does not exist in the record. Fitness functions become explanations of claims that an ADR should already have made. Architectural drift is defined as "implementation moves away from the recorded decision"; with no record, there is no drift, only erosion.

The motivating failure mode: a team picks a message broker in 2022, the three people who argued for it leave in 2024, and in 2026 a new engineer is told "we use this because Alice liked it." That is not governance, it is folklore.

Concrete Example​

Compare two states of the same team, two years after a decision.

No ADR:

"Why do we use Kafka?" "I think Mark set it up. He's at another company now." "What happens if we want to switch?" "I don't know, probably a lot."

With ADR:

Reader opens library/raw/adr/0007-event-transport.md:

  • Context: four services produce high-volume order events; analytics and fraud both subscribe; we need at-least-once delivery and multi-day replay.
  • Decision: Kafka with 7-day retention, partition by order_id.
  • Consequences: operational burden of running Kafka; hard dependency on replay for analytics; cannot drop retention below 7 days without breaking fraud's recovery process.
  • Status: Accepted 2024-01-15.

Now the reader can argue with the reasoning, not just the conclusion. If retention is expensive and fraud no longer needs 7 days, the path forward is clear: supersede this ADR.

Common Confusion / Misconception​

"ADR as status report." An ADR is not "what the team did last week." It captures a decision point. If there was no real choice, no alternative, no tradeoff - there is nothing to record.

"The ADR is for compliance." Compliance is a side effect. The real audience is the future engineer who will look at a line of code and ask "why is this like this?" If an ADR reads like a checkbox, that engineer gets nothing.

"Write it after shipping." By then the reasoning has rotted. Write before or during the decision so alternatives and counterarguments are still fresh.

How To Use It​

A decision becomes a recorded decision when it has:

  1. A durable location (repo-tracked, linkable, numbered).
  2. The alternatives that were actually considered - not invented afterward.
  3. The constraints that made this option win.
  4. At least one consequence that makes a future reader uncomfortable (otherwise, you have hidden the real tradeoff).

Treat the record as prospective: someone will read this in 2 years, angry or confused, and will use it to decide whether to change course. Write for that reader.

Check Yourself​

  1. For a decision your team made last quarter, write a one-paragraph "why" from memory. Then ask a teammate to do the same without seeing yours. Compare - are the reasons even the same?
  2. What makes an ADR harder to write before shipping than after? What does that difficulty protect you from?
  3. Name one decision that would be unsafe to record (trade secret, security posture, etc.). How should that be handled?

Mini Drill or Application​

Pick one long-running architectural choice in your system (cache strategy, auth provider, deploy model, etc.) whose ADR does not exist. Write a retrospective ADR in under 30 minutes:

  • Status: Accepted (retroactive, YYYY-MM-DD)
  • Context: what forced the decision; what alternatives were on the table
  • Decision: the actual choice, in one or two sentences
  • Consequences: at least one positive, one negative, one thing you would revisit

If you cannot reconstruct the context without interviewing someone, log that as a finding. The inability to recover the reasoning is the symptom this practice addresses.

Read This Only If Stuck​