Chapter 2 · Practice 3 of 4

Record significant decisions as Architectural Decision Records

Why it matters

An Architectural Decision Record (ADR) captures one significant decision, its rationale, its trade-offs and its consequences. The collection of ADRs in a project forms its decision log. The idea was popularised by Michael Nygard in 2011.

ADRs answer the question every new team member eventually asks: "Why did we do it this way?"

A minimal ADR:

markdown

# 0007: Use PostgreSQL for the orders service

Status: Accepted (2026-10-02)

## Context
Orders need transactions across several tables and ad hoc reporting.

## Decision
Use PostgreSQL with one schema per service.

## Consequences
Reporting queries run on a read replica. Teams need migration tooling.

Keep ADRs in the repository next to the code, number them, and never edit an accepted one: write a new ADR that supersedes it.

Store ADRs in the repository
Supersede old ADRs instead of editing them

Avoid

Decisions that live only in a chat thread or someone's memory

Example

Code

docs/adr/
  0001-record-architecture-decisions.md
  0006-use-feature-flags-for-releases.md
  0007-use-postgresql-for-orders.md