How to Write an ADR in English

An ADR that only states the decision is half-useful — the value of an architecture decision record is mostly in the context and consequences sections, which let a future engineer understand why the decision made sense at the time, even if it looks questionable years later.

Key Vocabulary

Context — the section describing the situation, constraints, and forces at play that made this decision necessary, written so a future reader understands what problem was actually being solved, not just what was chosen. “The context section should explain that we were choosing under a tight deadline with a small team unfamiliar with Kubernetes — that constraint matters as much as the decision itself when someone reads this in two years and wonders why we didn’t pick the ‘obviously better’ option.”

Decision — the specific, stated choice the ADR documents, written unambiguously and without hedging, since the whole point of the document is to record what was actually decided, not to present options. “The decision section shouldn’t read like a comparison of options — state clearly, ‘we will use PostgreSQL as the primary datastore,’ not ‘we’re leaning toward PostgreSQL but still considering alternatives.’ An ADR records a decision, not an ongoing deliberation.”

Consequences — the section documenting both the positive and negative results the team accepts by making this decision, including tradeoffs knowingly given up, which is what keeps an ADR honest rather than self-congratulatory. “The consequences section needs to include the downsides we’re accepting, not just the benefits — we’re gaining operational simplicity, but we’re also accepting a de facto single point of failure until we invest in replication, and that tradeoff should be written down explicitly.”

Status — a short field indicating whether the ADR is proposed, accepted, deprecated, or superseded by a later decision, which lets readers quickly tell whether a decision is still in effect without reading the full document. “Update the status field to ‘superseded by ADR-042’ rather than deleting this old ADR — the history of why we changed direction is valuable, and marking status like this keeps that history intact instead of erasing it.”

Common Phrases

• “Does the context section explain the actual constraints, or just restate the decision?”
• “Is the decision stated unambiguously, or does it still read like an open comparison?”
• “Have we documented the real consequences, including the tradeoffs we’re accepting?”
• “What’s the current status of this ADR — is it still in effect?”
• “Should this ADR be marked as superseded now that we’ve made a newer decision?”

Example Sentences

Writing the context section: “Context: our current monolith’s deploy time has grown to over 40 minutes, and the team has grown from 3 to 12 engineers working in the same codebase, causing frequent merge conflicts and deploy contention. We evaluated whether to invest in monolith tooling or begin splitting into services.”

Stating the decision clearly: “Decision: we will extract the billing module into a separate service, communicating with the monolith via a well-defined internal API, as the first step in a gradual decomposition rather than a full rewrite.”

Writing an honest consequences section: “Consequences: this reduces deploy contention for the billing team immediately, but introduces network latency and a new failure mode — a billing service outage now can degrade the monolith’s checkout flow in a way it previously couldn’t, and we’re accepting that operational complexity.”

Professional Tips

• Write the context section for a reader with none of the meeting-room background — include the constraints and forces at play, not just a summary of the problem.
• State the decision as a clear, committed sentence, not a comparison of options — an ADR records what was decided, and belongs after the debate, not during it.
• Be honest in the consequences section about real tradeoffs and downsides accepted, not just benefits — a consequences section that only lists upsides isn’t trustworthy.
• Keep the status field current, updating it to superseded rather than deleting old ADRs — the record of how decisions evolved is often as valuable as any single decision.

Practice Exercise

1. Write a context paragraph for a hypothetical decision to migrate from REST to GraphQL.
2. Draft a decision statement in one unambiguous sentence.
3. Write a consequences section that includes at least one honest downside.