ADR Template

Title: ADR-<next number>: <decision in one imperative line> Status: Proposed | Accepted | Superseded by ADR-N Date: <today>

Context

2–5 sentences: the forces in play. What problem exists, what constraints bind (deadlines, team skills, existing systems, cost), and why NOW.

Decision

One paragraph, present tense, active voice: "We will …". State the choice concretely enough that someone could implement from it.

Alternatives considered

For each serious alternative (2–3): one line on what it was, one line on why it lost. Honest reasons — "we know Postgres" beats invented benchmarks.

Consequences

The bill we're agreeing to pay: what gets harder, what we're locked into, what we'd revisit if X changes. Include at least one genuine downside — an ADR with no downsides wasn't thought through.