ADRs: Decisions with Trade-offs in Context

Why this matters

A platform choice made two years ago puzzles every new engineer, and nobody can say what problem it solved or what was rejected. The choice might be right, but without its context it cannot be revisited, only obeyed or resented. Revisits happen anyway (new scale, new team, new constraints) and without the record they restart from zero, re-litigating settled trade-offs while missing the one assumption that actually expired. ADRs are cheap insurance against organizational amnesia.

Concepts

An ADR holds five sections. Context: the problem, constraints and forces at decision time. Decision: what was chosen, in one paragraph a stranger can quote. Consequences: what gets better, what gets worse, what must now be maintained. Alternatives: what was rejected and why, with the trade-off stated fairly (a straw alternative teaches nothing). Assumptions: what was believed but not proven, listed so the future can verify rather than guess. Status tracks life: proposed, accepted, deprecated, superseded with a link forward.

Good ADRs are short and specific. One decision per record (bundled decisions cannot be revisited separately). Numbers where they exist (measured load, quoted costs, cited budgets). Named owners and dates. The L70-adjacent habit from the brief (comparing designs under constraints) starts here: the ADR is where the comparison lives after the meeting ends.

Supersede, never rewrite. When context changes, a new ADR records the new decision and links the old as superseded; history stays readable and the evolution teaches. Silent edits to accepted records destroy the trust that makes revisits safe. The log of supersessions is the architecture's autobiography: read it before proposing the next change.

Worked example

A fictional platform choice (build queue versus managed service under given constraints) gets an ADR: context with numbers, decision in one paragraph, consequences both directions, two fairly stated rejected alternatives, three unproven assumptions listed. A later constraint change supersedes it with a link; both records read cleanly in sequence.

Common wrong move

Writing ADRs after the fact as justification theater. A record that only ever supports what was already built teaches cynicism; decisions with real alternatives, stated trade-offs and listed assumptions teach judgment. Write before building where possible, honestly after where necessary.