Course contentsShow
← Software Engineering
Lesson 1699 of 1,93349. Technical Writing and DocumentationFree lesson

The Structure of an ADR

Understand the standard ADR template: title, status, context, decision, and consequences sections.

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.