ADR document

An ADR document records a single important architectural or technical decision. It is not a long design exploration: it states the outcome—the context that mattered, the decision you made, and the consequences you accept (including follow-up work and vendor or operational cost).

What is an ADR document?

It is usually a short markdown file in version control, often numbered or dated so people can refer to it in code review and in runbooks. The point is to make the rationale findable when the original authors have moved on.

What should an ADR document include?

Common sections (wording varies by format):

Title and identifier
Status and lifecycle (including what supersedes this ADR, if any)
Context — forces, constraints, and scope
Decision — the commitment, not a list of all options you considered
Consequences — tradeoffs, operational impact, and known follow-ups
Alternatives considered (when skipping them would confuse future readers)
Related decisions, RFCs, or tickets, linked explicitly

ADR document vs decision log

One file describes one decision. The collection of those files, plus an index you maintain in a README or tool, is your architecture decision log. Start from one ADR, then add entries as the log grows; do not conflate the index with the full text of every decision.

ADR document template (Nygard-style sketch)

The classic shape is a small set of headings. For copy-ready bodies and other formats, see our template pages (e.g. Nygard, MADR).

# Title of decision

## Status

Proposed | Accepted | Deprecated | Superseded by ADR-…

## Context

What problem or constraint forces a decision? What is in scope?

## Decision

What are we doing, in plain language?

## Consequences

What gets easier, harder, or explicitly deferred?

Example ADR document

Full worked examples (same structure, different domains):

Create an ADR document

Open the ADR generator to draft markdown with live preview, copy, and download.