The Standard Template
For ADRs to be useful across a team or organization, they need a consistent structure. If every engineer writes decisions in their own format, the documentation becomes harder to scan and compare. Most organizations use a variation of the template popularized by Michael Nygard, which centers on three critical pillars: Context, Decision, and Consequences.
Here is a complete, realistic ADR example:
# ADR-0007: Use Amazon RDS PostgreSQL for the Order Service Database
## Status
Accepted
## Date
2024-03-15
## Context
The Order Service currently stores data in a self-managed MongoDB instance
running on EC2. This instance has experienced two unplanned outages in the
last quarter due to disk space exhaustion and a failed replica set election.
The team spends approximately 8 hours per week on database maintenance tasks
(backups, patching, monitoring).
Our constraints:
- The team has strong SQL skills but limited MongoDB operational experience.
- We need ACID transactions for order processing (partial writes are unacceptable).
- Our SLA requires 99.95% availability for the order pipeline.
- Budget allows up to $2,000/month for the database tier.
## Decision
We will migrate the Order Service database to Amazon RDS PostgreSQL (db.r6g.large,
Multi-AZ deployment) with automated backups and read replicas.
## Consequences
**Positive:**
- Automated backups, patching, and failover reduce operational burden from ~8 hrs/week
to ~1 hr/week.
- Multi-AZ deployment meets our 99.95% availability SLA.
- PostgreSQL's ACID compliance eliminates the partial-write risk.
- Team's existing SQL expertise transfers directly.
**Negative:**
- Vendor lock-in to AWS for this data tier. Migration to another cloud would require
a database export/import effort.
- RDS PostgreSQL costs ~$1,400/month (Multi-AZ), which is $600/month more than the
current self-managed EC2 instance.
- We lose MongoDB's flexible schema — schema migrations will require more planning.
- The migration itself carries risk: estimated 2-week effort with a planned maintenance
window for the cutover.
## Alternatives Considered
- **Keep MongoDB, move to Atlas (managed):** Reduces operational burden but doesn't
address ACID requirements or team skill gap.
- **Use Amazon Aurora PostgreSQL:** Better performance at scale, but costs ~$2,800/month,
exceeding our budget.
- **Use CockroachDB:** Distributed SQL with excellent availability, but the team has
zero experience and the learning curve is steep.
Let's break down each section:
Status — The current state of this decision (Proposed, Accepted, Superseded, Deprecated, or Rejected). This is the first thing anyone reads. It tells you immediately whether this record reflects current reality or historical context.
Date — When the decision was made. Critical for understanding what constraints and technology landscape existed at the time. A decision made in 2018 about container orchestration was made in a very different world than the same decision made in 2024.
Context (The Situation) — This section answers: "What problem are we facing, and what constraints limit our options?" A good Context section includes concrete data: outage counts, team skills, budget limits, SLA requirements. Vague context like "we need a better database" is useless. Specific context like "two outages in Q1, 8 hours/week maintenance burden, $2,000/month budget cap" gives future readers the information they need to evaluate whether the decision still makes sense.
Decision (The Action) — A clear, unambiguous statement of what will be done. Specific enough that someone could act on it. "Use PostgreSQL" is too vague. "Use Amazon RDS PostgreSQL (db.r6g.large, Multi-AZ)" is actionable.
Consequences (The Trade-offs) — This is the most valuable section of the entire document. Every architectural choice has downsides. An ADR that lists only positive consequences is either dishonest or incomplete. You must list the good, the bad, and the ugly. Future engineers reading this ADR need to know what price was knowingly paid. If they're experiencing a pain point that was listed as a known consequence, they know it was a deliberate trade-off. If the pain point isn't listed, it was a blind spot — and that's equally important information.
Alternatives Considered — What other options were evaluated and why they were rejected. This prevents future teams from re-proposing the same alternatives without new information. It also demonstrates that the decision was deliberate, not arbitrary.
Key Point: The "Alternatives Considered" section is what separates a useful ADR from a rubber-stamp. If you can't articulate why you didn't choose the alternatives, you haven't actually made a decision — you've made a guess. Senior engineers evaluate this section first when reviewing ADRs, because it reveals the depth of analysis behind the choice. A strong alternatives section shows that the author considered the solution space seriously. A weak one (or a missing one) signals that the decision may have been made before the analysis was done.