ADR-NNNN — Short imperative title¶
Status¶
accepted | superseded | rejected | proposed
If superseded, include superseded-by: NNNN-... in frontmatter
and a Superseded by [ADR-NNNN](NNNN-...md) line here.
Context¶
What was the forcing function? What did we know at the time? What did we NOT know? Include links to research, to commits, to upstream sources. One to three paragraphs.
State the decision space: what options were on the table? Why those and not others?
Decision¶
One imperative sentence. The thing we decided to do. No hedging.
Then optionally a short paragraph restating the decision in plainer language so that a reader who does not have the context still understands the scope.
Consequences¶
What becomes easier after this decision? What becomes harder? What do we now have to maintain? What trade-offs did we accept?
Separate the consequences we wanted from the consequences we accepted as cost. Both are valuable to future readers.
Evidence¶
Bulleted list of the concrete evidence that backed the decision at the time. Commits, research docs, raw artifacts, upstream source quotes, empirical measurements. One line per item; each line should link to the source if possible.
path/to/evidence-1.md— one-line summarycommit abc1234— one-line summaryhttps://...— one-line summary
References¶
Related ADRs, external specs, upstream tickets. Anything that would help a reader who wants to go deeper than this ADR but isn't part of the evidence chain for the decision itself.