Architecture Decision Record Template
An ADR should preserve the reasoning that will otherwise disappear after a few months. Keep it short enough to write while the decision is being made and specific enough that a future engineer can tell why the obvious alternative was rejected.
Keep it short enough that people will maintain it
Architecture Decision Record Template
Title and status
Decision title, date, owners and status: proposed, accepted, superseded or deprecated.
Context
What problem are we solving? What changed, and why does a decision need to be made now?
Constraints
Security, regulatory, cost, team, operational, compatibility or timeline constraints that materially limit the options.
Options considered
List the credible alternatives. For each, record the advantage, operational cost and the reason it was not selected.
Decision
State the chosen option in one or two direct sentences. Avoid repeating the entire context.
Consequences
What becomes easier? What becomes harder? What new operational work or dependency does this choice create?
Revisit when
Name the conditions that would make this decision worth reopening, such as traffic level, team size, vendor limitation or regulatory change.
Related engineering work
Talk to the engineers who would do the work
Bring your current architecture, constraints and the problem you are trying to solve. We will tell you what we would change first, what it depends on, and where we would start.