How to Write an Architecture Decision Record (ADR) in English
A practical guide to writing clear, professional Architecture Decision Records in English: structure, vocabulary, example templates, and the phrases that experienced architects use.
An Architecture Decision Record (ADR) is a short document capturing an important architectural decision: what was decided, why, and what the consequences are. ADRs are read by current teammates, future engineers, and managers — often months or years later. A well-written ADR requires clear, precise English: you are documenting a decision whose reasoning must be understood without access to the original discussion.
This guide covers the ADR format, the vocabulary you need, section-by-section templates, and the language patterns that make ADRs readable and useful.
What an ADR is (and isn’t)
An ADR is not a design document. It does not explain how the system works — it explains why a specific choice was made at a specific point in time.
A good ADR answers:
- What problem were we solving?
- What options did we consider?
- What did we choose and why?
- What are the downsides we are accepting?
A bad ADR either justifies a decision after the fact without considering alternatives, or is so long that no one reads it.
The standard ADR structure
The most widely used ADR format (from Michael Nygard’s original template) has five sections:
- Title — Short, numbered, verb-first
- Status — Proposed / Accepted / Deprecated / Superseded
- Context — Background: what problem or forces led to this decision?
- Decision — What was chosen and why
- Consequences — What changes, what becomes easier, what becomes harder
Some teams add sections for Alternatives Considered and Rationale between Decision and Consequences. Both approaches work — the key is consistency within your team.
Section 1: Title
The title should be:
- Numbered (ADR-001, ADR-023, etc.) for easy reference
- Short — ideally one line
- Phrased as a decision, not a topic
Good titles:
ADR-001: Use PostgreSQL as the primary database
ADR-015: Adopt Terraform for all cloud infrastructure
ADR-023: Move from REST to gRPC for internal service communication
ADR-031: Implement circuit breakers using Resilience4j
Weak titles (avoid):
ADR-001: Database decision
ADR-015: Terraform
ADR-023: gRPC vs REST
Section 2: Status
Status is a single word or short phrase. Common values:
| Status | Meaning |
|---|---|
| Proposed | Under discussion, not yet accepted |
| Accepted | Approved and active |
| Deprecated | No longer recommended but not changed yet |
| Superseded by ADR-045 | Replaced by a later decision |
| Rejected | Considered but decided against |
“Status: Accepted — March 2026”
“Status: Superseded by ADR-047 (October 2026) — see that document for the current approach.”
Section 3: Context
The Context section describes the situation that made a decision necessary. Write it in neutral language — avoid advocating for any particular choice. Describe the forces at play: technical constraints, team capabilities, business requirements, existing architecture.
Template structure:
- What is the system or component involved?
- What problem or need prompted this decision?
- What constraints or requirements are relevant?
- What are the competing forces (speed vs. consistency, cost vs. flexibility, etc.)?
Useful phrases for Context:
Describing the situation:
“The current architecture uses a single PostgreSQL instance for all read and write traffic.”
“As of Q1 2026, the payments service handles approximately 500 write operations per second at peak, and load testing predicts this will double within six months.”
“The team has expertise in Python but limited experience with Go.”
Describing the problem:
“The primary concern is the lack of service isolation — a bug in the billing service can exhaust database connections and bring down unrelated services.”
“We need a solution that can be deployed and operated by a team of four, without requiring dedicated infrastructure expertise.”
“The current approach is not tenable at the projected growth rate.”
Acknowledging trade-offs and competing forces:
“There is tension between operational simplicity and scalability.”
“We are balancing the desire for consistency with the need for flexibility at the edges.”
“The primary constraint is time to production: the migration must be complete before the contract renewal in Q3.”
Section 4: Decision
The Decision section states the choice clearly and explains the reasoning. It should be direct and active: “We will use X” rather than “It was decided to use X.”
Template structure:
- State the decision in one sentence
- Explain the primary reasons
- Reference the alternatives considered (or link to a separate Alternatives section)
Useful phrases:
Stating the decision:
“We will adopt event sourcing for the order lifecycle domain.”
“We have decided to migrate from the monolithic Rails application to a set of independently deployable services.”
“Our approach will be to use a distributed cache (Redis) to store session data, replacing the current database-backed sessions.”
Giving reasons:
“This approach was chosen because it aligns with the existing team’s expertise and avoids the operational overhead of a separate deployment pipeline.”
“The primary driver is operational cost — maintaining two separate infrastructure stacks increases both cognitive load and financial overhead without proportional benefit.”
“The key factor in this decision was auditability — event sourcing provides a complete, immutable history of all state changes, which is a compliance requirement.”
Acknowledging alternatives:
“We considered MySQL as an alternative but ruled it out because of the team’s existing PostgreSQL tooling and the stronger JSONB support in PostgreSQL 14.”
“Kafka was evaluated for the message queue layer but was considered operationally heavy for our current team size. SQS was chosen for its managed nature and lower operational burden.”
“An alternative approach would be to maintain the monolith and introduce strangler fig patterns, but this was rejected because the tight coupling makes parallel work on the same codebase impractical.”
Section 5: Consequences
The Consequences section is what separates a good ADR from a justification document. It is honest about what becomes harder and what new problems the decision creates.
Template structure:
- Positive consequences (what improves)
- Negative consequences (what gets harder or more expensive)
- Neutral changes (what must now happen differently)
Useful phrases:
Positive consequences:
“Each service can now be deployed independently, reducing deployment coordination overhead.”
“The new approach significantly simplifies the write path and removes the distributed transaction complexity.”
“Onboarding new engineers becomes easier — the component is smaller and has a single, well-defined responsibility.”
Negative consequences (critical to include):
“This decision increases infrastructure complexity — we now need to operate a Redis cluster in addition to PostgreSQL.”
“Teams will need to learn the new framework, which will slow delivery during the initial three-month transition period.”
“Event sourcing adds cognitive overhead to the query path — developers must understand that state is derived from events, not stored directly.”
“We accept the risk of increased latency on the read path as a consequence of eventual consistency in this domain.”
Neutral / process changes:
“All new services written in this domain must implement the standard health check and metrics endpoints defined in ADR-018.”
“The decision requires updating the team onboarding documentation and adding a new section to the architecture guide.”
“A migration plan must be created and reviewed before implementation begins.”
Full example ADR
Here is a short but realistic example:
ADR-019: Use Redis for distributed session storage
Status: Accepted — March 2026
Context: The application currently stores user sessions in the PostgreSQL database. As the user base grows, session reads (which happen on every authenticated request) account for 40% of all database queries. Database connection pool exhaustion during peak traffic is causing intermittent 503 errors. The primary requirement is a high-availability session store that can handle 10,000 reads/second with sub-millisecond latency.
Decision: We will migrate session storage from PostgreSQL to Redis (AWS ElastiCache, multi-AZ). Redis is structurally well-suited for key-value access patterns (session ID → session data), supports configurable TTLs natively, and eliminates session queries from the PostgreSQL read path.
DynamoDB was evaluated as an alternative. It would also satisfy the latency and throughput requirements, but the team has existing Redis expertise and ElastiCache reduces operational overhead compared to a self-managed cluster.
Consequences:
Positive:
- Session queries are eliminated from PostgreSQL, freeing connection pool capacity for application queries.
- Sub-millisecond latency for session reads at scale.
- Native TTL support simplifies session expiry logic.
Negative:
- We now operate a second data store, increasing infrastructure complexity and AWS cost by approximately $180/month.
- Cache invalidation during session revocation (logout, password change) requires a new invalidation path that does not exist in the current architecture.
- Redis data is ephemeral — the team must ensure sessions are designed to be safely regenerated on cache miss.
Process:
- The application deployment process must now include ElastiCache in the pre-flight checks.
- Engineers must read the session management documentation before modifying session-related code.
Common language mistakes in ADRs
1. Using passive voice to avoid clarity
Passive voice in ADRs hides who made the decision and can obscure the reasoning:
❌ “It was decided that PostgreSQL would be used.”
✅ “We decided to use PostgreSQL. The primary factor was the team’s existing operational experience.”
2. Writing only the happy path
A consequences section with only positive points is not credible:
❌ “Consequences: Better scalability, improved performance, simplified architecture.”
✅ “Consequences: Improved read throughput (positive). Additional operational complexity from a second data store (negative). Migration work estimated at two sprints (neutral).”
3. Recording the decision without context
Future readers cannot evaluate the decision without knowing what constraints existed at the time:
❌ “Context: The team needed a database.”
✅ “Context: The system requires strong ACID guarantees for financial transactions. The team has five years of PostgreSQL experience. The compliance requirement mandates data residency in the EU.”
4. Vague references to alternatives
❌ “Other options were considered and rejected.”
✅ “MongoDB was evaluated and rejected because our data model has many relational joins. Cassandra was ruled out due to the team’s lack of operational experience and the complexity of its consistency model.”
Key vocabulary for ADRs
| Term | Common ADR usage |
|---|---|
| driver | The primary reason forcing a decision (“The key driver is compliance”) |
| constraint | A non-negotiable limit (“The constraint is a 6-month deadline”) |
| trade-off | A decision that gains X at the cost of Y |
| rationale | The reasoning behind a choice |
| supersede | To replace an older decision (“This ADR supersedes ADR-012”) |
| deprecated | Still in place but no longer recommended |
| tenable | Able to be maintained or defended (“Not tenable at scale”) |
| consequence | A result that follows from the decision |
| caveat | A warning or exception to the main decision |
| deferred | Postponed to a future decision (“The caching strategy is deferred to ADR-024”) |
The ADR is one of the highest-value documents an engineer can write. A good ADR requires perhaps one hour to write but saves days of repeated discussion over months and years. The investment in clear English here compounds over the lifetime of the codebase.