Architecture Decision Record
A short, durable record of an architecturally significant decision, including its context, rationale, alternatives, status, and consequences.
Download Markdown (.md)Soroush’s Product Wiki · https://wiki.soroush.uk/topic/architecture-decision-record/
01What 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.[1][2][3]
- ProposedContext, constraints, options, and consequences are reviewable
- Accepted or rejectedAuthority records the choice and rationale
- ImplementedFollow-up work tests expected consequences
- DeprecatedThe decision no longer governs new work
- SupersededA linked ADR explains the replacement
New evidence may reopen the architectural question
Later records supersede earlier reasoning instead of erasing it, preserving the context and consequences visible at the time of the decision.
02Why 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.
03When 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.
04How it works
- Describe the decision-driving context, constraints, and quality requirements without arguing for a solution yet.
- List realistic options and compare their relevant benefits, risks, costs, and operational effects.
- Record the chosen option and a concise rationale tied to the stated context.
- State positive, negative, and uncertain consequences, including follow-up work or validation needed.
- Give the record a status such as proposed, accepted, rejected, deprecated, or superseded.
- Keep the ADR discoverable and link later records rather than erasing the historical decision.
05A 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.
06Where 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.
07Sources
- Documenting Architecture DecisionsCognitect · Original practitioner articleDocumenting Architecture Decisions
- Architectural Decision RecordsADR GitHub Organization · Community referenceArchitectural Decision Records
- Maintain an Architecture Decision RecordMicrosoft Learn · Institutional guidanceMaintain an Architecture Decision Record