Template
Architecture Decision Record (ADR).
A lightweight document structure for capturing the context, options, and outcomes behind key technical decisions.
Template sections
What an ADR includes
- Context and problem statement with constraints and goals.
- Options considered with pros/cons, risks, and trade‑offs.
- Decision and rationale with success criteria.
- Consequences and follow‑ups (migration steps, debt, runbooks).
- Appendix: links to spikes, benchmarks, docs, and discussions.
Usage guidance
When to write an ADR
- Choosing core components: databases, message buses, auth, runtimes.
- Setting cross‑cutting standards (observability, CI/CD, APIs).
- Defining integration patterns or domain boundaries.
- Addressing significant risks, costs, or reversibility concerns.