Back to docs
Recipe

ADR Template

A lightweight Architecture Decision Record format for capturing technical choices with context, consequences, and clear status.

Why ADRs

ADRs document the why behind architecture decisions. They live alongside code, are immutable once accepted, and form a searchable decision log that outlasts Slack threads.

Template

# ADR-000: Title

Status: proposed | accepted | deprecated | superseded

## Context
What problem are we solving? What constraints exist?

## Decision
What did we decide and why?

## Consequences
What becomes easier? What becomes harder?

Conventions

  • File name: docs/adr/ADR-###-slug.md
  • One decision per ADR — no omnibus documents
  • Status transitions are append-only; superseded ADRs link forward
  • Number sequentially; never renumber

Example

# ADR-001: Use Upstash KV for session store

Status: accepted

## Context
We need sub-10ms session reads across Vercel edge regions.
Redis clusters add ops overhead we cannot absorb pre-launch.

## Decision
Use Upstash KV with HTTP client. Accept eventual consistency
for non-critical writes. Fall back to JWT self-encoded claims
if KV is unreachable.

## Consequences
+ Zero cold starts, no connection pooling
+ Free tier covers first 10k daily reads
- No transactions; multi-key atomicity requires application logic

Tip: Run npx adr new "Use Postgres for audit log" to scaffold from this template automatically.