Skip to content

ADR-XXXX:

Field Value
Status Proposed / Accepted / Deprecated / Superseded by ADR-NNNN
Date YYYY-MM-DD
Decision owners @you, @reviewer
Related ADRs See previous ADRs

Copy this file to docs/adr/NNNN-short-slug.md. Keep one decision per ADR. Fill every section. Write for a reader who was not in the conversation.

Context

What problem is this solving, and why now?

  • The forces at play (performance, consistency, team size, provider, cost).
  • Any constraints or pre-existing decisions that bound the choice.
  • What happens if we do nothing.

Decision

The decision, stated clearly and unambiguously. Include the concrete shape:

We will <decision> because <primary driver>.

Add code/pseudocode, links to the implementing PR, or pointers to the docs that describe the how (## Related links outward at the bottom).

Consequences

Positive and negative consequences, then the mitigation for each.

Positive:

  • …

Negative / costs:

  • …

Mitigations.

  • …

Alternatives Considered

For each alternative: what it is, and why it was rejected (cost, fit, risk, complexity, lock-in). Be honest — a good ADR records a real trade-off.

Alternative 1. …

Alternative 2. …

Status

Proposed until a decision owner sets it; Accepted once agreed; later ADRs can mark it Deprecated / Superseded by ADR-NNNN.