How to Write an Architecture Decision Record (ADR)
Learn the ADR structure: context, decision, consequences. Includes a full example template, common mistakes to avoid, and phrases for writing clear ADRs in English.
Architecture decisions are some of the most consequential choices made in a software project. Yet they are often documented poorly — or not at all. Architecture Decision Records (ADRs) are a lightweight, structured way to record why a significant architectural choice was made, what alternatives were considered, and what trade-offs were accepted. This guide explains how to write effective ADRs in clear technical English.
What Is an ADR?
An Architecture Decision Record is a short document that captures a significant architectural decision along with its context and consequences. ADRs were popularised by Michael Nygard and are widely adopted in engineering teams as part of a “decisions-as-code” or “decisions-in-repo” practice.
ADRs answer three questions:
- What was the situation when this decision was made?
- What did we decide?
- What are the expected consequences?
Standard ADR Structure
The most widely used ADR format includes the following sections:
Title
A short, descriptive title using a decision-focused format:
“ADR-007: Use PostgreSQL as the primary database” “ADR-014: Adopt event sourcing for the order domain”
Number your ADRs sequentially. Once written, the number and title should never change — even if the decision is later superseded.
Status
One of: Proposed, Accepted, Deprecated, or Superseded by ADR-XXX.
“Status: Accepted (2026-03-15)“
Context
Describe the situation that made this decision necessary. What constraints existed? What problem were you solving? Who was affected?
“Our monolithic application has reached a point where multiple teams are deploying to the same codebase. Deployment conflicts and long review queues are slowing delivery. We need to decide whether to decompose the application into separate deployable units.”
This section should be factual and specific, not opinionated. Save your opinion for the Decision section.
Decision
State clearly what was decided. Use active voice and direct language.
“We will adopt a service-per-domain architecture, starting with the Order and User domains. Each domain will have its own repository, database, and deployment pipeline.”
Consequences
List the expected results — both positive and negative. Good ADRs do not hide trade-offs.
“Positive consequences: - Teams can deploy independently, removing cross-team deployment dependencies. - Domain boundaries will be explicit, reducing accidental coupling.
Negative consequences: - Cross-domain queries will require API calls or event-based data synchronisation, adding complexity. - We will need to invest in service discovery, distributed tracing, and inter-service authentication.”
Full ADR Template
# ADR-[number]: [Short title of the decision]
**Date:** YYYY-MM-DD
**Status:** Proposed | Accepted | Deprecated | Superseded by ADR-XXX
**Deciders:** [List of people involved in the decision]
## Context
[Describe the situation, constraints, and the problem that prompted this decision.]
## Decision
[State clearly what was decided and why.]
## Consequences
### Positive
- [Expected benefit]
- [Expected benefit]
### Negative
- [Known trade-off]
- [Known trade-off]
## Alternatives Considered
[Briefly describe alternatives and why they were not chosen.]Common Mistakes to Avoid
Writing the Decision as a Problem Statement
Wrong:
“We need to decide how to handle authentication.”
Right:
“We will use JSON Web Tokens (JWTs) for stateless authentication across all services.”
The decision section should state what was decided, not restate the problem.
Hiding Trade-offs
Omitting the negative consequences makes an ADR useless. Future engineers need to understand what trade-offs were knowingly accepted.
“Negative: JWTs cannot be invalidated before they expire without a blocklist, which adds operational complexity for logout and account suspension scenarios.”
Writing ADRs After the Fact Without Acknowledging It
If you are writing an ADR for a decision already implemented, note that:
“Note: This decision was made and implemented in March 2025. This ADR was written retrospectively to document the reasoning.”
Using Vague Language
Avoid phrases like “we should consider” or “it might be good to.” ADRs document decisions, not possibilities.
Practical Phrases for Writing ADRs
- “At the time of this decision, the primary constraint was…”
- “Three alternatives were considered: X, Y, and Z. We chose X because…”
- “This decision introduces a trade-off between simplicity and scalability.”
- “Future teams should be aware that this decision assumes…”
- “If the following assumptions change, this ADR should be revisited: …”
- “This decision supersedes ADR-003, which recommended…”
Where to Store ADRs
The most common convention is to store ADRs in a docs/decisions/ directory within the repository, named NNNN-title-with-hyphens.md. This keeps decisions versioned alongside the code they describe.
Tools like adr-tools automate the creation and linking of ADR files.
ADRs are a form of institutional memory. Without them, teams repeatedly revisit the same decisions, and engineers joining a project cannot understand why things are the way they are. A well-written ADR takes 30 minutes to produce and saves hours of confused archaeology in the future. Make writing them a habit.
Navigating Nuance: Refining Your ADR Language for Clarity
Writing an Architecture Decision Record (ADR) is about more than just stating what you decided; it’s about communicating why – the reasoning behind your choice. For non-native English speakers, this can be particularly challenging due to subtle differences in phrasing and emphasis that impact understanding and buy-in. Let’s focus on elevating your language to ensure your ADRs are not just technically correct but also clearly understood by your entire team.
One frequent area of confusion arises with expressing potential downsides or risks. Instead of a blunt statement like “This introduces risk,” which can sound accusatory, aim for phrases that acknowledge uncertainty constructively. Consider using “We’re acknowledging the possibility of [specific issue] and will proactively monitor [metric] to mitigate this.” Or, when discussing trade-offs, avoid simply saying “Option A is better.” Instead, frame it as: “While Option B offers [benefit], Option A provides a stronger foundation for [critical requirement] given our current constraints. We’ll continue to assess the long-term implications of this decision.” A common Slack message you might receive during code review regarding an ADR could be: “Hey team, just reviewing this ADR – appreciate the thoroughness! Could we perhaps elaborate slightly on how we’re addressing potential scalability issues with this approach? It would be helpful to see a concrete plan for monitoring performance as our user base grows.” Notice the polite and inquisitive tone; focusing on understanding rather than directly criticizing.
Furthermore, precision in vocabulary is key. Avoid jargon that isn’t universally understood within your team. If you must use technical terms, briefly define them within the context of the ADR. Similarly, when documenting consequences – both positive and negative – be specific. Instead of “This will improve performance,” state: “We anticipate a 15% reduction in latency for [specific operation] based on initial testing.” A good PR description for an ADR might read: “This ADR outlines our decision to adopt the microservices architecture, driven by the need for independent scaling and reduced deployment risk. The documented consequences include increased operational complexity requiring dedicated monitoring tools but also a projected 20% improvement in application responsiveness.”
Finally, remember that ADRs are living documents. Encourage ongoing discussion and iteration. Don’t be afraid to revisit your decisions as new information emerges. A follow-up message after an ADR has been approved could be: “Great work on finalizing this ADR! Let’s schedule a brief sync next week to discuss the monitoring strategy we outlined – any initial thoughts or concerns?” Focusing on collaborative language and demonstrating openness to feedback will significantly enhance the effectiveness of your ADRs and foster stronger team communication.