Writing an Architecture Decision Record: Decisions, Alternatives, Consequences, and Reconsideration Conditions

Welcome back. In the preceding lessons, you translated flash-sale goals into measurable scenarios, modeled the expected load, made assumptions and risks explicit, and compared three deployment strategies with a trade-off matrix. The matrix produced a provisional recommendation: a zone-redundant deployment in one primary region, with backups in a secondary region.

That recommendation is still fragile if it survives only in a meeting, a spreadsheet, or someone’s memory. This lesson turns it into an Architecture Decision Record (ADR): a compact, durable statement of what was decided, why, what alternatives were rejected, what consequences the team accepts, and what changed conditions should reopen the decision.

---

ADRs preserve the “why,” not just the “what”

An ADR is a short document that records one architecturally significant decision. “Architecturally significant” does not mean every technical preference. It means a decision that substantially affects the system’s structure, a key quality attribute, an important dependency or interface, or something expensive to reverse later.

For example, these probably deserve ADRs:

• choosing zone-redundant rather than single-zone deployment for a revenue-critical checkout path;
• deciding that accepted orders are persisted before payment is confirmed;
• selecting a message broker shared by several services;
• adopting a modular monolith rather than independently deployed services.

These usually do not:

• selecting a variable name;
• choosing a minor internal helper library;
• changing a dashboard color;
• documenting a routine implementation detail that follows from an already accepted decision.

The distinction matters because ADRs are not intended to become a complete design manual. They are a decision log. Their value is greatest months later, when a teammate asks, “Why is this system deployed this way?” or, “Why didn’t we choose multi-region failover?”

The answer should not be “because that was the standard at the time.” It should reveal the decision context:

• what business outcome mattered;
• what constraints and evidence existed;
• what was traded away;
• which assumptions remained uncertain;
• what future event would make the decision no longer fit.

This is why an ADR should record a decision under conditions, not present an architecture as universally correct.

An ADR is normally written while the decision is being considered, not reconstructed only after an incident or a departure makes the original reasoning hard to recover. Its initial status may be Proposed. Once the relevant team accepts it, it becomes Accepted. If circumstances later demand a materially different decision, create a new ADR that Supersedes the old one and link them.

Do not quietly rewrite an accepted ADR to make history look tidier. The old record explains why the old decision was reasonable under its original circumstances; the new record explains why those circumstances no longer apply.

The review lifecycle in the diagram highlights an important practical point: a proposed ADR need not be accepted immediately. Review may expose missing data, an unexamined alternative, or an operational responsibility nobody can yet support. In that case, the appropriate outcome is not a forced decision. It is a revised proposal with explicit action items.

---

The anatomy of a decision-quality ADR

A useful ADR follows a predictable shape. Consistency matters because it lets a future reader scan many decisions quickly. Microsoft’s guidance also emphasizes that ADRs should capture the problem, considered options, decision outcome and trade-offs, confidence, and status.

A practical template can be small:

# ADR-0012: Zone-redundant primary-region deployment for checkout

**Status:** Proposed
**Date:** 2025-03-08
**Owner:** Checkout architecture group

## Decision
We will ...

## Context and decision drivers
...

## Options considered
...

## Consequences
...

## Confidence and validation
...

## Conditions for reconsideration
...

## Related material
...

The sections are short, but they have distinct jobs.

Section	Question it answers	Common mistake
Title and status	What decision is this, and is it active?	Vague titles such as “Deployment thoughts.”
Decision	What will the team actually do?	Describing debate without making a clear choice.
Context and drivers	Why was a decision needed now?	Repeating all project background instead of the relevant constraints and scenarios.
Options considered	What serious alternatives were rejected, and why?	Listing every idea raised in a meeting.
Consequences	What benefits, costs, risks, and obligations follow from the choice?	Recording only benefits.
Confidence and validation	Which claims are established, estimated, or unverified?	Presenting assumption-dependent claims as facts.
Conditions for reconsideration	What future changes would invalidate the decision’s rationale?	Writing “review later” without a trigger.

Lead with the decision

A reader should find the architectural commitment near the top. Prefer a direct statement:

We will deploy the checkout workload across availability zones in one primary region and retain recoverable backups in a secondary region.

Avoid language such as:

It seems that zone redundancy may be the most appropriate option.

The second sentence reports an opinion. The first creates an accountable decision that engineers can implement, operators can prepare to support, and reviewers can challenge.

Keep context selective and measurable

The context should include only facts necessary to understand the choice. In the flash-sale case, that includes the 200 requests-per-second sustained load, the 300 requests-per-second burst, the two-second p99 acknowledgement target, the unacceptable risk of losing accepted orders, and the small operations team.

It does not need a long history of the product, detailed component diagrams, or a complete cost worksheet. Link those supporting artifacts instead.

Separate alternatives from consequences

These sections are often blurred together.

Alternatives explain why another plausible choice was not selected at decision time. For example, single-region baseline deployment was rejected because a regional outage would require manual recovery and could consume much of a time-limited sale window.

Consequences describe what the chosen option now requires. Zone redundancy may improve tolerance of a zone failure, but it also means the team must verify each managed dependency’s failure semantics, provision redundant capacity, and rehearse recovery.

The distinction prevents an ADR from becoming a vague list of pros and cons.

---

From a trade-off matrix to a finished ADR

The previous lesson’s matrix should make this ADR much easier to write. The matrix supplied the options, quality-attribute scenarios, key evidence, trade-off points, and provisional recommendation. The ADR compresses those into a decision that can stand on its own.

Here is a decision-quality draft for the flash-sale checkout system.

# ADR-0012: Zone-redundant primary-region deployment for flash-sale checkout

**Status:** Proposed  
**Date:** 2025-03-08  
**Owner:** Checkout architecture group  

## Decision

We will deploy the Checkout API, order persistence layer, and payment-work queue
with availability-zone redundancy in one primary region. We will maintain backups in
a secondary region for regional recovery.

The checkout acknowledgement path will not synchronously depend on a second region.
An order is considered accepted only after its required order data is durably persisted
in the primary region and payment work has been recorded for asynchronous processing.

## Context and decision drivers

The flash sale requires checkout to acknowledge accepted orders within two seconds at
p99 while sustaining 200 requests per second and handling an opening burst of
300 requests per second.

Losing an accepted order is unacceptable. Delayed payment confirmation is acceptable
when the accepted order is durable and the customer is clearly informed. The operations
team is small, so a design requiring continuous multi-region failover operations is not
currently supportable. The business may expand to another geography within two years,
but has no current requirement to continue checkout through a full regional outage.

## Options considered

1. **Single-region baseline with secondary-region backups**
   - Lowest cost and simplest routine operation.
   - Does not meet the preferred recovery posture for a zone failure and requires a
     manual regional recovery procedure.

2. **Zone-redundant primary region with secondary-region backups**
   - Tolerates a supported availability-zone failure while retaining a contained
     operating model.
   - Increases infrastructure cost and requires validation of zone support and
     failover behavior for every critical managed dependency.

3. **Multi-region active-passive deployment**
   - Could reduce service interruption after a regional outage.
   - Adds asynchronous replication, failover routing, reconciliation, monitoring,
     data-residency review, and regular failover-exercise obligations that exceed
     the current team capacity and budget.

## Consequences

Positive consequences:
- Checkout has stronger protection against an availability-zone failure than the
  single-region baseline.
- The critical acknowledgement path avoids cross-region synchronous latency.
- The design retains a clear later migration path if regional resilience or geographic
  expansion becomes a demonstrated requirement.

Negative consequences and obligations:
- Redundant capacity and service tiers increase recurring cost.
- The team must verify that each critical dependency has the required zone-redundant
  behavior; application redundancy alone is insufficient.
- A full regional outage still requires recovery from backups and may interrupt
  checkout for longer than a multi-region design.
- Operations must maintain alerts, runbooks, and recovery exercises for zone and
  regional failure scenarios.

## Confidence and validation

**Confidence:** Medium.

Before accepting this ADR, the team must:
- load-test the acknowledgement path at sustained and burst traffic, confirming the
  two-second p99 target;
- verify availability-zone support, failover behavior, and durability semantics for
  compute, database, and messaging dependencies;
- test payment-provider quota behavior, queue retention, and payment-backlog recovery;
- rehearse the zone-failure response and the secondary-region recovery runbook.

## Conditions for reconsideration

Create a superseding ADR if any of the following occurs:
- tested p99 acknowledgement latency exceeds two seconds at the agreed workload;
- a business or regulatory requirement requires checkout to continue through a full
  regional outage with a recovery objective this design cannot meet;
- the business begins serving a second geography whose latency or data-residency needs
  require regional deployment;
- repeated incidents or recovery exercises show that regional restoration is not
  operationally acceptable;
- the organization gains the staffing, automation, and budget needed to operate
  multi-region failover responsibly.

## Related material

- Flash-sale workload model
- Assumption log ASM-01 through ASM-05
- Deployment trade-off matrix
- Checkout failure-mode analysis

This draft is deliberately Proposed, not Accepted. The trade-off matrix supported the choice, but several decisive claims remain unvalidated: capacity at the burst, actual availability-zone support, payment-provider behavior, and recovery performance.

That distinction is important:

• Validation criteria determine whether the proposed ADR is ready to be accepted.
• Reconsideration conditions determine when an already accepted ADR should be replaced.

For example, “verify zone failover semantics” is an acceptance gate because the team needs the answer before relying on the design. “Begin serving a second geography” is a reconsideration trigger because it may happen later and alter the business context.

---

Write for future readers under pressure

ADRs are often read during design changes, production incidents, audits, or onboarding. Under those conditions, concise and factual writing matters more than polished prose.

A final editing pass should test the ADR against these criteria:

1. One decision: Can the decision be stated in one sentence? If it contains several independently reversible choices, split it into multiple ADRs.
2. Clear commitment: Does the decision use direct language such as “We will”?
3. Decision-relevant context: Are the key scenarios, constraints, and organizational limits explicit?
4. Real alternatives: Would a reasonable reviewer recognize the options as viable candidates rather than straw figures?
5. Visible costs: Does the record state negative consequences and operating obligations as clearly as benefits?
6. Honest uncertainty: Are confidence and needed validation stated explicitly?
7. Concrete triggers: Could a future team identify whether the decision should be revisited without rediscovering the entire original debate?
8. Accessible home: Is the ADR kept with the system documentation or source repository where the people changing the system can find it?

The goal is not to defend a choice forever. It is to make the choice inspectable. A later team may reasonably supersede it, but should be able to see exactly which facts changed: perhaps the recovery objective tightened, a second region became necessary, or evidence showed that the operational burden was lower than expected.

---

Key takeaways

An ADR records a single, architecturally significant decision in the context that made it reasonable. Its core content is the decision, relevant context, alternatives considered, consequences, confidence and validation needs, and explicit conditions for reconsideration.

Use the trade-off matrix and assumption log as inputs rather than duplicating them. The ADR should be concise enough to scan, but specific enough to reveal the decision’s quality-attribute commitments and accepted risks.

Treat accepted ADRs as an append-only historical record. When circumstances materially change, write and link a new ADR that supersedes the original rather than rewriting history.

In the next module, the focus shifts from deployment decisions to service boundaries: identifying business capabilities and domain invariants that should shape the boundaries between modules or services.