Decision-making glossary
Architecture decision record (ADR)
An architecture decision record (ADR) is a short text file that documents one significant technical decision: its context, the decision itself, its status, and its consequences. ADRs are numbered, stored in version control next to the code, and not rewritten afterward. A changed decision gets a new ADR that supersedes the old one.
The format was popularized by Michael Nygard in a 2011 post, “Documenting Architecture Decisions.” He proposed five parts, title, context, decision, status and consequences, and argued that each record should be one or two pages so people actually read it. The status moves from proposed to accepted, and later to deprecated or superseded.
An ADR is written for a particular reader: the engineer who joins in two years and wonders why the system is built this way. It records what the team knew at the time, including the forces pulling in different directions, and states the decision in active voice, as in “We will …”. The UK Government Digital Service asks teams to keep ADRs in version control, in the repository of the application they affect.
Common mistakes are writing ADRs for trivial choices, editing an accepted ADR instead of superseding it, and titling it after the problem rather than the decision. An ADR is one kind of decision record, and the set of a project’s ADRs is its decision log.
In Decize: Paste an existing ADR into Decize’s Import and it pulls out the decisions the document records, for you to approve row by row. Import is on paid plans. See how →
Free template: Architecture decision record (ADR) template
Sources: Michael Nygard, “Documenting Architecture Decisions” (2011) · The GDS Way, “Documenting architecture decisions” · Architectural Decision Records (adr.github.io)