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.

Navigating Nuances: Refining Your Architectural Voice

Let’s be honest – even with a solid understanding of what to write in an ADR, articulating those thoughts clearly in English can feel daunting. It’s not just about stating facts; it’s about conveying intent and inviting collaboration. A poorly worded ADR can lead to misinterpretations, rework, and ultimately, wasted time. Let’s focus on refining your phrasing to ensure your architectural decisions are readily understood and embraced by the team.

One of the trickiest areas is framing the decision itself. Instead of simply stating “We chose X,” consider phrases like “To mitigate performance bottlenecks in the API layer, we decided to migrate data access to a microservice architecture.” Notice the inclusion of context – “performance bottlenecks” - and the explanation of why that decision was made. This shifts the focus from just the outcome (“X”) to the underlying reasoning. Another useful addition is anticipating potential pushback. A phrase like “This approach introduces operational complexity with regard to inter-service communication, which we will address through…” immediately signals awareness and invites discussion about mitigation strategies.

Beyond formal documents, ADRs often spark conversations. Think about how you’d communicate this decision in a Slack channel. Instead of just saying “Switching to microservices,” try something like: “Hey team, thinking through the recent API performance issues – exploring a microservice architecture as a potential solution. Initial thoughts are around improved scalability and decoupling. Let’s discuss pros/cons!” The key here is to frame it as an exploration rather than a decree. Similarly, when writing a PR description, instead of “Refactoring for microservices,” aim for “Refactoring the API layer to adopt a microservice architecture to address performance bottlenecks and improve scalability – further discussion welcome.”

Finally, remember that ADRs are inherently collaborative. Don’t be afraid to use tentative language – phrases like “We’re considering…” or “A potential alternative is…” signal openness to feedback. A crucial element is actively soliciting input: “What are your thoughts on the trade-offs between this approach and [alternative]? Are there any immediate concerns you foresee?”. The goal isn’t to dictate a solution, but to arrive at one together. Mastering these nuances will significantly improve the effectiveness of your ADRs and foster a more productive engineering environment.