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.

An ADR differs from an 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.

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.

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.

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.

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.

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.

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.

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

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