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.
Example scenarios
Real-world ADR use cases
- Selecting between PostgreSQL and MongoDB for core data storage.
- Choosing REST vs GraphQL for client-facing APIs.
- Adopting event sourcing for order management system.
- Migrating from monolith to microservices architecture.
- Implementing multi-region deployment strategy.
Best practices
Writing effective ADRs
- Keep ADRs concise—aim for 1-2 pages maximum.
- Write ADRs before implementing to enable team review.
- Store ADRs in version control alongside code.
- Number ADRs sequentially (ADR-001, ADR-002, etc).
- Supersede old ADRs rather than deleting them.
Template structure
Suggested ADR format
- Title: ADR-XXX: [Decision in imperative mood]
- Status: Proposed | Accepted | Deprecated | Superseded
- Context: What problem are we solving? Why now?
- Decision Drivers: Key factors influencing the choice
- Options Considered: At least 2-3 alternatives evaluated
- Decision: What we chose and why
- Consequences: Positive outcomes, tradeoffs, and risks