What is an Architecture Decision Record (ADR)?

An Architecture Decision Record is a short document that captures one significant engineering decision: the context that forced it, the options considered, the choice made, and its consequences. One decision, one record, written when the decision happens - so that a year later, nobody has to reverse-engineer the why.

Why teams write ADRs

Every codebase is a pile of decisions, but the code only shows the outcomes. The reasoning - why Postgres over DynamoDB, why a monolith, why this queue - lives nowhere unless someone writes it down. Teams adopt ADRs because the alternative is expensive in familiar ways: new engineers re-ask settled questions, departed engineers take context with them, and teams relitigate choices because nobody can say what constraints shaped them. An ADR is the cheapest known insurance against all three.

A minimal template

The best template is the one your team actually fills in. This five-part shape, adapted from Michael Nygard's widely used original, is deliberately small:

  • Title and status. A number and a name (“ADR-014: Move session storage to Redis”), plus a status: proposed, accepted, deprecated, or superseded.
  • Context. The forces at play: the problem, the constraints, what made the status quo untenable. Written so a stranger understands why a decision was needed at all.
  • Options considered. The real alternatives, each with a sentence on why it lost. This section is the one teams skip - and the one future readers need most.
  • Decision. What you chose, stated plainly.
  • Consequences. What gets better, what gets worse, and what you are explicitly accepting - the tradeoff, on the record.

Keep each ADR under a page. Store them in the repository next to the code they describe (a docs/adr/ folder is the common convention) so they travel with the system and show up in code review.

When to write one

Not every choice deserves a record. The working test: will someone plausibly ask “why is it like this?” in a year? Datastores, service boundaries, frameworks, build-vs-buy, deprecations, and anything expensive to reverse - yes. Naming a variable - no. If a debate took more than one meeting, that is usually a signal the reasoning is worth preserving.

Where ADRs fall short

ADRs are the best lightweight practice available, and honest teams still hit the same three walls. First, coverage: ADRs capture the decisions someone remembered to write down - in practice a fraction of the ones that matter, because many decisions happen in tickets, pull requests, and meetings and never feel like “architecture” at the time. Second, staleness: a record written once drifts from reality unless someone maintains statuses and supersessions by hand, and almost nobody does. Third, discoverability: a folder of Markdown files answers “what did we write down?” but not “what did we decide about the billing service?” - the connections between decisions, evidence, and outcomes are left for the reader to reconstruct.

None of that is a reason to skip ADRs. It is a reason to treat them as raw material for something more durable. That is the problem Rationale works on: it reads the artifacts your team already produces - ADRs, tickets, design docs, pull requests - and maintains the decisions, evidence, tradeoffs, and supersessions as a connected, current Decision Map, so the reasoning stays findable after the folder of Markdown files has gone quiet.