Decisions on Record: ADRs

Teams make big, hard-to-reverse decisions — which database to use, which architecture to follow — and six months later, nobody remembers why. An Architecture Decision Record (ADR) is a short, dated note that captures a decision, the context around it, and the alternatives that were considered. It's how a team's reasoning survives.

The value of an ADR isn't the decision itself (the code already reflects that); it's the why. Knowing why a choice was made stops future teams from either blindly trusting it or pointlessly re-arguing it.

Think of meeting minutes for the important calls — a brief record of what was decided and the reasoning, so future-you knows not just what the code does, but why it was built that way.

The Problem

Without records, decision rationale evaporates. A new developer finds an odd-looking choice and wonders: was this a mistake, or is there a good reason? Often nobody knows anymore, so the team either leaves it alone out of fear, or rips it out and rediscovers the original problem the hard way. "Why on earth is it like this?" is a question that wastes enormous amounts of time on real teams — and an ADR answers it.

What an ADR Captures

A good ADR is short and captures a few things: the decision (what we chose), the context (the situation and constraints at the time), the options considered (and why the others lost), and the consequences (what this choice commits us to). That's it — usually a single page. The point is to record enough reasoning that a future reader understands the choice without having been in the room.

Lightweight and Immutable

ADRs are deliberately lightweight — a short file per decision, kept right alongside the code in version control. And they're immutable: you don't edit an old ADR when you change your mind; you write a new one that supersedes it. That way the history of how thinking evolved is preserved, not overwritten. The trail of decisions, including the ones later reversed, is itself valuable.

Decisions vs Comments

How is this different from a code comment? A comment explains a specific line or function — local, small-scale. An ADR explains a direction — a big, cross-cutting choice that shaped the whole system. Comments answer "what does this line do?"; ADRs answer "why is the system built this way at all?" Both matter, at different scales.

The Cadence team writes a one-page ADR for "we chose a monolith, not microservices" (from Chapter 5), listing the four-person team size and modest traffic as the reasons, and noting they'd revisit it if they grew. A year later, when a new hire wonders why Cadence isn't split into services, the answer is right there in the ADR — so nobody wastes a sprint re-arguing a question that was already settled, for good reasons, on purpose.