Writing Architecture Decision Records (ADRs)
Practice writing clear ADRs: the decision, context, consequences, and alternatives considered.
ADR structure and vocabulary
- Status: Proposed / Accepted / Deprecated / Superseded by ADR-XXXX
- Context: current behaviour + quantified trigger + measured impact — no solution
- Decision: "We will use X..." — imperative, present tense, how + why
- Consequences: Positive / Negative / Neutral — honest about trade-offs
- Alternatives: "We rejected X because..." — specific named option + specific reason
Question 0 of 5
Which ADR status label correctly describes a decision that has been reviewed and is now binding?
ADR status vocabulary follows the Nygard convention: Proposed → Accepted → Deprecated → Superseded.
- Proposed — the ADR has been written and is open for review. No action should be taken on it yet.
- Accepted — the decision has been reviewed and agreed. It is now the binding direction for the team.
- Deprecated — the decision is no longer recommended but has not been replaced. It may still be in use.
- Superseded by ADR-0042 — this decision has been replaced by a newer ADR. Always link to the superseding ADR.
Which passage correctly writes the "Context and Problem Statement" section of an ADR?
The "Context and Problem Statement" section describes the situation that makes a decision necessary — without proposing a solution.
- Current behaviour described precisely — "sends emails synchronously within the HTTP request-response cycle" — the reader understands the mechanism of the problem.
- Quantified trigger — "12,000 messages per hour during peak periods" — establishes that this is a scaling problem, not a design smell at low volume.
- Measured impact — "p99 latency spikes to 4.2 seconds" vs. "2-second SLA target" — the problem is framed as a concrete SLA breach, not a vague complaint.
Which sentence correctly writes the "Decision" section of an ADR?
The "Decision" section uses imperative present tense ("we will") and describes not just what technology is chosen but how it will be used.
- "We will use..." — active voice, first person plural, present tense. ADRs use "we will" (not "it was decided to" or "the team should consider"). The imperative language signals that this is a binding direction, not a suggestion.
- How it will be used — "all notification-triggering endpoints will enqueue a message and return immediately" — describes the integration pattern, not just the technology choice.
- Operational boundary — "a dedicated consumer process will handle delivery, retries, and dead-lettering independently of the API process" — establishes the operational model, which is essential for planning deployment and monitoring.
Which passage correctly writes the "Consequences" section of an ADR?
The "Consequences" section must enumerate positive, negative, and neutral consequences — not just the benefits.
- Positive — the direct benefit that motivated the decision. Must connect to the problem statement.
- Negative — the honest downsides. "Eventually consistent" is a real trade-off that could matter for specific notification types. Naming it prevents future surprise and invites reviewers to flag cases where it is unacceptable.
- Neutral — changes that are neither good nor bad but must be acknowledged. "Adds operational complexity" is honest; "but team already has expertise" contextualises it. Neutral consequences often cover: new dependencies, changed operational patterns, team skill requirements.
Which passage correctly writes the "Alternatives Considered" section with proper rejection language?
"We rejected X because..." is the standard ADR rejection language — it must name the specific option and give a specific technical or business reason.
- Each alternative named and described — "Amazon SES direct async call" — not just "Option A". The reader must understand what was considered.
- "We rejected this because..." — active voice, past tense for the rejection decision. Clear ownership of the decision.
- Specific rejection reason — "ties our delivery mechanism to a single provider, reducing portability" — a reader who disagrees can argue against this specific reason. "We did not choose this" is not arguable.
- Status quo as an option — "Option B — Status quo" — always consider doing nothing as an explicit option. Its rejection should cite the specific reason the current state is unacceptable.