Architecture Decision Record

Architecture Decision Records (ADRs) are short documents that capture a single architectural decision, its context, rationale, alternatives considered, and consequences. They should be kept brief (one page), stored in the source repository in a lightweight markup format like Markdown, numbered sequentially, and never modified once accepted — instead superseded by a new ADR. Writing ADRs serves both as a historical record and as a tool to clarify thinking and surface disagreements within teams. Each ADR has a lifecycle status (proposed, accepted, superseded) and should include trade-offs, confidence levels, and triggers for re-evaluation. Martin Fowler traces the term to Michael Nygard's 2011 article and points to tools like adr-tools for managing them.