# 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)[^nygard2011]. 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

- [Maintainability](https://quality.stereobooster.com/maintainability.md) · Quality dimensions
- [Quality dimensions](https://quality.stereobooster.com/quality-dimensions.md) · Quality dimensions
- [Refactoring practice](https://quality.stereobooster.com/refactoring-practice.md) · Methods
- [AI tooling for requirements engineering](https://quality.stereobooster.com/ai-requirements-tools.md) · AI
- [How AI fits into software quality](https://quality.stereobooster.com/ai.md) · AI

## References

[^nygard2011]: Nygard, Michael. 2011. *[Documenting Architecture Decisions](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions)*. <https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions>.

## Acronyms

- ADR — architecture decision record
- MADR — Markdown Any Decision Records