Every large system runs on hundreds of decisions made quietly: why the API gateway sits where it does, why the team chose one message broker over another, why data is replicated across two regions and not three. The code remembers the what. The design documents, if they exist, describe the how. But the why — the reasoning, the trade-offs weighed, the alternatives rejected — evaporates the moment the meeting ends or the architect moves on. Six months later, a new team member asks “why do we do it this way?” and the answer is a shrug, a vague memory, or a costly re-debate of a question the organization already answered once.

Architecture decision records, usually called ADRs, fix this. An ADR is a short, dated document that captures a single significant technical decision: the context that made it necessary, the options considered, the choice made, and the consequences accepted. Individually, each record is small. Together, they form a living history of how the architecture came to be — a resource that makes onboarding faster, reviews sharper, and governance real rather than ceremonial.

What an ADR is (and is not)

An ADR is a decision log entry for software architecture. It answers three questions in permanent form: what did we decide, why did we decide it, and what did we know at the time. The scope is deliberately narrow — one decision per record — and the format is deliberately brief. Most ADRs fit on a single page.

It is not a design document. A design document describes a solution in detail: components, interfaces, data flows, diagrams. An ADR explains why that solution was chosen over the alternatives. Engineers consult design documents to build; they consult ADRs to understand, challenge, or safely change what was built.

It is also not a standards document or a policy. Standards tell teams what to do. ADRs tell teams what was decided and why. A standard might say “all services must expose health checks.” An ADR records the decision to adopt that standard, the incident or analysis that motivated it, and the options that lost. When a team later questions the standard, the ADR supplies the reasoning instead of forcing another round of debate.

Finally, an ADR is not a committee memo or a change-request form. The best ADRs are written by the person or team closest to the decision, close to the time the decision was made, in plain language.

Anatomy of a good ADR

Most organizations converge on a handful of common sections. The exact headings matter less than the discipline of covering each one.

Title and status. The record starts with a numbered title and a status: proposed, accepted, superseded, deprecated, or rejected. Status is the most important field after the decision itself, because it tells the reader whether the decision is still in force.

Context. What problem was being solved, and what constraints shaped the decision? This section should be factual and time-bounded: the load characteristics at the time, the team structure, the regulatory environment, the budget realities. The goal is to let a future reader reconstruct the conditions under which the decision made sense, even if those conditions no longer hold.

Decision. The choice itself, stated plainly and unambiguously. Vague decisions — “we will use the cloud” — produce vague records. Specific decisions — “we will run this workload on managed containers in our primary region, with deployment via our existing CI/CD pipeline” — produce records that can actually be acted on and later revised.

Consequences. What follows from this choice — the positive, the negative, and the neutral. Honest consequences are what separate a useful ADR from a justification document. If a decision adds operational burden, the record should say so.

Alternatives considered. The options that were rejected, with a sentence or two on why. This is the section future readers value most: it prevents the organization from re-litigating settled questions and protects it from survivorship bias — the illusion that the current approach was the only reasonable one.

Annotated example

The following is a generic, hypothetical example — not drawn from any real project — to show the shape of a complete record.

ADR-014: Use event-driven integration between order capture and fulfillment

Status: Accepted (2026-03-18)

Context: Order capture and fulfillment currently communicate through synchronous API calls. During peak sales periods, capture waits on fulfillment processing, and fulfillment outages propagate to the storefront. The team needs to decouple the two domains without a full rewrite of either system. Both teams deploy independently on different release schedules.

Decision: Introduce an asynchronous event stream between order capture and fulfillment. Order capture publishes order events; fulfillment consumes them. Delivery guarantees will be at-least-once, with idempotent consumers.

Consequences:

Fulfillment outages no longer block order capture; orders queue and process on recovery.

Both teams can deploy independently, but they must now agree on and version the event schema.

At-least-once delivery requires idempotent fulfillment logic, which is new work for that team.

Operational complexity increases: the event infrastructure needs monitoring, retention policies, and a dead-letter strategy.

Alternatives considered:

Synchronous API with retries and circuit breakers — rejected; improves resilience marginally but preserves the coupling that causes the worst outages.

Shared database between the two domains — rejected; creates hidden coupling and makes independent deployment nearly impossible.

Full rewrite of fulfillment on the capture platform — rejected; too expensive and too risky for the problem at hand.

Notice what the record does not contain: diagrams, configuration details, API specifications. It contains the reasoning a future architect needs when the schema needs a breaking change, or when someone proposes re-coupling the domains “to simplify things.” The ADR is the organization’s memory of why that was already rejected, and what it cost to reach that conclusion.

The ADR workflow

A template without a workflow is a form nobody fills in. The workflow answers four questions: when to write one, who proposes it, who approves it, and where it lives.

When to write one. Not every decision deserves a record. The test is significance and reversibility. Decisions that are expensive to reverse — technology selection, integration patterns, data residency choices, security boundaries — are the core candidates. Decisions that shape how multiple teams work together are next. Routine implementation choices within a single component are not; recording them creates noise that buries the decisions that matter. A useful rule: if the decision would take more than a few weeks to undo, or if getting it wrong would surface in a security review or an outage, write the ADR.

Who proposes. The person or team closest to the decision drafts the record. For platform-level decisions, that is usually the platform or architecture team. For domain decisions, the owning team drafts it. Centralizing authorship in an architecture group produces records that read well and reflect reality poorly. The author’s job is accuracy, not polish.

Who approves. Approval should be proportional to impact. A decision confined to one team can be accepted by that team’s lead, with the record visible to everyone. A decision that crosses teams or commits the organization to a vendor, a pattern, or a cost profile should go through the architecture review board or the equivalent forum. The review step is where the alternatives-considered section earns its keep: reviewers can see whether the team did the hard thinking, not just the easy writing.

Where they live. ADRs should live where engineers already work. For most organizations, that means the source repository, in a docs or architecture-decisions directory, versioned alongside the code. This keeps the record next to the system it describes and makes supersession natural: the old record stays in history, the new one takes its place, and the version control log shows the lineage. Some organizations mirror accepted ADRs into a wiki or internal portal for broader discovery, which is fine as long as one location is the source of truth.

ADRs and architecture governance

Architecture governance fails when it is detached from how decisions actually get made. Review boards that only see finished designs end up rubber-stamping them; standards written without knowledge of past trade-offs get ignored. ADRs connect the two by making the decision history reviewable.

Review boards. An architecture review board that requires an ADR for significant decisions gets better submissions and faster reviews. The template forces the proposing team to articulate alternatives and consequences before the meeting, which eliminates the most common review failure: a team presenting a finished design and asking for approval, with the real alternatives never examined. Reviewers can focus on the reasoning — did the team consider the right options, are the consequences acceptable — rather than reverse-engineering the design from slides.

Compliance linkage. In regulated industries, auditors ask for evidence that controls were considered and applied. ADRs that record security, privacy, and data-residency decisions provide that evidence directly: the context section documents the regulatory constraint, the decision section documents the control, and the consequences section documents the residual risk. Organizations that maintain this discipline find audits substantially less disruptive, because the reasoning auditors want to see was captured at decision time rather than reconstructed afterward.

Audit value over time. Beyond formal compliance, the ADR archive is an audit trail for the architecture itself. When a new chief architect or a new CTO asks “how did we get here,” the answer is the archive — not a series of oral histories. When a migration is planned, the archive identifies which decisions the migration invalidates and which remain. When an incident occurs, the archive often contains the exact trade-off that the incident exposed, with the reasoning that led to accepting it.

Teams formalizing their architecture practice often find that the ADR archive becomes one of the most consulted artifacts in the organization — precisely because it answers the questions that design documents and wikis never captured.

ADRs for AI systems

AI systems concentrate the exact properties that make decisions worth recording: they are expensive to build, expensive to change, and full of choices whose consequences only become visible over time. ADRs are a natural fit.

Model selection. Which model a system uses, why that model was chosen over alternatives, and under what evaluation criteria — this is decision material. The record should capture the benchmarks or evaluations run, the trade-offs between capability and cost, and the conditions under which the choice should be revisited, such as a new model release or a cost change. Without the record, model choices calcify: nobody remembers whether the current model was chosen for quality, latency, cost, or simply because it was available first.

Data decisions. Training data sources, data retention policies, consent and licensing considerations, and preprocessing choices are all significant, partially irreversible decisions with legal and ethical consequences. An ADR records which data sources were approved, which were rejected and why, and what assumptions the decision rests on. When regulations change or a data source’s licensing terms shift, the record shows exactly which systems are affected.

Evaluation criteria. How the organization judges whether an AI system is working — the metrics, the test sets, the thresholds for shipping — is itself an architectural decision. Recording it prevents the quiet drift that happens when criteria erode under delivery pressure. The ADR can also record the decision to accept known limitations, such as performance on edge cases, which is the kind of honest trade-off that regulators, customers, and future maintainers all need to see.

Operational governance. Decisions about human oversight, fallback behavior, logging of model inputs and outputs, and incident response for model misbehavior all belong in the record. For organizations building AI governance programs, ADRs provide the connective tissue between high-level principles and the specific systems those principles govern: each principle is realized through concrete decisions, and each decision is recorded.

Common mistakes

Most ADR programs fail in one of three ways.

Writing too many. When every minor choice gets a record, the archive becomes noise and engineers stop reading it. The significance test — expensive to reverse, crosses team boundaries, or would surface in a review or outage — keeps the archive focused. A healthy archive grows slowly. If the team is producing more than a few ADRs a month, the bar is probably set too low.

Writing too few. The opposite failure is an archive that stops at the easy decisions. Teams record technology choices but skip the uncomfortable ones: the accepted technical debt, the security control that was deferred, the migration that was postponed. These are often the most valuable records, because they capture risk the organization knowingly accepted. A record that says “we are accepting this risk and here is why” is a governance artifact of the first order.

Stale statuses. An archive full of accepted decisions that no longer describe reality is worse than no archive, because it misleads. Status hygiene is the ongoing cost of the practice: when a decision is revisited, the old record must be marked superseded with a link to the new one. This is a review-board or architecture-owner responsibility, not something to leave to individual teams. A periodic review — quarterly is enough for most organizations — catches drift before it accumulates.

Getting started

Adopting ADRs requires almost no tooling and very little ceremony. What it requires is commitment to write the first records and to keep the workflow alive.

Start with a template. Adopt a simple template with the sections described above: title and status, context, decision, consequences, alternatives considered. Keep it to one page. Resist the urge to add extra fields until the practice is established — every additional field is friction against writing the next record.

Write the first three ADRs. Do not start with a mandate. Start by recording three decisions the organization already made: one recent technology choice, one integration pattern, and one accepted trade-off or piece of technical debt. Backfilling recent decisions is the fastest way to demonstrate value, because the authors still remember the reasoning and readers immediately recognize the decisions.

Put the workflow in place. Agree on where records live, who approves cross-team decisions, and when the archive gets reviewed. Then make the review board require ADRs for significant decisions going forward. The practice sustains itself once engineers experience the value: faster reviews, fewer re-debates, and an archive that answers questions before they are asked.

Putting it into practice

ADRs are a small practice with outsized returns, but they work best as part of a deliberate architecture discipline — one where decisions are reviewed, standards are grounded in recorded reasoning, and governance is evidence rather than assertion. For organizations building or strengthening that discipline, an advisory engagement can help establish the templates, workflows, and review structures that make ADRs stick, or review an existing archive for gaps and stale decisions. If that would be useful, get in touch — the first step is a conversation about how your organization makes decisions today.

Architecture Decision Records (ADRs) Explained