The Structure of an ADR
You'll learn the standard template that makes ADRs consistently useful across projects.
An Architecture Decision Record (ADR) follows a structured format to capture key information about important technical decisions. Think of it like a medical chart—every doctor knows where to find the patient's allergies, medication list, and vital signs because the format is standardized. Similarly, every engineer should know where to find the context, reasoning, and consequences of an architectural decision.
The Five Core Sections
Title
A short, numbered descriptor like "ADR-001: Use PostgreSQL for primary database" that immediately tells you what was decided.
Status
The current state: Proposed, Accepted, Deprecated, or Superseded (with a reference to the replacing ADR). This prevents confusion about whether a decision still applies.
Context
The situation that prompted the decision. What problem needed solving? What constraints existed? What options were considered? This section answers "Why did we even need to make a decision here?"
Decision
The actual choice made, stated clearly and definitively. "We will use PostgreSQL as our primary relational database." No ambiguity, no hedging.
Consequences
Both positive and negative outcomes expected from this decision. What becomes easier? What becomes harder? What technical debt might accumulate? This honest assessment helps future teams understand the trade-offs.
Why This Structure Works
The template separates facts (context), choices (decision), and outcomes (consequences) so readers can quickly understand not just what was decided, but why it made sense at the time. When revisiting a decision years later, this structure prevents "why on earth did they do it this way?" moments.
Key Takeaway: The standard ADR template—title, status, context, decision, consequences—creates a consistent, scannable record that captures both the choice and the reasoning behind architectural decisions.