Architecture Decision Record (ADR) Template

Context

Describe the situation that requires a decision. What is happening in the system, the team, or the business that forces us to choose? Include enough background that someone reading this ADR in two years — who was not in the room — can understand why this decision was needed.

Address:

• What problem are we facing? What is broken, missing, or about to break?

• What technical, organizational, or business constraints are in play?

• What has changed since the last time we addressed this area (if applicable)?

• What is the cost of not deciding? What happens if we do nothing?

Decision Drivers

List the criteria that matter most for this decision, in priority order. These are the factors the team will weigh when evaluating options. Being explicit about drivers prevents the discussion from going in circles.

Options Considered

Describe each option honestly. A good ADR explores at least two real alternatives — if there is only one option, you are documenting an implementation, not a decision.

Option 1: [Name] (Chosen)

Describe what this option is and how it works at a high level.

Effort estimate: Approximate implementation cost (t-shirt size, person-weeks, or sprint count).

Option 2: [Name]

Describe what this option is and how it works at a high level.

Effort estimate:

Option 3: [Name] (Optional)

Include a third option if it was seriously considered. Delete this subsection if only two options were evaluated.

Comparison

Score each option against the decision drivers. This makes the trade-offs visible and the reasoning auditable.

Decision

State the decision clearly, starting with "We will..." Be precise enough that someone can implement it without ambiguity.

We will [chosen option] because [primary justification]. This was chosen over [rejected option] because [key differentiator], despite [acknowledged trade-off].

Consequences

Be honest about what this decision means — the good, the bad, and the obligations it creates.

What becomes easier or better

• Positive consequence of this decision

• Another positive consequence

What becomes harder or worse

• Negative consequence or new constraint this decision introduces

• Technical debt or operational burden this creates

What we must now do

Decisions create obligations. List the follow-up work this decision requires:

• Migration or implementation work that must happen

• Documentation, runbooks, or monitoring that must be updated

• Teams or systems that must be notified

Risks & Mitigation

What could go wrong with this decision, even if the implementation is flawless?

Validation

How will we know this decision was the right one? Define the signals you will look for and when you will evaluate.

Related Decisions

Link to ADRs that this decision depends on, supersedes, or is related to. This builds a navigable decision history.