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.

What goes in an ADR document?

One ADR document records one decision. The minimum useful record names the forces that shaped the choice, the choice itself, and the tradeoffs the team accepts. Most templates express that with these 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.

ADR lifecycle and status

Status is part of the lifecycle, not a substitute for consequences. A record commonly moves from Proposed to Accepted or Rejected. Later it can be Deprecated or Superseded by a new ADR that links back to it. Keep the old record: the history is the reason the log remains useful. 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.

ADR document vs. architecture decision log

An ADR document contains the rationale for one decision. An architecture decision log is the collection and index that makes all of those records discoverable. Start with one document; add a lightweight index once the repository has enough records that filenames alone are hard to scan.