# Architecture decision record

## What it is

An architecture decision record, often abbreviated ADR, is a short account of
a consequential technical choice. It says what the team decided, which
conditions made the decision necessary, what credible options it considered and
what consequences it accepted. The choice might concern how to store facts,
where a system boundary lies, how teams integrate or what happens during a
failure. A reader arriving later can use the record to understand why this
design exists and which assumptions still apply.

A few fields carry most of the work. An identifier and a date make the record
easy to cite. A short status indicates whether a decision is proposed,
accepted or superseded. The context identifies the problem and constraints.
The decision describes what the team will actually do. Consequences cover
benefits and obligations, such as another service to operate, a slower
transition or a migration that must be rehearsed. Include enough detail about
options to explain the tradeoff without recreating the full discussion.

Use the same publication path reviewers already trust. A team may keep
Markdown records beside its code and link them from the change that implements
the decision. A team designing a service across several repositories may keep
a shared index and reference the same record from each change. The record's
value comes from readable reasons and a stable address. Its template is a
means of capturing those reasons consistently.

## Why it matters

Code is good at preserving what exists. It explains the history only
partially. A reader may see two databases and assume that one should be
retired, when the split was a temporary measure to isolate a risk while a
supplier changed its export. The written decision can clarify what the team
was protecting, why the alternative was viable and what event makes it time
to reconsider. That avoids repeating an investigation from scratch.

The record also helps people disagree productively. A proposal can say that a
new dependency would spare the team from developing a scheduler but require
an operator who can restore its state. A reviewer can question the cost or the
availability of that operator. The tradeoff is visible to people outside the
immediate implementing pair, including the team that will operate the service.
Once accepted, the same account gives a handover reader a way to understand
where responsibility belongs.

The time spent writing should match the effect of revisiting the choice.
Changing a label normally belongs in the change history. Changing which
service owns the ledger or how an application handles duplicate payments is
costly to undo and has consequences for several readers. A short record
written during the decision preserves those reasons before the team forgets
earlier alternatives. Keep the evidence close enough that another engineer
can confirm which reading was available on that day.

## What it looks like in practice

The portfolio's account of [a platform's founding technical decisions](/portfolio/set-the-platforms-founding-technical-decisions/)
describes choosing core technologies while shaping the product and its
technical direction. That case shows the kind of decision worth preserving.
The following fictional example illustrates how an ADR could record a similar
tradeoff about ownership. It is written for this article.

Suppose a shipping service has a live order database and a read-only status
page. Teams have been debating whether the status page should read the order
database directly. The context is that dispatch receives late status events and
support needs a public view that cannot disclose another customer's order.
The decision is to serve the view from a separate read model, updated from
approved fields only. A direct read would start with fewer components and
usually show fresher data, but would put public traffic and a new permission
boundary next to the system of record. Reusing a nightly export would be
simpler still, but would leave same-day delivery changes invisible.

The consequences should drive work. A lag indicator tells the support
team when to fall back to its internal procedure. A contract check catches
an accidental new field. Someone owns the update job and its alert. The
team agrees to revisit the choice if lag exceeds the agreed tolerance in two
busy weeks, or if the separation requirement changes. The record links to
the design review and the test. A maintainer can see the cause of the extra
component and the evidence needed before replacing it.

When replacing the choice, create another record, link both directions and
make the old entry's status clear. Preserve the dated reason that was valid
for the previous design. People investigating an older system version still
need that history. An index with short titles and statuses lets readers
find the live decision without reading a chain of reviews.

Before returning a status, the public endpoint verifies that the viewer has access to that specific order. Test rejection of another customer's order as well as the exact allowed response fields.

## Where it goes wrong

A record is weak when it lists one preferred option and a caricature of
everything else. Give alternatives the fairest version the team considered.
Readers should understand why an option would have been attractive in a
different situation. Ground important claims in the benchmark, standard or
constraints that actually informed the decision. A copied template should
leave room to describe a decision that depends on legislation, capacity or
previous commitments.

A second mistake is to list advantages and leave the costs unowned. A new
database, a second application or a shared queue changes someone else's
working day. Include the operational handover, security boundary or
maintenance cost that follows. Assign important obligations to people and
checks where appropriate. If the consequences cannot be tested immediately,
name what would be observed and when the team expects to learn.

Finally, keep the record small and timely. A folder of uniform documents
whose milestones no longer match the work is harder to trust than a handful
of precise decisions. Separate the decision's reasoning from a general
tutorial and link to changing operational procedures. When a continuation
becomes a new choice, preserve both decisions and give readers a reliable
route to the current one.

## Further reading

- [AWS guidance on the architecture decision record process](https://docs.aws.amazon.com/prescriptive-guidance/latest/architectural-decision-records/adr-process.html)
- [Microsoft Azure Well-Architected guidance on decisions](https://learn.microsoft.com/en-us/azure/well-architected/architect-role/architecture-decision-record)
- [UK government architectural decision record framework](https://www.gov.uk/government/publications/architectural-decision-record-framework)

<https://engineer.company/glossary/architecture-decision-record/>
