Architecture Decision Records

What an ADR is and the problem it solves

An Architecture Decision Record (ADR) is a short text document that captures one architecturally significant decision: the situation that forced it, the options that were weighed, what was chosen and what follows from the choice. A collection of them, kept in order, forms the decision log of a system. The idea of recording decisions is old (design rationale research goes back decades, and Jeff Tyree and Art Akerman published a detailed decision template in IEEE Software in 2005), but the lightweight form most teams use today comes from Michael Nygard's blog post Documenting Architecture Decisions, published on 15 November 2011.

Nygard's starting point was a problem every long-lived team recognises. A new developer finds a decision in the code that looks strange: an extra queue, a duplicated table, a library nobody would choose today. Without knowing why it was made, the newcomer has two bad choices. They can accept it blindly, preserving something whose reasons may no longer apply, or change it blindly, breaking something whose reasons still do. Nygard's remedy was to write down the reasons at the time the decision is made, in a small file kept with the code, so that the motivation travels with the system. Big architecture documents rarely achieve this because nobody updates them; a short record of one decision, written once and never rewritten, stays true because it only claims to describe what was known and decided on a particular date.

This builds directly on the anatomy of a decision in Chapter 1: decisions and trade-offs: context, options, criteria, decision with rationale, consequences and status. An ADR is simply that anatomy written down in a predictable format. It also answers the question architecture versus design leaves open in practice: if architecture is the set of significant decisions, the ADR log is the closest thing a team has to a list of its architecture.

Nygard's format

Nygard proposed five parts. Most teams still use them, often moving the status to the top so that readers see at once whether the record is in force. His guidance on how to write each part matters as much as the headings.

Nygard also suggested that a record should fit on one or two pages, that records are numbered sequentially and numbers are never reused, and that they live in the project repository as plain text. Each of those small rules exists for a reason: short records get read, stable numbers can be cited in code comments and commit messages, and plain text in the repository can be reviewed and versioned like code.

Other templates: MADR, Y-statements and richer forms

Nygard's format says nothing explicit about the options that were rejected, and many teams found that the alternatives are exactly what a later reader most wants to know. Several templates add them.

MADR (Markdown Architectural Decision Records, maintained at adr.github.io) is the most widely used structured template. Its current release at the time of writing is version 4.0.0, published in September 2024. The full template has a title, then Context and Problem Statement, optional Decision Drivers, Considered Options, Decision Outcome with optional Consequences and Confirmation subsections, optional Pros and Cons of the Options and optional More Information. Metadata such as status, date, decision-makers, and who was consulted and informed can go in a YAML header. Two ideas in MADR are worth borrowing even if you use another format. Decision drivers make the criteria explicit before the options are judged, which is the weighted-matrix discipline from Chapter 1 in compact form. Confirmation says how the team will check that the decision is actually implemented and still holds, for example a review, a test or an automated architecture check.

The Y-statement, proposed by Olaf Zimmermann and colleagues and first presented at the SATURN conference in 2012, compresses a decision into one structured sentence: In the context of (a use case or component), facing (a concern or quality requirement), we decided for (the option) and neglected (the alternatives), to achieve (the benefits), accepting that (the drawbacks). The name is a pun on why. A Y-statement is ideal for a decision log summary, a slide, a code comment or a pull request description; for a contested one-way door it is usually too compressed, and teams expand it into a full record.

Heavier templates exist for regulated or very large settings. Tyree and Akerman's 2005 template adds fields such as assumptions, constraints, related decisions, related requirements and implications. These are useful when decisions must be traced to requirements for an auditor; for most product teams they add effort that nobody reads.

Status, lifecycle and why accepted records are not edited

An ADR moves through a small number of states. It starts as proposed, usually as a pull request that adds the file, so that discussion happens in review comments. When the people accountable agree, it is merged as accepted. A proposal that is turned down can be kept as rejected, which is valuable: the next person who suggests the same idea finds the earlier reasoning. Later, an accepted record may become deprecated (the decision no longer applies, perhaps because the component was retired) or superseded by a newer record that replaces it, with links in both directions. MADR lists the same set: proposed, rejected, accepted, deprecated and superseded.

The central rule is that an accepted record's content is not rewritten. If the team changes its mind, it writes a new ADR that supersedes the old one, and changes only the old record's status line to point forward. The reasons are practical. First, the record is evidence of what was known and decided at a point in time; editing it after the fact turns history into fiction and destroys the trust that makes the log useful. Second, the old record explains why the system looked the way it did for a period, which matters when debugging old data or reading old code. Third, a new record forces the team to state what changed in the context, which is often the most important insight. Small corrections (a typo, a broken link) are harmless; changing the decision, the reasons or the consequences is not. Martin Fowler's description of the practice says the same: once accepted, a record is not reopened; a superseding record is written instead.

Where to keep ADRs

Keep ADRs in the repository of the code they govern, as plain-text files (usually Markdown), one decision per file, with a sequence number and a short slug in the file name. Two directory conventions are common: doc/adr, the default of Nat Pryce's adr-tools command-line tool, and docs/decisions, recommended by MADR with names such as 0012-publish-order-events-through-broker.md. Thoughtworks placed lightweight ADRs in the Adopt ring of its Technology Radar (most recently in 2018) and specifically recommended source control over a wiki, so that records stay in step with the code they describe.

Keeping records next to the code has concrete advantages. They are reviewed in the same pull requests as the code that implements them, they are versioned and branched with it, a developer can find them with the same search tools, and code can point at them: a comment such as see ADR-0012 above an outbox relay tells the next reader where the reasons are. Decisions that span many repositories, such as an organisation-wide choice of identity provider, need a home of their own; a dedicated architecture repository with the same conventions works well, with links from each affected codebase.

docs/
  decisions/
    README.md                                  <- the decision log (index)
    0001-record-architecture-decisions.md
    0004-use-hosted-card-fields.md
    0007-use-managed-postgresql-for-orders.md
    0012-publish-order-events-through-broker.md
    template.md
src/
  ordering/
    outbox_relay.py      # comment: see docs/decisions/0012-...

Which decisions deserve an ADR

Writing an ADR for every choice buries the important ones; writing none loses the reasons. The test is significance, as defined in Chapter 1: a decision deserves a record when it is expensive to reverse, affects a key quality attribute, has wide scope, constrains other teams, or was contested. In practice that means choices such as a primary datastore, a communication style between services, an identity provider, an API versioning policy, a hosting platform, a build-versus-buy decision, and conventions whose violation is expensive (how money is represented, how time zones are stored). It also includes decisions not to do something that people keep suggesting, such as not introducing a cache yet.

Choices that are local, cheap to reverse and invisible outside one module usually do not need a record: the choice of a test assertion library, the name of a class, the internal layout of a component. A useful signal is the question a newcomer would ask: if someone is likely to ask why on earth did they do this? within a year, write the record now, while the reasons are fresh.

A complete worked ADR

The food-delivery platform used throughout this chapter has customer, restaurant and courier apps, an ordering service, payments through an external payment provider, courier dispatch and notifications. The record below follows the MADR structure, slightly shortened. Notice how the context gives numbers and dates rather than adjectives, how the drivers are stated before the options, how the rejected options are given a fair hearing, and how the consequences include real costs. The decision itself (asynchronous messaging for order events) is explored properly in Chapter 6: event-driven architecture; here the point is how it is recorded.

# ADR-0012: Publish order events through a managed message broker

- Status: Accepted
- Date: 2026-09-14
- Deciders: ordering team lead, platform lead, principal architect
- Consulted: restaurant, courier and notifications teams; SRE
- Related: ADR-0007 (managed PostgreSQL for the order service)

## Context and problem statement

When a customer's payment succeeds, the ordering service calls the restaurant,
courier-dispatch and notification services synchronously over HTTP before it
confirms the order. On Friday evenings (peak about 40 orders/s) p99 order
confirmation time reaches 4.2 s against our target of 1.5 s (scenario QS-3).
On Friday 21 August a notification-service outage blocked all new orders for
23 minutes. Two new consumers (loyalty points, analytics) want order data.

## Decision drivers

- Order confirmation must not depend on notification or dispatch availability.
- p99 confirmation under 1.5 s at three times today's peak.
- No order event may be lost, even if a service crashes mid-request.
- New consumers should not require changes to the ordering service.
- The platform team has three people; operational load must stay small.

## Considered options

1. Keep synchronous calls; add timeouts, retries and circuit breakers.
2. Publish events to a managed message broker using a transactional outbox.
3. Let consumers poll a shared "order_events" table in the order database.

## Decision outcome

Chosen option: 2. We will publish OrderPlaced, OrderAccepted, OrderPickedUp,
OrderDelivered and OrderCancelled events to our cloud provider's managed
broker. The ordering service writes each event to an outbox table in the
same database transaction as the order; a relay publishes it. Payment
authorisation stays synchronous, because the customer must see the result.

### Consequences

- Good: confirmation no longer waits for downstream services.
- Good: loyalty and analytics can subscribe without ordering-team work.
- Bad: services become eventually consistent; the restaurant tablet may
  show a new order a second or two after the customer's confirmation.
- Bad: a broker to pay for and monitor; consumers must be idempotent
  because delivery is at-least-once.
- Neutral: event schemas become public contracts and need versioning.

### Confirmation

Load test at 120 orders/s in staging before go-live; a build check fails
if the ordering service gains an HTTP client for notification or dispatch.

## Pros and cons of the other options

- Option 1: least new infrastructure, but a slow dependency still delays
  every order, and each new consumer means another call to add.
- Option 3: no new infrastructure, but couples every consumer to our schema
  and adds polling load to the order database (see ADR-0007).

Reviewing ADRs

Because an ADR is a file in the repository, the natural review mechanism is the pull request. The proposer opens it with status proposed; the people affected comment; the record is revised; when the accountable people agree, the status changes to accepted and it is merged. This keeps the discussion attached to the record and visible to anyone who later reads the history.

Who must review depends on how decisions are governed. In a centralised model an architecture board approves significant records. In the advice process described by Andrew Harmel-Law (martinfowler.com, 2021), anyone may make an architectural decision, provided they first seek advice from everyone meaningfully affected and from people with relevant expertise, and record that advice; the decision-maker need not follow the advice but must hear it. ADRs are the backbone of that process: the advice appears in the record, and a regular open advisory forum reviews proposed records. Governance models are covered in Chapter 11: governance in agile organisations.

Olaf Zimmermann's ecADR checklist (2020) gives reviewers a compact definition of done for a decision. Evidence: there is reason to believe the option will work, from a spike, a proof of concept or trusted experience. Criteria: at least two options were compared against the stakeholder concerns. Agreement: the decision has been challenged by peers and the team accepts it. Documentation: it is recorded and shared with those affected. Realisation and review: implementation is planned and a date or trigger for revisiting it is set. A reviewer who checks those five points, plus the honesty of the consequences, catches most weak records.

Anti-patterns

ADRs fail in recognisable ways. Zimmermann catalogued several in 2023 with memorable names, and the most damaging are worth knowing.

The decision log as an index

Individual records are useful; the log as a whole is more useful. A short index file (often the README.md of the decisions folder) lists every record with its number, title, status and date. A newcomer reads it in five minutes and gets a compressed history of the architecture: what was decided, what was rejected, what was replaced and when. Tools such as adr-tools can generate the index and create superseding records that update the old record's status automatically, and documentation tools including the Structurizr DSL can import a folder of ADRs into the published documentation.

Treat the log as part of the architecture description. The arc42 template has a section for architecture decisions that can simply link to it, and a docs-as-code pipeline can publish it with the rest of the documentation.

# Decision log

| ADR  | Title                                                | Status                 | Date       |
|------|------------------------------------------------------|------------------------|------------|
| 0001 | Record architecture decisions                        | Accepted               | 2025-03-02 |
| 0004 | Use the payment provider's hosted card fields        | Accepted               | 2025-04-18 |
| 0007 | Use managed PostgreSQL for the order service         | Accepted               | 2025-06-11 |
| 0009 | Send push notifications through a third-party SDK    | Superseded by 0015     | 2025-09-30 |
| 0012 | Publish order events through a managed broker        | Accepted               | 2026-09-14 |
| 0013 | Store courier locations in a time-series database    | Rejected               | 2026-09-20 |
| 0015 | Run our own notification service on the broker       | Accepted               | 2026-10-08 |