Skip to content

Software Quality

Architecture Decision Records

An Architecture Decision Record is a short document that records one architectural decision. In a page or two it carries the context in which the decision was taken and the consequences accepted. Michael Nygard named the format in 2011 (Nygard 2011)1. ADRs are not verification: they don't catch bugs. The dimension they serve is maintainability, and the failure mode they address is decision rot — nobody remembers why the system is shaped the way it is, so every change risks re-litigating a settled question or breaking a critical assumption nobody documented.

What ADRs capture

  • Lost rationale. Six months after the decision, the ADR explains why the team chose Postgres over DynamoDB. Without it, the same debate restarts.
  • Hidden constraints. "We can't use streaming responses because the upstream gateway buffers" is the kind of fact that is invisible in code but central to the next refactor.
  • Stakeholder context. Legal said no to storing IPs. Procurement vetoed the SaaS vendor. These constraints leave no trace in the codebase but shape it heavily.
  • Trade-offs accepted. Knowing that "we chose simplicity over flexibility" lets a future engineer recognize when the trade-off has inverted.
  • Reversal cost. An ADR that says "switching to async messaging is a six-week project" is the input to a realistic estimate two years later.

What ADRs do not catch: implementation bugs, drift between the decision and the code, decisions that were never written down. The discipline depends on the team writing one whenever an architectural decision is made; tools cannot enforce this.

The standard shape

# <Title — one sentence>

## Status
Proposed | Accepted | Deprecated | Superseded by <link>

## Context
What is the issue we are seeing that is motivating this decision
or change?

## Decision
What is the change we are actually making?

## Consequences
What becomes easier or harder to do because of this change?

Variations exist (MADR, Y-statements) but the four sections — Status, Context, Decision, Consequences — are the essential minimum.

Tools

The discipline is markdown and git; no dedicated tool is required.

When to use, when not

Use:

  • For any decision a future engineer might second-guess. Architecture, data-store choice, framework, deployment shape, authentication model, multi-region strategy, build system.
  • For critical trade-offs accepted under constraint. "We chose X because Y was unavailable at the time."
  • For decisions imposed by stakeholders outside engineering. Legal, compliance, procurement, finance.
  • As a routine PR-time artifact for any change large enough to warrant a design review.

Don't:

  • For every code-level decision. ADRs are about architecture; small-grained design choices live in code comments or commit messages.
  • As a substitute for writing the code. ADRs are durable rationale, not specifications.
  • Without numbering. Numbered files let a later decision reference an earlier one; date-only file names collide.
  • Without keeping them in the repo. ADRs in a wiki rot faster than the code; in-repo ADRs ship with the system.

Evidence

ADRs are too heterogeneous to study as one artifact, and the counterfactual ("would the team have rotted faster without them?") can't be measured cleanly. The case is definitional, not empirical: a decision recorded with its rationale doesn't have to be re-derived later.

Classification

  • Quality dimensions: Maintainability.
  • Area: Documentation discipline for long-lived codebases, team decision trails, onboarding artifacts.

Referenced by

References

  1. Nygard, Michael. 2011. Documenting Architecture Decisions. https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions. ↩