Architecture Decision Records (ADRs): The 2026 Guide

Most engineering teams have made a thousand architecture decisions and written down maybe twenty of them. The other 980 live in Slack scrollback, in heads that have since left the company, or in slide decks that nobody can find. Three years later, when someone asks, "Why did we choose Postgres for the catalog service?" the honest answer is, "I think it was Alex, and Alex doesn't work here anymore." Architecture Decision Records exist because that type of answer is too expensive to keep paying for.

This guide covers what an ADR is, what goes in one, when to write them, where to keep them, the format variants that have evolved since Michael Nygard proposed the original shape in 2011, the mistakes that turn ADRs into bureaucracy, and what's changing now that AI agents are starting to read, write, and reason about them. It's written for software architects, engineering leads, and CTOs who want their decision history to survive the people who made the decisions.

What Is an Architecture Decision Record (ADR)?

An Architecture Decision Record is a short, dated document that captures a single architecturally significant decision, including its context, the options considered, the choice made, and the consequences. Martin Fowler describes an ADR as "a short document that captures and explains a single decision relevant to a product or ecosystem", and most working implementations come back to that scope. One decision per document, a couple of pages at most, written in plain language that a future engineer can read and act on without context.

The format was popularized by Michael Nygard's 2011 post "Documenting Architecture Decisions" and has since become the most widely adopted lightweight pattern for preserving the why behind a system. The intent isn't documentation for its own sake. The cost of forgetting an architectural decision gets paid years later, by whoever inherits the system, and that cost is usually far higher than the cost of writing it down in the moment.

A useful distinction. An ADR is not a design document, nor is it an RFC. An RFC proposes a change and is typically resolved into either a decision or a rejection. A design document describes the structure of what was built. An ADR captures the decision itself, immutably, after the fact. Once accepted, the substance of an ADR should not be rewritten; material changes are captured by a new ADR that explicitly supersedes the original. Typo fixes and clarifying notes are fine. That immutability is what makes the decision history trustworthy, and it's what turns a corpus of files into a defensible record of the system architecture the team committed to.

What Goes in an ADR (The Template)

Nygard's original format is usually expressed as a title plus four body sections (Status, Context, Decision, Consequences), and most production templates still follow that format. The shape is small on purpose.

Title

A short noun phrase that names the decision. Numbering helps: ADR-0014: Use Postgres for the Order Catalog Service. Numbering also makes it easy to find a specific decision in a directory listing without opening the file.

Status

Proposed while the decision is under discussion. Accepted once the team has committed. Superseded by ADR-NNNN once a later decision replaces it. Some teams add Deprecated for decisions that no longer apply but haven't been replaced. The status field is small but does heavy lifting. It is the thing that lets a reader scan a directory of ADRs and know which ones are still authoritative.

Context

What is the situation that forces this decision? Constraints, requirements, prior decisions, and organizational pressures. The context is usually that the post-decision reader is asking, "Why did we even need to choose?" So write for that reader, not for the people in the room.

Decision

The actual choice. State it plainly, in active voice, in one or two sentences. "We will use Postgres as the primary datastore for the order catalog service." Avoid passive constructions like "it was decided that Postgres would be used"; the decision had owners, and the document should make that legible.

Consequences

What follows from this decision? Operational implications, what becomes easier, what becomes harder, what the team is now committed to (and what they are explicitly choosing not to do). The consequences section is the most common place for ADRs to fall short, because writing them honestly requires admitting trade-offs the team would rather not name.

Here's a minimal Markdown template:

# ADR-0014: Use Postgres for the Order Catalog Service

## Status

Accepted (2026-04-12)

## Context

The order catalog service needs durable storage for ~50M product records,
with strong consistency on price and inventory updates and read scalability
for catalog browsing. We have existing operational expertise with Postgres,
and our infrastructure team already runs a managed Postgres cluster.

## Decision

We will use Postgres as the primary datastore for the order catalog service.
We will use row-level locking for inventory updates and read replicas for
catalog browsing traffic.

## Consequences

- We accept a per-region write bottleneck in exchange for ACID guarantees.
- We will need to invest in read replica autoscaling to handle browse traffic.
- We are explicitly not choosing DynamoDB, which would have given us
  multi-region writes, but at the cost of write-side consistency we want
  for inventory.
- This ADR supersedes ADR-0007 (DynamoDB Spike Findings).

The length is usually around 40 lines, about two pages rendered. The brevity is the point with these docs.

When to Write an ADR (and When Not To)

Not every change deserves an ADR. The rule of thumb is that a decision is architecturally significant if it is expensive to reverse, crosses team boundaries, or constrains future decisions.

Architecturally Significant Criteria

A decision usually warrants an ADR when one of these is true:

• It picks one of several plausible technical approaches and rules out others.
• It changes the system's structure (a new service, a removed service, or a changed boundary).
• It changes how teams interact (e.g., a new contract or a new ownership boundary).
• It locks in a vendor, framework, or protocol that would be expensive to change later.
• It encodes a trade-off the team has explicitly accepted (latency vs. consistency, cost vs. flexibility, build vs. buy).

It does not warrant an ADR when the decision is reversible in a sprint, when it sits entirely within one component owned by one engineer, or when it is a routine implementation choice (such as which JSON library to use or which logging format to standardize on). Writing ADRs for trivial choices dilutes the corpus's signal and trains the team to skim them. For a broader framing of why treating decisions as measurable artifacts changes how engineering organizations operate, see our decision-first KPI playbook.

Avoiding ADR Sprawl

A common failure mode is treating ADRs as the universal documentation format. They aren't. ADRs capture decisions; runbooks capture operations; design docs capture structure; READMEs capture how to use a thing. When teams blur these lines, they end up with hundreds of "ADRs" that are really just notes, and the actual decisions get lost in the noise. Be picky about scope.

ADR vs. Design Document vs. RFC

The cleanest separation runs like this. An RFC proposes; an ADR records the decision (often born of an RFC); a design document describes the resulting system. RFCs are mutable. ADRs are immutable once accepted. Design documents are kept up to date as the system evolves. Conflating them is what produces the "we have 200 ADRs, and nobody reads them" anti-pattern.

ADR Example

The template above is minimal. Real ADRs benefit from a worked example. Here's a realistic one for an engineering team choosing between a managed search service and a self-hosted search for a B2B SaaS application.

ADR-0028: Use OpenSearch (managed) for product search rather than building on Postgres full-text

Status: Accepted (2026-05-30)

Context: The product search feature needs to support typo tolerance, faceted filtering across 30+ attributes, and sub-200ms p95 latency for catalogs up to 5M products. Our current Postgres full-text implementation hits typo tolerance limits and shows p95 of 800ms on the largest tenant. The platform team is small (4 engineers) and is currently absorbing the operational burden of two other primary datastores.

Decision: We will adopt OpenSearch via AWS OpenSearch Serverless for the search subsystem, and migrate the product search query path to it over a single quarter. We will retain Postgres as the system of record; OpenSearch is a read-side index.

Decision drivers (in order of weight): (1) Typo tolerance and faceted filtering are first-class in OpenSearch, custom in Postgres. (2) The platform team's bandwidth is the binding constraint, and managed OpenSearch removes infra ownership. (3) Cost is acceptable within projected query volume; we re-evaluate at 3x current volume.

Alternatives considered: Algolia (rejected: pricing escalates poorly above 1M product cap); Elasticsearch on EC2 (rejected: operational burden); Postgres full-text + GIN + pg_trgm (rejected: typo behavior on multi-word queries doesn't meet UX bar).

Consequences: We accept a second source of truth for search-relevant fields and the index-lag complexity that comes with it. We will add monitoring on index lag and a deliberate, eventual-consistency UX for very recent product changes. We will not migrate any other workloads to OpenSearch in this quarter; ADR-0029 explicitly defers analytics search to a later evaluation. This ADR supersedes ADR-0019 (Postgres full-text as primary search backend).

This is roughly the level of specificity ADRs reward. Decision drivers and alternatives are where the value lives. Three years from now, when someone proposes ripping out OpenSearch in favor of "just use Postgres again," ADR-0028 is the artifact that tells them what trade-offs the original team accepted.

How to Store and Manage ADRs

ADRs work best when they are easy to find, easy to differentiate, and impossible to forget.

In the Repository (Markdown + Git)

The most common pattern, and the one Martin Fowler recommends, is keeping ADRs as Markdown files in the same repository as the code they describe, typically under docs/adr/. The advantages are real. ADRs live where engineers already work, they version with the code, they show up in pull request reviews, and they can be diffed and linked like any other artifact. Most modern ADR tooling assumes this layout.

The trade-off is that ADRs in a single repo only cover decisions scoped to that repo. Cross-cutting decisions (an org-wide identity strategy, a multi-team data platform choice) sit awkwardly in any single repository, and tend to drift to wherever someone happened to put them.

In Confluence, Notion, or a Wiki

Some teams prefer a wiki because non-developers can read and contribute. The cost is real. ADRs in wikis tend to be harder to diff, harder to link to code, and easier to silently edit (which breaks the immutability discipline that makes ADRs trustworthy). If the wiki is the choice, explicitly lock down edit permissions on accepted ADRs.

As a Static Site (adr-tools and friends)

For larger organizations, a dedicated ADR site (often generated from Markdown by adr-tools or Log4brains) provides searchable cross-repo decisions, a clear status view, and a presentation layer that non-engineers find easy to read. The cost is maintaining the pipeline. For most teams, the in-repo Markdown layout is sufficient; the static site becomes useful once decisions cross many repositories.

ADR Tooling Comparison

The major tools converge on a small set of capabilities. They scaffold new ADRs from templates, list the corpus, track supersession links, and (sometimes) generate a viewable site. adr-tools (the Bash CLI from Nat Pryce) is the lowest-friction starting point. Log4brains produces a static site from your ADR directory. ADR Manager is a web UI for teams who want a non-Git surface. None of these tools solves the harder problem, which is keeping ADRs connected to the live system they describe. That's the gap newer architecture-decision systems are filling.

ADR Formats and Templates

Nygard's four-section format is the canonical starting point, but several variants have emerged that solve specific problems.

Michael Nygard's Original Format

Title plus Status, Context, Decision, and Consequences. Small, simple, and the format most teams who say "we use ADRs" still mean. Nygard's 2011 post remains the most widely cited reference, and most teams that say "we use ADRs" mean some variant of this format.

MADR (Markdown Any Decision Records)

MADR adds a few sections that Nygard's original implies but doesn't name: explicit decision drivers, considered options with pros and cons, and decision outcome. The MADR format is more verbose, which is either an improvement (it forces the team to enumerate trade-offs) or a regression (it adds bureaucracy), depending on team maturity. For teams that struggle with the consequences section in Nygard's format, MADR helps. For teams that already write good ADRs, MADR is overhead.

Y-Statements

A more compressed format that captures a decision in a single sentence shaped as "In the context of X, facing Y, we decided Z, to achieve W, accepting V." Useful for very high-volume, lower-stakes decisions, or as a precursor to a fuller ADR. Y-statements are not a replacement for ADRs at architecturally significant decisions; they're a complement at the smaller end.

arc42 ADR

The arc42 architecture documentation framework includes an ADR template that integrates with its broader system-documentation conventions. Useful for teams already on arc42; not worth adopting just for the ADR variant.

Common ADR Mistakes

The pattern is simple. The execution is where it breaks down.

Writing Them After the Fact

The single most common failure mode. The team has a decision meeting, ships the change, and writes the ADR three months later when someone notices the decision exists but isn't documented. The retroactive ADR has the form of the decision record but not the substance. The context is reconstructed, the alternatives are forgotten, and the consequences are described as outcomes rather than as a forecast the team committed to. The fix is process. An ADR is part of the decision, not an artifact of it.

Treating Them as a Commit Log

A subtler failure is writing an ADR for every code change rather than for every architectural commitment. The result is hundreds of "ADRs" that are really just commit messages, which dilute the corpus's signal. If a future engineer can't tell from a directory listing which ADRs are load-bearing, the format has stopped working.

Never Revisiting Them

ADRs are immutable, but the current state of decisions is not. A team that writes ADRs but never re-reads them ends up with a system that has quietly drifted away from its own decisions. The discipline is to revisit the corpus during architecture reviews, supersede the decisions that no longer apply, and keep the live decision set roughly in sync with what's actually running. This is harder than it sounds, and it's the reason most ADR programs eventually stall.

No Decision Owner

Decisions without owners get unwritten quietly. Every ADR should name a person (or a small group) accountable for the decision. When the system drifts away from the decision later, the owner is the one you go to. When the owner leaves, the decision is either explicitly transferred or explicitly superseded. ADRs that don't name owners are decisions waiting to be forgotten.

ADRs and AI: What's Changing in 2026

ADRs solved a specific problem in 2011. Decisions kept getting lost in head knowledge and Slack scrollbacks. They were the right answer to that problem. In 2026, the problem has shifted in two ways, and the format is starting to feel the strain.

The first shift is that systems evolve faster than the documents about them. The whole reason ADRs are immutable is that the decision history needs to be trustworthy as a snapshot of what the team committed to at time T. But the running system in 2026 changes orders of magnitude faster than the ADR corpus describing it. A static document on disk has no way to know whether the decision it captured remains consistent with the production system it once described.

The second shift is that AI agents are starting to do real work in the decision loop. Agents write code, plan migrations, and generate architecture diagrams, and the static-document format doesn't fit naturally into any of it. An agent that needs to know "what did we decide about the catalog data store" can read an ADR, but it has no way to know whether the decision still holds against the live system, no way to know which alternatives were considered, and no way to update the corpus when a new decision crosses an old one.

This is the architectural shift Catio is built around. The Architecture IDE is a system of record for architecture decisions tied to the live system state, so the corpus stops being a static snapshot and becomes a queryable, drift-aware decision layer. The Nygard format still works as the artifact. The interesting work in 2026 is in the layer above it, where decisions are reasoned across the system rather than read from one file at a time. Tools like Archie, our conversational architecture copilot, let teams ask the corpus questions in natural language and get answers grounded in what's actually running. We've written separately about how Catio's multi-agent recommendation engine composes architecture questions across the decision history; the agentic shape changes what the decision layer is actually used for.

None of this kills the ADR. The Nygard format is too small, too useful, and too well-adopted to be displaced. What's changing is that the corpus is becoming a substrate something else operates on, rather than a directory of files engineers read directly.

ADR Tools (2026)

The current tooling landscape splits roughly into three categories.

Lightweight CLI tools. adr-tools (the Nat Pryce Bash CLI) and Log4brains (Node-based, generates a static site) handle the core mechanics. They scaffold new ADRs from a template, number them, and track supersession. For teams keeping ADRs in a single repo, this category is usually sufficient.

Web-based ADR managers. ADR Manager and similar tools offer a non-Git surface for editing and reviewing ADRs. Useful for organizations where non-developers participate in decisions, less useful for engineering-only teams that already live in the repository.

Architecture-decision systems. A newer and smaller category that treats decisions as a queryable corpus tied to live system state, rather than as files on disk. Catio operates here. The category isn't a replacement for the in-repo Markdown format; it sits above it, so that the decision corpus can be reasoned about across the system, drift can be detected against the decisions the team committed to, and AI agents can do useful work in the decision loop. For teams running multi-cloud or multi-region systems where decisions cross many repositories, this category is starting to matter; for teams managing a handful of repos, the lightweight CLI tools remain the right starting point.

For the broader category around architecture decisions, see our roundup of software architecture tools.

Closing the Loop

ADRs are among the few engineering practices that have survived a decade-plus of fashion cycles without being replaced or forgotten. The reason is that the problem they solve (the cost of forgetting decisions) keeps getting more expensive as systems grow. The format is small, the discipline is hard, and the payoff shows up years later, when whoever inherits the system finds the decision they need exactly where they expected it.

If your team is at the point where ADRs in Markdown are doing their job but the corpus is starting to feel like a snapshot of a system that has moved on, that's the seam Catio is built around. See how Catio’s Architecture IDE treats decisions as a living, drift-aware corpus that AI agents and humans can reason about together, rather than as a directory of files that age the moment they're written.

Frequently Asked Questions

What is an ADR in software architecture?

An Architecture Decision Record is a short, dated, immutable document that captures one architecturally significant decision, including its context, the options considered, the choice made, and the consequences. ADRs preserve the "why" behind a system over time, so the decisions don't get lost when teams change or systems evolve.

What is the difference between an ADR and a design document?

A design document describes the structure of a built system. An ADR captures the decision that produced the structure. Design documents are kept up to date as the system evolves; ADRs are immutable once accepted and are superseded by new ADRs rather than edited. Both are useful, and they answer different questions.

Who should write architecture decision records?

The team that made the decision, while the decision is being made. Retroactive ADRs lose most of their value because the context, alternatives, and consequences are reconstructed rather than committed to at the time. Each ADR should name an owner (the person or group accountable for the decision over time) so that the corpus has clear lines of accountability.

Are ADRs still relevant with AI in 2026?

Yes, but the role is changing. The Nygard format remains a good artifact for capturing a decision, but the static-document model is starting to feel the strain as systems evolve faster than the documents that describe them and as AI agents begin to reason across the decision corpus. The category Catio operates in (architecture-decision systems tied to live state) is the layer above ADRs, not a replacement for them.

What is the best ADR template?

For most teams, Nygard's original four-section template (Title, Status, Context, Decision, Consequences) is the right starting point. Teams that struggle with the consequences section often benefit from MADR, which adds explicit decision drivers and considered-options sections. Avoid adopting a template just because it has more fields; bigger templates produce more bureaucracy, not better decisions.

‍