Architecture decision records

# ADR [number]: [one decision in a short title]

Keep one decision per file. Replace the bracketed prompts with what is actually known; mark unknowns rather than inventing evidence. Save the record alongside the code, for example as docs/decisions/0001-short-title.md.

## Decision

We will [specific action and scope].

## Context

Date of the decision: [YYYY-MM-DD]
Decision owner and reviewers: [people responsible for the choice]

[Describe the constraint, workload, existing system and deadline that matter now. Separate measured facts, assumptions and unknowns. Link to the issue, design discussion or reproducible evidence.]

## Alternatives rejected

- [Alternative A]: [Why it does not satisfy the relevant constraints; what it would do better.]
- [Alternative B or the current approach]: [Why it was not chosen; when it would become preferable.]

## Consequences accepted

[State the useful effect and the cost we deliberately accept. Name the changed failure mode, operational responsibility, dependency or reversal cost. Describe what observation would justify revisiting the choice.]

## Status

Proposed | Accepted | Superseded — choose one.

Supersedes: [previous record, when applicable]
Superseded by: [replacement record, when applicable]

When the decision changes, create a new record. Mark this record as superseded and link to the replacement; do not rewrite its historical context to match the new system.

---

This template follows the five-field structure in Software Made Clear's architecture decision records guide: https://softwaremadeclear.com/architecture-decision-records/
It is a blank working template, not a claim that any decision has already been reviewed or approved.

A new engineer finds that reports run inside the main application. A separate worker looks like the obvious alternative. Was it considered? Was there a constraint that no longer applies? The code shows what the team built, but it cannot answer those questions on its own. A short record can preserve the missing reasoning.

What the file has to contain#

The template above makes five things explicit. Each should help someone understand the choice, not merely show that a form was completed.

This is the site’s adaptation, not a verbatim copy of the original format. Michael Nygard’s proposal uses title, context, decision, status and consequences. Our template names rejected alternatives explicitly. The purpose is the same: preserve enough reasoning to avoid both blindly accepting and blindly reversing a past choice.

Assumptions and review triggers#

A reason can be sensible and temporary. Recording that distinction makes the ADR useful when the system changes. Consider this illustrative reporting decision; the limits below are invented for the example, not recommended thresholds or production measurements.

Now a new requirement asks for 100,000 rows. The trigger has fired, but “add a worker” is not yet the conclusion. Streaming results inside the application, moving work elsewhere and changing the user-facing behaviour remain different options. The review needs evidence about those options under the new requirement.

Write what would make the current choice unattractive, not just what would confirm it. For this example: “If report generation causes unacceptable delay for interactive requests under the agreed workload, revisit the shared-process choice.” The team must define an acceptable delay and measure it; calling a design simple does not settle that question.

A review trigger is our suggested extension, not a mandatory ADR field. It can be a short sentence in the context or consequences rather than a new process. Give it an owner and a way to be noticed. An unobserved threshold in a document is not monitoring, and a trigger that nobody owns is only a reminder.

After reviewing, the team may retain the decision and append a dated review note. If it changes the decision, it writes a new ADR and links it to the old one. Either way, it keeps the original assumptions distinguishable from the information learned later. A good result alone does not prove that the original reasoning was sound; a disappointing result does not tell us which assumption failed.

Why they die#

Three habits make a directory of records less useful. The first is writing from memory after the implementation, when the rejected options are harder to recover. The second is writing for an unspecified audience: long background sections hide the actual choice. The third is recording every minor decision, so the important ones become difficult to find.

Reserve ADRs for choices whose context matters to future changes. Nygard’s examples of significant decisions include structure, dependencies, interfaces and non-functional characteristics. The cost of reversing a choice is a useful consideration, not a fixed time threshold. A small change to an externally used interface may deserve a record even if the code took an afternoon.

The retry promise made by an API is one example: callers may depend on it long after the implementation changes. The boundary between code and deployment configuration is another. An ADR records why the team chose the boundary; it does not replace the documentation of the current contract.

The record that got rewritten#

Suppose someone edits the reporting ADR so that it now says the team always expected 100,000-row reports. The page looks up to date, but it no longer explains the original decision. A future reader cannot tell whether the team knowingly accepted that workload or discovered it later.

Keep that history intact. A spelling correction, a dated clarification and a status change are not the same as replacing the old reasoning. When the architecture changes, mark the earlier decision as superseded and explain the new choice in a linked record. Do not make the earlier team appear to have known what only became clear afterwards.

Questions that are still open belong in a design discussion people can challenge. Once a choice is accepted, its ADR records the result and consequences. Keeping those jobs separate lets the current system evolve without erasing the path that led to it.