ADR

Abbreviation · Development

Definitions

  1. ADR, or Architecture Decision Record, is a lightweight document that captures an important architectural decision along with its context, the options considered, and the rationale for the chosen approach. Each ADR is typically a short text file stored in the project repository, making architectural decisions version-controlled and discoverable alongside the code they affect. A standard ADR includes a title, status (proposed, accepted, deprecated, superseded), context explaining the problem, the decision made, and the consequences of that decision. The practice was popularized by Michael Nygard and addresses the common problem of teams losing track of why something was built a certain way when the original decision-makers have moved on. ADRs create an institutional memory that helps new team members understand historical tradeoffs and prevents relitigating settled decisions.

    In plain English: A short write-up explaining why the team made a particular technical decision, so people in the future understand the reasoning.

    Example: "Before we switch message brokers, write an ADR so future engineers know why we chose Kafka over RabbitMQ."

Etymology

2011
Michael Nygard proposes Architecture Decision Records (ADRs) as lightweight documents to capture key design decisions.
2016
The ADR format gains traction in open-source projects and engineering organizations as a way to preserve decision context.
2020s
ADRs become standard practice in many engineering teams. Tools like adr-tools and Log4brains automate management.

Origin Story

The Diary That Keeps Architecture Honest

ADR stands for Architecture Decision Record, a document that captures an important architectural decision along with its context and consequences. The concept was formalized by Michael Nygard in a November 2011 blog post titled 'Documenting Architecture Decisions.' Nygard proposed a lightweight format: a short text file with sections for Title, Status, Context, Decision, and Consequences. His key insight was that architecture decisions are often lost because they live only in people's memories or are buried in meeting notes. When team members leave or new ones join, the reasoning behind critical choices evaporates. ADRs solve this by treating architectural decisions as first-class artifacts in the codebase, stored alongside the code they govern. The format deliberately stays simple: each ADR is a short document (often just a page or less) with a sequential number. Nygard recommended storing them in a 'doc/adr' directory in the project repository. The idea gained traction in the mid-2010s as microservices architectures increased the number of decisions teams needed to track. Tools like adr-tools (a bash-based toolkit) and Log4brains emerged to manage ADR collections. Today ADRs are widely adopted in organizations from small startups to large enterprises.

Coined by: Michael Nygard

Context: Blog post, November 2011

Fun fact: Nygard's original ADR template was inspired by pattern languages in architecture, going all the way back to Christopher Alexander's 1977 book 'A Pattern Language,' which also influenced software design patterns.

Related Terms