Don't Panic: Architecture Decision Records

An architecture decision record is a small document that remembers why a consequential technical choice was made. This is valuable because code is very good at proving that a choice happened and remarkably bad at explaining the constraints, rejected options, and trade-offs that made it sensible at the time.

The useful shape is context, credible options, one decision, and consequences. Context names the forces before the choice: requirements, constraints, risks, assumptions, and tensions. Consequences name the conditions after it: benefits, costs, risks, follow-up work, and new limits. The decision sits between them, doing the difficult work of being specific without pretending the future has signed a contract.

One record should hold one decision. That sounds fussy until a document called Choose the Entire Architecture arrives and quietly contains choices about data, deployment, interfaces, ownership, and operations. Those choices can change independently, so they need records that can be reviewed, linked, and replaced independently. The decision log is the collection of those records, a map of how the system acquired its current personality.

An ADR is not a tiny constitution. It does not decide who has authority, enforce implementation, or prove that the team was right. Teams still need review, tests, policies, and operational evidence. The record gives those controls a durable statement of intent, which is less glamorous than magic and rather more useful when a requirement changes.

Status is the part that prevents historical improvisation. A proposed record is under review. An accepted record describes the direction that was chosen. When new evidence changes that direction, write a new record and mark the old one superseded. The earlier decision stays visible because its original context may explain code, data, or operational constraints that have not yet vanished.

Start with the intro for the full mental model and lifecycle. Use the slides to see the relationships at a glance. Keep the cheatsheet nearby while drafting or reviewing a record, especially its selection test and option comparison card. The practice section turns that structure into a repeatable technique, and the exercise asks you to make the trade-offs visible in a proposed decision.

Don't Panic: Architecture Decision Records

Relevant careers