What an ADR is, and what it is not

An architecture decision record captures a single significant decision: the situation that forced a choice, the option you picked, and the consequences you are accepting. The format popularized by Michael Nygard is deliberately small - a title, a status, the context, the decision, and the consequences - so that writing one takes twenty minutes, not a day.

It is not a design document and it is not a specification. A design doc explains how a system works; an ADR explains why one particular fork was taken. That distinction keeps ADRs short enough that people actually write and read them.

Record the alternatives you rejected and why. The rejected options are the part future readers need most, because they are the ones that will be proposed again.

Rules that keep an ADR log useful

Store ADRs in the repository next to the code, numbered and dated, so they are versioned and reviewed in the same pull requests as the change they justify. Treat accepted records as immutable: when a decision changes, write a new record that supersedes the old one and link the two. The history of how your thinking evolved is itself valuable.

Write one when a decision is hard to reverse or affects more than one team - choice of datastore, service boundaries, authentication approach, a major framework, a build-versus-buy call. Do not write one for choices you could undo in an afternoon.

Status is part of the record

Proposed, accepted, deprecated, or superseded - a reader should know at a glance whether a record still applies.

Review it like code

Decisions debated in a pull request get sharper, and the discussion is preserved with the change.

Why ADRs matter more with AI coding assistants

AI coding assistants read the repository you give them. Without recorded reasoning, an assistant sees only what the code does, so it will happily propose the exact pattern your team rejected last quarter. A small folder of decision records gives both new engineers and AI tools the constraints that are not visible in the code.

The same applies to agents that modify infrastructure or open pull requests: recorded decisions are a cheap, human-readable guardrail that tells them which paths are off the table and why.

Want an architecture review that leaves your team with documented decisions instead of a slide deck? See our code audit or talk to us.

Key takeaways

  • An ADR captures one significant decision - context, the choice, and its consequences - in a page or less.
  • Keep records in the repository, numbered and dated, and supersede rather than edit them when a decision changes.
  • Always record the rejected alternatives; they are the options most likely to be proposed again.
  • Decision records give AI coding assistants and new engineers the constraints that are invisible in the code itself.