# Architecture Decision Record

A short, durable record of an architecturally significant decision, including its context, rationale, alternatives, status, and consequences.

- Type: artifact
- Domain: Engineering & architecture
- Level: Foundational
- Last reviewed: 2026-09-22
- Original: [Soroush’s Product Wiki](<https://wiki.soroush.uk/topic/architecture-decision-record/>)

## What it means

An Architecture Decision Record, or ADR, documents one important design choice and why a team made it. A typical record states the decision context, options considered, selected option, expected consequences, and status. ADRs are usually lightweight text files stored near the system documentation or source code, where version history preserves how thinking changed.

## Why it matters

Code shows what a system does, but rarely explains why one database, integration style, deployment model, or security boundary was chosen. ADRs preserve that reasoning for future teammates, reviews, incident analysis, and later replacement decisions. They also make trade-offs visible before implementation, reducing repeated debates and architecture by folklore.

## When to use it

Create an ADR when a choice materially affects system qualities, cost, delivery, team boundaries, compliance, or future options. Use one for decisions that would be expensive or confusing to reverse. Skip routine implementation details that are local, low-risk, and easily changed without broader consequences.

## How it works

1. Describe the decision-driving context, constraints, and quality requirements without arguing for a solution yet.
2. List realistic options and compare their relevant benefits, risks, costs, and operational effects.
3. Record the chosen option and a concise rationale tied to the stated context.
4. State positive, negative, and uncertain consequences, including follow-up work or validation needed.
5. Give the record a status such as proposed, accepted, rejected, deprecated, or superseded.
6. Keep the ADR discoverable and link later records rather than erasing the historical decision.

## A practical example

A team expecting uneven traffic evaluates a managed queue, direct synchronous calls, and a self-hosted broker. Its ADR chooses the managed queue because delivery reliability and low operational staffing outweigh portability concerns. It records message-size limits, vendor dependency, retry policy work, and the metric that will trigger reconsideration.

## Where it breaks

An ADR captures reasoning at a moment in time; it does not prove that the decision is correct. Records become noise if every minor choice gets one, and they lose trust if statuses or consequences are never updated. Sensitive commercial or security details may require access controls or a sanitized companion record.

## Common mistakes

- Writing a victory speech for a preselected solution instead of comparing credible options.
- Recording only the decision while omitting context, trade-offs, and consequences.
- Editing away an obsolete decision rather than marking it superseded and linking its replacement.
- Storing ADRs where the people affected by the decisions cannot find or review them.

## Visualization

[View the visualization on the website](<https://wiki.soroush.uk/topic/architecture-decision-record/#visualization-architecture-decision-record>)

## Sources

1. [Documenting Architecture Decisions](<https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions>) — Cognitect · Original practitioner article
2. [Architectural Decision Records](<https://adr.github.io/>) — ADR GitHub Organization · Community reference
3. [Maintain an Architecture Decision Record](<https://learn.microsoft.com/en-us/azure/well-architected/architect-role/architecture-decision-record>) — Microsoft Learn · Institutional guidance

## Related topics

- [Non-Functional Requirements](<https://wiki.soroush.uk/topic/non-functional-requirements/>)
- [Evolutionary Architecture](<https://wiki.soroush.uk/topic/evolutionary-architecture/>)
- [Build vs. Buy](<https://wiki.soroush.uk/topic/build-vs-buy/>)
