Purpose
An ADR records a significant decision and its reasons — briefly and forever, so nobody asks "why was this done?" six months later. Kept next to the code (docs/adr/), numbered, never deleted (marked superseded). Only for significant/irreversible forks, not every trifle.
Template
# ADR-<NNN>: <decision name>
- Date · Status: proposed|accepted|deprecated|superseded by ADR-<M>
## Context — problem, constraints, forces.
## Options — A/B/C with pros/cons.
## Decision — chose X because Y.
## Consequences — pros, cons/cost, risks & mitigations.
Example 1 — storage
# ADR-003: Store the personal core in IndexedDB (not localStorage)
- Date 2026-05-20 · Status accepted
## Context — the core grows; need reliable local storage surviving reload, supporting export. localStorage is ~5MB and synchronous.
## Options — A localStorage (simple, ~5MB, sync); B IndexedDB (bigger, async, structured; harder API); C cloud-only (no offline, network dependency day one).
## Decision — B, because volume and async matter for growth and UI smoothness, and offline-first is a product requirement.
## Consequences — pros: headroom, non-blocking, export-friendly. cons: harder API (wrap it); browser differences (cover with tests).
Example 2 — supersede
# ADR-007: Move internal API from REST to tRPC
- Date 2026-06-01 · Status accepted (supersedes ADR-002 "REST + manual types")
## Context — TS front+back, contract kept drifting → bugs.
## Options — A REST + OpenAPI codegen (reliable, extra step); B tRPC (end-to-end types, no codegen; TS monorepo lock).
## Decision — B: TS monorepo exists, end-to-end type safety removes a class of drift bugs.
## Consequences — pros: contract won't drift, less manual work. cons: TS lock (keep REST for the public API). ADR-002 marked superseded.
Quality checklist
- One decision per record.
- Rejected alternatives visible (≥ A/B).
- Reason explicit, grounded in context.
- Consequences incl. cons & debt.
- Status & date; stale ones superseded, not deleted.
Common mistakes
Decision without alternatives; hiding cons; an ADR per trifle; deleting stale ADRs; "decided on a call", recorded nowhere.