Skip to main content
Last Updated: 2026-06-12 Architecture Decision Records (ADRs) document significant architectural choices — the context, options considered, decision made, and consequences. They are permanent records; superseded ADRs are never deleted. Template: specs/_templates/ADR_TEMPLATE.md

​
When to Write an ADR

Write an ADR when:
  • Choosing between multiple viable approaches with significant trade-offs
  • The decision will outlast a single sprint or affect multiple cores
  • A new dependency, pattern, or cross-core boundary is introduced
  • Reversing the decision would take more than a sprint
Skip ADRs for: obvious single-option choices, reversible single-function decisions, or purely cosmetic changes.

​
ADR Index

​
Process

  1. Propose: Create a new ADR file (next sequential number) from the template. Set status Proposed.
  2. Review: Open a PR; relevant stakeholders review. Add as PR checklist item when introducing new patterns.
  3. Accept: Merge the PR; set status Accepted. Update this index.
  4. Supersede: If a decision changes, write a new ADR that supersedes the old one. Update the old ADR’s status to Superseded by ADR-NNN.
Tip: Each ADR should take 10–30 minutes to write. If it takes longer, the decision likely needs to be split.