Skip to content

Architecture Decision Records

Significant decisions should survive memory.

An ADR captures the context, the decision made, the alternatives considered, and the trade-offs accepted. It is written at the time of the decision, when context is fresh.

When to Write an ADR

  • Choosing between two or more meaningful technical approaches
  • Adopting a new tool, framework, or platform
  • Establishing a pattern that others will follow
  • Making a decision that would be expensive to reverse

Template

# ADR-XXX: <Title>

**Date:** YYYY-MM-DD
**Status:** Proposed | Accepted | Superseded | Deprecated

---

## Context

What is the problem or situation requiring a decision?
What constraints exist?

---

## Decision

What was decided?

---

## Alternatives Considered

What other options were evaluated and why were they not chosen?

---

## Consequences

What trade-offs were accepted?
What becomes easier? What becomes harder?
What will need to be revisited?

Where to Store ADRs

Store ADRs in the repository they relate to, under docs/decisions/ or similar. This keeps them close to the code and versioned alongside it.

← Operational Excellence ← Technical Excellence ← Engineering Excellence