Writing Architecture Decision Records: Advanced Language and Structure
Go beyond the ADR template: master the advanced English of context, trade-offs, consequences, and status language so your architecture decision records read with authority.
Most engineers know the ADR template — Context, Decision, Consequences. But knowing the template isn’t the same as writing an ADR that reads with authority. The difference is in the language: how you frame the problem, how you weigh options without sounding wishy-washy, and how you state consequences honestly. This guide is about that advanced layer, for engineers who already write ADRs but want them to land like a senior architect’s.
A quick refresher on the structure
An Architecture Decision Record (ADR) is a short document that captures one significant decision: what you decided, why, and what it costs. The standard sections:
- Title — short, decision-shaped
- Status — Proposed / Accepted / Deprecated / Superseded
- Context — the forces at play
- Decision — what you chose
- Consequences — what follows, good and bad
The rest of this guide is about writing each section in language that’s precise and confident.
The title: decision-shaped, not topic-shaped
A weak title names a topic. A strong title names a decision.
- Weak: “Database choice”
- Strong: “Use PostgreSQL as the primary datastore”
- Stronger still (when there’s tension): “Adopt PostgreSQL over DynamoDB for transactional workloads”
Use the imperative verb form: Use, Adopt, Migrate to, Standardise on, Deprecate. This is the same grammar as good Git commit messages — a command describing what the decision does.
Context: the language of “forces”
The Context section explains why this decision was even necessary. The most professional ADRs frame context as a set of forces — competing pressures that constrain the choice.
Useful framing language:
- “We’re constrained by…”
- “There’s tension between time-to-market and long-term maintainability.”
- “The following forces are at play: …”
- “This decision is driven by a need to reduce operational load.”
- “Our current approach no longer scales because…”
“We currently run three separate caching layers, each configured differently. This fragmentation increases operational burden and onboarding time. We’re constrained by a small platform team, which creates pressure to consolidate.”
Write Context in present tense — it describes the situation as it is now. Avoid loading it with the decision; the reader should feel the problem before they see the answer.
Decision: state it, don’t hedge it
The Decision section is the one place in technical writing where hedging is wrong. Once you’ve decided, commit:
- “We will adopt PostgreSQL.”
- “We will standardise on a single caching layer using Redis.”
Before (weak): “We think it might be better to maybe use PostgreSQL, although there could be reasons to reconsider.” After (strong): “We will adopt PostgreSQL as the primary datastore for transactional services.”
Use “we will” — present/future commitment, active voice, “we” as subject. Save the nuance for Consequences.
Considered options: weighing without waffling
Strong ADRs include the alternatives you rejected and why. This is where the language of trade-offs lives:
- “We considered three options: …”
- “Option A offers X at the cost of Y.”
- “We ruled out DynamoDB because our access patterns are relational.”
- “The deciding factor was operational familiarity.”
- “On balance, PostgreSQL best satisfies the forces above.”
A clean comparison table reads well:
| Option | Pros | Cons | Verdict |
|---|---|---|---|
| PostgreSQL | Relational, mature, team knows it | Manual sharding at scale | Chosen |
| DynamoDB | Managed, scales automatically | Access patterns don’t fit | Rejected |
| Keep status quo | No migration cost | Fragmentation persists | Rejected |
Vocabulary for verdicts: chosen, rejected, deferred, revisit later, out of scope.
Consequences: be honest about the downside
This is the section that separates mature ADRs from marketing. List both positive and negative consequences. An ADR with only upsides reads as naive.
Framing:
- “As a result, onboarding becomes simpler.”
- “The trade-off is that we take on manual sharding responsibility above ~1TB.”
- “This introduces a new operational dependency.”
- “We accept the risk that …”
- “This decision constrains future choices around multi-region.”
“Positive: a single, well-understood datastore reduces cognitive load. Negative: we accept manual sharding above 1TB and lose DynamoDB’s automatic scaling. Neutral: we’ll need to build connection-pool monitoring we didn’t have before.”
The phrase “we accept the risk that…” is gold. It signals that you saw the downside and chose anyway — the mark of a deliberate decision rather than an oversight.
Status language and lifecycle
ADRs are immutable once accepted — you don’t edit them, you supersede them. The status vocabulary:
- Proposed — under discussion
- Accepted — agreed and in force
- Deprecated — no longer recommended, but not replaced
- Superseded by ADR-014 — replaced by a newer decision
“Status: Superseded by ADR-021. We migrated from manual sharding to Citus; see ADR-021 for the current approach.”
Note: deprecated and superseded are not the same. Deprecated = falling out of use. Superseded = explicitly replaced by something specific. Mixing them up is a common error.
Tense and voice cheat sheet
- Context: present tense (“We currently run…”)
- Decision: future/commitment (“We will adopt…”)
- Consequences: present/future (“This introduces…”)
- Voice: mostly active with “we” as subject — it’s a record of human decisions, so own them.
Common mistakes non-native writers make
- Hedging the decision. “We might possibly use…” undermines the whole document. Decide, then commit.
- Listing only benefits. Reviewers trust ADRs more when they name the downsides.
- Editing accepted ADRs. Don’t. Write a new one and mark the old one superseded.
- Confusing “deprecated” and “superseded.” Use superseded by ADR-X when there’s a replacement.
- Vague titles. “Caching” is a topic. “Standardise on Redis for application caching” is a decision.
Key takeaways
- Title the ADR as a decision with an imperative verb, not a topic.
- Frame Context as competing forces in present tense — let the reader feel the problem.
- In the Decision, drop all hedging: “We will.”
- Show considered options with honest trade-offs and a clear deciding factor.
- Always list negative consequences and use “we accept the risk that…” — it signals a deliberate choice.
- Don’t edit accepted ADRs; supersede them, and keep deprecated and superseded distinct.