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.

ADR vs. design document

A design document explores options; an ADR records the 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.

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.