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

What Are Architecture Decision Records (ADRs)?

Learn the purpose of ADRs as lightweight documents capturing significant architectural choices and their context.

What Are Architecture Decision Records (ADRs)?

You'll learn: What ADRs are and why teams use them to capture important architectural choices in a lightweight, structured way.

The Core Idea

Architecture Decision Records (ADRs) are short, numbered documents that capture significant architectural decisions made during a project's lifetime. Think of them as a decision journal for your system—each entry explains what was decided, why it was chosen, and what alternatives were considered.

Unlike heavy architecture documentation that becomes outdated quickly, ADRs are lightweight snapshots frozen in time. They don't change after being written (except to mark them as superseded). This creates a historical record showing how and why your architecture evolved.

Why ADRs Matter

Software systems accumulate decisions over months and years. Without documentation, future team members (or your future self) ask: "Why did we choose PostgreSQL over MongoDB?" or "Why is authentication handled this way?" ADRs answer these questions by preserving the context that existed when the decision was made.

What Goes in an ADR

A typical ADR includes:

  • Title: A short, descriptive name
  • Status: Proposed, accepted, superseded, deprecated
  • Context: The situation requiring a decision
  • Decision: What was chosen
  • Consequences: Expected outcomes, trade-offs, and risks
  • Alternatives: What else was considered and why it wasn't chosen

ADRs live alongside your code (often in a docs/adr/ directory), making them discoverable and version-controlled. They complement other documentation types like design documents and architecture overviews but focus specifically on decisions rather than describing the entire system.

Key Takeaway: ADRs are lightweight, immutable records that capture significant architectural decisions with their context, rationale, and consequences—creating a decision trail that helps current and future team members understand why the system evolved as it did.