Architecture Decision Record Template

WHEN TO USE IT For a decision that is expensive to reverse and that a future engineer would otherwise reverse without knowing why it was made — a datastore choice, a boundary between services, a build tool, an authentication approach. Not for decisions a code review captures adequately. The signal you needed one is hearing "why on earth is it done this way?" about a choice that was, in context, correct. HOW TO USE IT Write it when the decision is made, not afterwards. One page. Store it in the repository next to the code it governs, numbered and never renumbered. Do not edit an accepted record to reflect a later change of mind — write a new one that supersedes it, and mark the old one superseded. The history is the value. Include the options you rejected. A record that lists only the chosen path cannot tell a future reader whether their "obvious" alternative was already considered. THE TEMPLATE # ADR-00N — <decision in one line> Status: proposed | accepted | superseded by ADR-00M Date: <yyyy-mm-dd> Deciders: <names> ## Context What forces are in play: constraints, scale, team shape, deadlines, existing commitments. Enough that a reader can judge whether the same forces still apply to them. ## Decision What we are doing, stated actively: "We will ..." ## Consequences What becomes easier, what becomes harder, and what we are now committed to. Include the ones you dislike — a record listing only benefits reads as advocacy and gets discounted. ## Alternatives considered Each with the reason it was not chosen. This is the section future readers use most. ## Revisit when The condition that should reopen this — a scale threshold, a cost, a dependency changing. Without it, the decision is permanent by accident. ADAPTING IT Add a "compliance impact" section in regulated environments. Teams new to the practice should start by writing records for decisions already made and still contested — it is faster than it sounds and immediately useful. The "revisit when" field is the one most templates omit and the one that keeps a record honest. See /decisions for worked comparisons of the choices these records usually capture, and /platform-engineering for the surrounding practice.