View source for Architecture Decision Record

'''Architecture Decision Record''' ('''ADR''') is a concise, durable document that captures an architecturally significant decision, the circumstances and constraints that prompted it, the reasoning behind the chosen approach, and its expected consequences. A collection of ADRs forms an architecture decision log that helps teams understand why a system was designed in a particular way, including decisions that later become obsolete or are replaced.

ADRs are used in software engineering, [[Solution Architecture]], [[Enterprise Architecture]], and [[Cloud Architecture]]. They may document choices about data storage, integration, service boundaries, deployment, security, reliability, technology platforms, and other design matters with lasting implications. The goal is to preserve decision knowledge without reproducing a complete architecture specification. The widely used format associated with software architect Michael Nygard contains a title, status, context, decision, and consequences.<ref name="nygard">Architecture Decision Record community, ''Decision record template by Michael Nygard'', [https://adr.github.io/adr-templates/ ADR Templates], accessed 28 October 2026.</ref>

An ADR differs from an [[Architecture Document|architecture description]], which explains the overall structure of a system, and from a [[Request for Comments]] (RFC), which often solicits discussion before a decision. An RFC may lead to an ADR, while the ADR provides a short-lived or long-lived record of the outcome and its rationale, depending on how the project evolves.

== Purpose and value ==

Architecture decisions are often made under constraints involving time, funding, performance, security, organizational responsibilities, and available technology. A design may appear arbitrary to a future team when the original circumstances are no longer visible. ADRs address this loss of context by recording the choice and its tradeoffs near the time it was made.

Their common purposes include:
* Making the reasoning behind important design choices discoverable.
* Establishing a shared understanding among architects, developers, operations teams, and other stakeholders.
* Preserving alternatives considered and why they were rejected.
* Supporting design review and accountability without requiring lengthy documentation.
* Reducing repeated debates over decisions already examined.
* Making subsequent replacement or reversal of decisions traceable.
* Helping new team members understand the constraints embedded in an existing system.

A record does not prove that the decision was correct. Its value lies in making the assumptions, consequences, and decision authority open to examination. The UK Government Digital Service identifies ADRs as a way to preserve knowledge of design choices beyond their original discussions.<ref name="gds">UK Government Digital Service, ''Documenting architecture decisions'', [https://gds-way.digital.cabinet-office.gov.uk/standards/architecture-decisions.html The GDS Way], accessed 28 October 2026.</ref>

== Typical contents of an ADR ==

The format should remain concise, but sufficiently complete to allow a reader to reconstruct the decision. Organizations may adapt the template to their governance needs.

{| class="wikitable"
! Element
! What it records
! Why it matters
|-
| Identifier and title
| A stable number and a brief statement of the choice
| Enables references from code, issues, designs, and later ADRs
|-
| Status
| Proposed, accepted, rejected, deprecated, or superseded
| Establishes whether a decision is current and authoritative
|-
| Context
| Problem, business need, requirements, constraints, and assumptions
| Explains the forces shaping the decision
|-
| Options considered
| Credible alternatives, including retaining the current approach
| Shows that tradeoffs were examined
|-
| Decision and rationale
| Selected approach and reasons for choosing it
| Allows others to understand the intended design direction
|-
| Consequences
| Expected benefits, drawbacks, risks, costs, and new obligations
| Makes tradeoffs and follow-up work visible
|-
| Ownership and date
| Decision participants, authority, and decision date
| Supports governance and later review
|-
| Links and review triggers
| Related ADRs, evidence, implementation work, and conditions for reconsideration
| Maintains history and continuity
|}

The original Nygard-style record is intentionally smaller than many expanded templates. The Markdown Architectural Decision Records (MADR) approach makes options and their advantages and disadvantages more explicit. Different formats can serve the same purpose when they preserve the decision and the logic that supports it.<ref name="templates">Architecture Decision Record community, ''ADR Templates'', [https://adr.github.io/adr-templates/ template overview], accessed 28 October 2026.</ref>

== Which decisions should be recorded? ==

An ADR is appropriate when a choice is significant enough that future teams may need to know why it was made. Common triggers include:
* Selecting a database, messaging mechanism, hosting model, or architecture pattern.
* Establishing service boundaries or major integration contracts.
* Making consequential security, identity, privacy, or data-residency tradeoffs.
* Choosing a resilience, recovery, or deployment architecture.
* Accepting a difficult-to-reverse dependency or technology constraint.
* Changing an earlier architectural choice.

Routine code-level choices that have little architectural significance generally do not require an ADR. The practical test is whether the decision materially affects system structure, quality attributes, long-term cost, operational risk, or future options. Microsoft recommends recording decisions that affect system structure, key quality attributes, or reversibility, while keeping records short and factual.<ref name="microsoft">Microsoft, ''Maintain an architecture decision record (ADR)'', [https://learn.microsoft.com/en-us/azure/well-architected/architect-role/architecture-decision-record Azure Well-Architected Framework], updated 13 April 2026.</ref>

The significance of a choice depends on context. A small configuration setting can warrant an ADR when it has consequences for safety, compliance, or enterprise interoperability. A widely discussed technology preference may not warrant one if it has no material impact on the system.

== ADR lifecycle ==

=== Proposal ===

A contributor identifies a significant design question, describes the relevant context, and proposes an approach. A proposed ADR may be circulated through code review, architecture review, or a designated consultation process. The organization should distinguish proposed content from a decision that has actually been accepted.

=== Review and decision ===

Affected stakeholders assess alternatives against the intended outcomes and constraints. Review participants may include architects, engineers, security specialists, product owners, service operators, data stewards, and representatives of business processes affected by the choice. The decision authority should be proportionate to the risk and organizational scope.

=== Acceptance and implementation ===

When the authorized decision is accepted, the ADR records the chosen approach and its consequences. Related design documents, implementation tickets, code repositories, and operational procedures can link to the record. Acceptance does not by itself prove implementation; teams should be able to identify outstanding work and whether the deployed system follows the decision.

=== Supersession and historical continuity ===

A later decision may replace an accepted ADR. A common practice is to retain the original, mark it as superseded, and link it to the new record. This preserves the historical sequence instead of rewriting past reasoning to match the current architecture. The GDS guidance describes a superseded state and links from the prior decision to its replacement.<ref name="gds" />

Organizations may have additional states, including deprecated or rejected, but the meaning of each should be defined consistently. A rejected proposal is not equivalent to an accepted design later superseded by new information.

== ADR governance and ownership ==

ADRs usually work best when authorship and approval are close to the teams implementing the architecture, with higher-level review reserved for decisions that cross enterprise boundaries or affect material risk. An architect may facilitate the decision record, while an accountable service or product owner authorizes the business tradeoffs.

Governance should define who can propose records, which decisions require review, where ADRs are stored, how acceptance is recorded, and when supersession is mandatory. Teams should also clarify the relationship between local workload decisions and enterprise standards. A team-level ADR cannot automatically override an organization-wide security policy or architecture principle.

A useful governance pattern records the minimum evidence needed for a meaningful decision, rather than imposing a large committee process on every choice. For consequential decisions, review should include those who own the resulting security, reliability, operating, financial, and integration obligations.

== Storage, discovery, and traceability ==

ADRs can be kept in a version-controlled repository alongside source code, in a project documentation system, or in a governed architecture knowledge base. The chosen location should support stable identifiers, readable history, search, and links between related decisions. Microsoft's Azure architecture guidance recommends keeping ADRs readily accessible with workload documentation.<ref name="microsoft" />

Common relationships include:
* A system or workload that is governed by the decision.
* The architectural requirement or constraint that motivated it.
* Related diagrams and design specifications.
* The change request, project, or implementation work that realizes it.
* An earlier ADR superseded by the new one.
* Evidence from tests, incidents, audits, or operational experience.

A decision log becomes less useful if records are scattered across repositories without an index or stable references. Teams should ensure that affected parties can find the current accepted decision and navigate its history.

== Example of an architecture decision record ==

Consider a hypothetical enterprise application that needs to exchange order events with several downstream systems. Its existing synchronous interfaces create tight dependencies and repeated failures during peak demand.

{| class="wikitable"
! ADR field
! Illustrative content
|-
| Title
| Use asynchronous events for downstream order notifications
|-
| Status
| Accepted
|-
| Context
| Synchronous calls delay order completion when a downstream service is unavailable; consumers require eventual notification rather than immediate confirmation
|-
| Alternatives
| Retain synchronous calls with retries; introduce a message broker; adopt a managed event service
|-
| Decision
| Publish durable order events through the approved managed event service, with unique event identifiers and consumer retry handling
|-
| Consequences
| Lower coupling and improved fault isolation; additional monitoring, event-versioning, replay, and delivery-consistency responsibilities
|-
| Review trigger
| Reassess if delivery guarantees, latency requirements, or regulatory data constraints materially change
|}

This record would link to the service design, integration contracts, test results, and implementation work. It would not replace the full event schema or operational runbook. The example illustrates the distinction between documenting a choice and specifying all the engineering details needed to implement it.

== ADRs and other architecture artifacts ==

{| class="wikitable"
! Artifact
! Main question answered
! Relationship to an ADR
|-
| Architecture decision record
| What was decided and why?
| Preserves rationale and consequences of an individual choice
|-
| Architecture description
| How is the system structured?
| Describes components, relationships, views, and relevant constraints
|-
| Architecture principles
| Which broad rules guide design choices?
| Influence or constrain individual ADRs
|-
| Request for comments
| What proposal should stakeholders consider?
| Can support consultation before formal acceptance
|-
| Technical specification
| How will a component or interface work?
| Provides detailed implementation design
|-
| Risk assessment
| What could go wrong, and what treatment is appropriate?
| Supplies evidence for decisions involving material risks
|}

An ADR may refer to each of these artifacts, but should not absorb their entire contents. Keeping the record concise makes the reasoning easier to discover and maintain.

== Benefits and limitations ==

ADRs improve continuity, transparency, and architectural knowledge transfer when they are consistently used. They can clarify why a team adopted a complex design, why a seemingly simpler option was rejected, or why a temporary compromise remains in place.

However, the approach has limitations. A record may contain hindsight bias if written long after a decision. An accepted ADR can describe intentions that were never implemented. Excessive detail may discourage adoption; too little context can make the record unhelpful. A large collection can become stale unless superseded decisions are clearly marked and discoverable.

There is also a governance risk when the existence of an ADR is mistaken for proof that a decision was adequately challenged. The review process, evidence quality, and authorization matter independently of documentation completeness.

== Common mistakes ==

'''Writing ADRs only after problems occur.''' The original constraints and reasoning may be lost or reconstructed inaccurately.

'''Documenting routine decisions indiscriminately.''' Excessive records increase maintenance burden and obscure the choices that matter.

'''Leaving alternatives unexplained.''' Future teams cannot understand whether a different option was considered or merely overlooked.

'''Replacing old records in place.''' Historical decisions and the sequence of change become hard to reconstruct.

'''Ignoring implementation evidence.''' Accepted decisions may not match the architecture actually deployed.

'''Confusing the ADR with a design specification.''' Detailed technical instructions can bury the decision itself.

'''Failing to define approval authority.''' Teams may disagree over whether a proposed record constitutes an authorized architectural decision.

== See also ==

* [[Enterprise Architecture]]
* [[Solution Architecture]]
* [[Cloud Architecture]]
* [[Software Architecture]]
* [[Architecture Governance]]
* [[Architecture Principles]]
* [[Technical Debt]]
* [[IT Governance]]

== References ==

<references />