ADR-NNNN — {{Decision title in imperative form}}

Status

Proposed — YYYY-MM-DD

Lifecycle: Proposed → Accepted → (Deprecated | Superseded by ADR-NNNN). When superseded, update both this ADR’s superseded_by and the new ADR’s supersedes.

---

Context

What forces are at play? What pre-existing constraints, requirements, or facts make this decision necessary now? Two short paragraphs at most.

State the problem in solution-neutral language. Don’t telegraph the answer.

Useful prompts:

• What changed that triggered this decision?
• What are we currently doing (or not doing) that hurts?
• What can’t we postpone, and why?

Considered alternatives

Option	Summary	Pros	Cons	Outcome
A	…	…	…	rejected — one-sentence reason
B	…	…	…	rejected — one-sentence reason
C (chosen)	…	…	…	selected

---

Decision

One paragraph, in active voice. “We will ”, not “It is suggested that…”.

We will use {{chosen option}} for {{specific scope}}, because {{the single most decisive reason}}.

Concretely:

• … (implementation-shaping detail #1)
• … (implementation-shaping detail #2)
• … (scope boundary — what this decision does NOT cover)

---

Consequences

Positive

• …
• …

Negative / trade-offs

• …
• … (if any of these are severe enough to deserve a follow-up ADR, link it here)

Neutral / follow-ups

• Spike: …
• Update onboarding doc to mention …
• Add metric / alert for …

---

References

• Link to RFC, blog post, library docs, prior incident, related ADR, etc.
• (External references that informed the decision — keep authoritative ones, prune the rest.)