Skip to content

ADR-NNN — [Decision Title]

Status · Accepted | Superseded by ADR-NNN Date · [date] TA anchor · components/[…] or contracts/[…] or stack (OC_TA.md) Related RFC · RFC-NNN (if this ADR closes an RFC) Related PRDs · [if this ADR was triggered by a PRD]

Context

[1–2 paragraphs. What was the situation that required this decision? What constraints existed? Brief — the full deliberation lives in the related RFC if there was one.]

Decision

[The decision, stated clearly. One paragraph. No hedging.]

Rationale

[Why this decision. The key factors that tipped the choice. Brief.]

Alternatives considered

[Alternatives that were rejected, with one-line reasons. If a deep deliberation happened in a related RFC, link to it and keep this section short.]

  • [Alternative] — [brief reason for rejection]
  • [Alternative] — [brief reason for rejection]

Consequences

[What this decision makes easier and what it makes harder. Both sides.]

Positive: - [benefit]

Negative: - [trade-off]

Implementation notes

[Where in the codebase this decision manifests. Pointer-form.]

Notes on writing ADRs in this format

ADRs are append-only. Once accepted, an ADR is never edited. If circumstances change, write a new ADR that supersedes the old one. The old one stays in the record marked Superseded.

ADRs are short. One page is the target. ADRs commit; they don't deliberate. Deliberation lives in the related RFC. If you find yourself writing more than a page, either you're writing an RFC by accident or the decision needs splitting.

ADRs come from RFCs or from direct decisions. An RFC closes into one or more ADRs. A small decision that doesn't need deliberation can be an ADR directly — no preceding RFC required. The bar is whether the deliberation actually happened (RFC) or didn't need to (direct ADR).

Voice. ADRs are the most functional document in the system. Less voice than a PRD or RFC. But still: no apology, no padding, no "this might be controversial" preamble. State the decision and move on.