Skip to content

ADR Template

Architectural Decision Records (ADRs) are short documents that capture important technical decisions along with their context and consequences. They are the institutional memory of why things are the way they are—essential for onboarding, for avoiding repeated debates, and for understanding the trade-offs your system embodies.

What problem this solves

Technical decisions get made and forgotten. Six months later, someone asks "why do we use X instead of Y?" and no one remembers. The decision gets revisited, debated again, and sometimes reversed without understanding the original reasoning.

ADRs solve this by creating a lightweight, searchable record of significant decisions. They're not documentation of how the system works—they're documentation of why it works that way.

When to use this

Write an ADR when:

  • The decision is significant and hard to reverse.
  • Multiple options were considered.
  • The decision has consequences the team should understand.
  • Future engineers might reasonably question the choice.

Don't write an ADR for:

  • Trivial decisions (variable naming, minor refactors).
  • Decisions that are obviously correct and have no meaningful alternatives.
  • Temporary spikes or experiments.

A good rule: if you'd want to explain this decision during onboarding, it probably deserves an ADR.

Roles and ownership

Role Responsibility
Decision maker Writes the ADR. This is usually the person proposing the change—a tech lead, staff engineer, or senior engineer.
Reviewers Provide feedback on the proposal. Challenge assumptions. Confirm the decision is sound.
Approver Makes the final call (may be the same as the decision maker for team-level decisions, or a more senior person for cross-cutting decisions).

How to use ADRs

Step 1: Propose the decision

Create a new ADR with status "Proposed." Fill in the context, the decision, the options considered, and the consequences.

Share it with relevant stakeholders asynchronously. Give people time to read and comment (24–48 hours minimum for significant decisions).

Step 2: Discuss and refine

Address feedback. Update the ADR based on discussion. If there's significant disagreement, schedule a synchronous discussion—but keep it focused on resolving specific concerns, not rehashing the entire proposal.

Step 3: Accept or reject

Once consensus is reached (or the approver makes a call), update the status to "Accepted" or "Rejected." Record the date.

Step 4: Implement

Proceed with implementation. Reference the ADR in relevant PRs, design docs, or discussions.

Step 5: Supersede when needed

If a future decision changes the approach, create a new ADR and mark the old one as "Superseded by ADR-XXX." Don't delete old ADRs—they're part of the history.

Signals that ADRs are working

  • New team members can understand why the system is built the way it is.
  • Decisions don't get re-debated without new information.
  • ADRs are referenced in discussions and PRs.
  • The ADR collection is a useful resource, not a graveyard.

Failure modes and mitigations

Failure mode What it looks like Mitigation
ADRs never written Decisions made in meetings, nothing documented Make ADRs a required artifact for significant changes
ADRs too detailed 10-page documents that no one reads Keep ADRs short; 1–2 pages max
ADRs not discoverable They exist but no one can find them Maintain an index; use consistent naming and storage
Status never updated "Proposed" ADRs languish without resolution Set time limits; review proposed ADRs in team meetings
Decisions made, then ADRs written ADR is a formality after the fact Write ADRs before implementation; use them for discussion

The template

ADR document

# ADR-[NUMBER]: [Title]

**Status:** [Proposed | Accepted | Rejected | Deprecated | Superseded by ADR-XXX]
**Date:** [YYYY-MM-DD]
**Decision maker:** [Name]
**Approver:** [Name, if different]

---

## Context

[What is the situation? What problem are we trying to solve? What constraints exist?]

[Include relevant technical context, business requirements, and any forcing functions.]

---

## Decision

[State the decision clearly and concisely.]

We will [decision].

---

## Options considered

### Option 1: [Name]

[Brief description]

**Pros:**

- [Pro]
- [Pro]

**Cons:**

- [Con]
- [Con]

### Option 2: [Name]

[Brief description]

**Pros:**

- [Pro]
- [Pro]

**Cons:**

- [Con]
- [Con]

### Option 3: [Name] (if applicable)

[...]

---

## Consequences

### Positive

- [Consequence]
- [Consequence]

### Negative

- [Consequence]
- [Consequence]

### Risks

- [Risk and mitigation]

---

## Related decisions

- [Link to related ADRs]
- [Link to relevant design docs]

---

## Notes

[Any additional context, discussion summary, or implementation notes.]

ADR index template

Keep an index file for discoverability:

# Architecture Decision Records

| ADR                                     | Title                                             | Status   | Date       |
| --------------------------------------- | ------------------------------------------------- | -------- | ---------- |
| [ADR-001](adr-001-use-postgres.md)      | Use PostgreSQL as primary database                | Accepted | 2025-01-15 |
| [ADR-002](adr-002-event-driven-arch.md) | Adopt event-driven architecture for notifications | Accepted | 2025-02-20 |
| [ADR-003](adr-003-monorepo.md)          | Move to monorepo structure                        | Proposed | 2025-03-01 |

Tips for good ADRs

  • Start with context, not solution. Help readers understand the problem before the answer.
  • Be honest about trade-offs. Every decision has downsides. Acknowledge them.
  • Keep it short. A good ADR fits on 1–2 pages. If you need more, you might be mixing documentation types.
  • Use plain language. ADRs are for humans, not machines.
  • Date everything. Context changes. Knowing when a decision was made matters.