Architecture Decision Records (ADR)

Overview

An Architecture Decision Record (ADR) is a short document that captures a single significant architecture decision along with its context and consequences. ADRs answer the question future developers always ask: "Why did we do it this way?"

ADRs are lightweight, version-controlled, and stored alongside the code they describe. They form a decision log that accumulates over the life of a project, creating an invaluable history of the reasoning behind the system's architecture.

The Nygard Format (Original ADR)

Michael Nygard defined the original ADR format in his blog post "Documenting Architecture Decisions" (2011). It has five sections:

Structure

# [ADR-NNNN] [Short Title of Decision]

## Status

[Proposed | Accepted | Deprecated | Superseded by ADR-XXXX]