What is an ADR?

An Architecture Decision Record is a short document that explains a non-trivial technical decision. It is optimized for a reader who needs the rationale months or years later—not for a pitch deck, and not for an exhaustive spec.

Typical sections:

• Context — constraints, unknowns, and the forces that make a choice necessary.
• Decision — what you are doing, in plain language, without burying the answer in background.
• Consequences — what gets easier, harder, or deferred, including follow-up work.

Status (Proposed, Accepted, Superseded, …) is part of the lifecycle, not a substitute for consequences. If you only write status and a title, you have a ticket title, not an ADR.

When should you write an ADR?

Not every technical choice needs a record. A good heuristic: will someone ask “why?” in six months? If so, write it down now while the tradeoff is still legible.

• Choosing between viable alternatives (database, framework, protocol).
• A constraint that is not obvious from the code (compliance, cost, deadline).
• Reversing or superseding a previous decision.
• Any choice that would be expensive to undo without context.

Skip it for trivial choices that are obvious from the diff, or decisions that only affect a single function and carry no cross-cutting consequence.

ADR vs. design document

An ADR is not a solution overview. It is the evaluation of a single decision—what you chose, what you rejected, and why. A design document explores options and may span many decisions; an ADR records one outcome once you commit. It can reference longer docs, performance numbers, or RFC threads—those belong in links and appendices, not in place of a crisp decision.

Chesterton's fence

ADRs solve the Chesterton's fence problem: before tearing down a decision, you can read why it was built. The key benefit is that decisions and their background are documented so that in the future, when you have a question about why something works the way it does, you have an answer—without a scavenger hunt through Slack threads and old tickets.

Where ADRs live

Most teams keep ADRs in git next to the code they affect, often under a path like docs/adr/. Numbering (ADR-0001, …) keeps merge order and cross-references unambiguous. Some teams add a team or service prefix; pick one convention and document it in your contributing guide. The set of those files, plus an index, is an architecture decision log; a single file is the ADR document for that decision.