Architecture Decision Records

Every codebase has decisions nobody remembers making. Why this state library? Why is that service separate? Why do we version routes like this? An Architecture Decision Record (ADR) captures one significant decision and its reasoning, in the repo, at the time it’s made. The collection becomes a decision log: a readable history of why the system looks the way it does.

The format

Michael Nygard’s template is still the one most teams use:

# 7. Split pull-request and merge pipelines

Status: Proposed | Accepted | Deprecated | Superseded by 12
Date: 2026-10-08

## Context
The forces at play, the constraints, what's true today.

## Decision
"We will…" — active voice, one decision.

## Consequences
Good, bad, and the follow-up work this creates.

Many teams add Alternatives considered. It’s often the most valuable section for future readers, because it answers “didn’t anyone think of X?” before it’s asked.

Rules that make them work

• Immutable once accepted. When a decision changes, write a new ADR that supersedes the old one. The old reasoning stays readable, and that’s the point.
• Stored with the code, in docs/adr/, and reviewed in pull requests like code. The PR discussion becomes the decision forum.
• Short. One page. If it needs more, link to a design doc.

What deserves one?

Anything costly to reverse, or anything people will later ask “why did we…?” about: a framework, a state-management approach, an API style, an auth strategy, a monorepo, a gateway. Not every library bump.

The leadership angle

What I like most about ADRs is who they empower. I first used them on a client project where they were the route for anyone, not just leads, to propose an architectural change. A well-argued ADR from a mid-level developer carried the same weight as one from a lead. That’s a healthier culture than decisions made in meetings that half the team missed.

In practice

When I join a codebase, the ADR folder is the first thing I read. When there isn’t one, I start it by backfilling the three decisions people ask about most. It’s also the natural place to record trade-offs like those in the CAP Theorem or the failure model a system assumes (Types of Failure). See also Design Review Readiness Checklist for the step before a decision is made.