Architecture Decision Records in English: Structure, Language, and Templates
Learn how to write Architecture Decision Records in clear English: ADR structure, vocabulary for each section, hedging language for trade-offs, and ready-to-use templates.
An Architecture Decision Record (ADR) is a short document that captures a significant architectural decision: what was decided, why, and what the consequences are. ADRs are widely used in engineering teams, but writing them clearly in English — especially when weighing trade-offs or acknowledging uncertainty — requires specific vocabulary and phrasing. This guide gives you the structure, the language, and the phrases you need.
ADR Structure
A standard ADR contains four core sections. Understanding the purpose of each section helps you write more focused, useful content.
1. Context
The context section describes the situation that necessitates a decision. It is factual and neutral — you are not arguing for a solution yet, just explaining what is true and what forces are at play.
Useful vocabulary for context:
- Force — a competing concern or constraint shaping the decision. “The main forces at play are scalability, operational complexity, and cost.”
- Constraint — a limitation that is fixed and cannot be changed. “We are constrained to AWS services due to our existing enterprise agreement.”
- Driver — a business or technical need motivating change. “The primary driver for this decision is the need to support 10× the current peak traffic within six months.”
- Assumption — something believed to be true but not yet verified. “We assume the team will grow to eight engineers within the next quarter.”
2. Decision
The decision section states what was chosen, written as an active, unambiguous statement.
Recommended phrasing:
- “We will use X.”
- “We have decided to adopt X.”
- “The team has agreed to implement X.”
Avoid vague language like “we might consider X” or “X could potentially be used.” The decision section must be definitive.
3. Status
Status reflects the lifecycle of the ADR:
- Proposed — under discussion, not yet agreed
- Accepted — agreed and in effect
- Deprecated — superseded by a newer decision
- Superseded by ADR-042 — replaced by a specific record
4. Consequences
Consequences describe what becomes easier, harder, or different as a result of the decision. This is where you acknowledge trade-offs honestly.
Hedging Language for Trade-offs
Good ADRs acknowledge uncertainty and describe trade-offs without either over-promising or being evasive. Hedging language is the key tool here.
Acknowledging positives and negatives:
- “This approach simplifies X but introduces additional complexity in Y.”
- “Whilst this increases operational overhead, it significantly reduces latency.”
- “The main drawback is X; however, this is an acceptable trade-off given Y.”
Expressing uncertainty:
- “It is anticipated that…” (moderate confidence)
- “We expect that, under normal load, …” (conditional expectation)
- “This assumption will need to be validated once…” (deferred validation)
- “There is a risk that X may occur if Y.” (risk framing)
Describing future consequences:
- “Teams consuming this service will need to update their client libraries.”
- “This decision closes off the option to use X in the future.”
- “Reversing this decision at a later date would require a full re-migration.”
Vocabulary for Each ADR Section
| Section | Key terms |
|---|---|
| Context | force, driver, constraint, assumption, trade-off, background |
| Decision | adopt, implement, migrate to, replace with, deprecate, retire |
| Status | proposed, accepted, deprecated, superseded, under review |
| Consequences | enables, prevents, requires, increases, reduces, introduces risk |
Example ADR Sentences in Context
-
“The primary driver for this decision is the need to eliminate the single point of failure introduced by our current monolithic session store.” (Context)
-
“We will adopt a distributed Redis Cluster managed by our infrastructure team, replacing the current single-instance Redis deployment.” (Decision)
-
“Status: Accepted — agreed by the backend chapter lead and platform team on 2026-04-01.” (Status)
-
“This approach simplifies horizontal scaling but introduces an operational dependency on the platform team for cluster management; application teams will no longer be able to self-serve Redis changes.” (Consequences — trade-off)
-
“Reversing this decision in the future would require migrating session data back to a single-instance model, which is feasible but would incur significant engineering effort during a traffic-sensitive migration window.” (Consequences — reversibility)
Template to Use Immediately
# ADR-[NUMBER]: [Short decision title]
**Date:** YYYY-MM-DD
**Status:** Proposed | Accepted | Deprecated | Superseded by ADR-[N]
## Context
[Describe the situation. What is happening? What forces, constraints, and drivers are at play?]
## Decision
We will [state the decision clearly and actively].
## Consequences
**Positive:** [What becomes easier or better?]
**Negative:** [What becomes harder or introduces risk?]
**Neutral:** [What changes but is neither clearly positive nor negative?]Common Writing Mistakes in ADRs
Too vague: “We decided to improve performance.” → Better: “We will replace synchronous HTTP calls between Service A and Service B with asynchronous messaging via RabbitMQ.”
Missing consequences: Simply stating a decision without explaining its impact reduces the long-term value of the ADR enormously.
Passive throughout: “It was decided that Redis would be used.” → Better: “The backend chapter agreed to use Redis.”
Write ADRs in present and future tense for decisions, past tense only for historical context. Keep each record short — a useful ADR is typically one page, not five.