Architecture Decision Records (ADRs)

An Architecture Decision Record (ADR) is a document that captures an important [[Architecture Decision (AD)]] made along with its context and consequences.

Structure

A typical ADR includes:

• Title: Short description of the decision
• Status: Proposed, accepted, deprecated, superseded
• Context: What forces are at play
• Decision: What we decided to do
• Consequences: What becomes easier or harder

Purpose

ADRs help:

• Document why decisions were made
• Preserve context for future team members
• Enable better decision-making over time
• Create institutional memory
• Avoid revisiting settled decisions

Related Concepts

• [[Architecture Decision Log (ADL)]] — the collection of ADRs for a project or organization
• [[Architecture Decision (AD)]] — the decisions that ADRs document
• [[Architecturally-significant Requirement (ASR)]]
• [[Engineering Strategy]]
• [[A Note on Distributed Computing]]
• Software architecture
• Technical documentation

References

• Architecture Decision Record (GitHub) — comprehensive guide and examples