Architecture Decision Record (ADR)

When to Use

• Making significant technical decisions that affect system architecture
• Choosing between technology options (frameworks, databases, services)
• Establishing patterns that future development should follow
• Documenting the rationale for constraints or non-obvious approaches
• Preserving institutional knowledge about past decisions

Instructions

1. Assign a Number and Title ADRs are numbered sequentially (ADR-001, ADR-002, etc.) for easy reference. The title should be a short noun phrase describing the decision, like "Use PostgreSQL for order data" or "Adopt React for frontend."
2. Set the Status New ADRs start as "Proposed." After team review, they become "Accepted," "Deprecated," or "Superseded by ADR-XXX." Status changes should be tracked.
3. Describe the Context Explain the circumstances that led to this decision. What problem are you solving? What forces are at play (technical constraints, team expertise, timeline, cost)? This section should help a reader who wasn't there understand why this decision was needed.
4. State the Decision Clearly articulate what you decided. Use active voice: "We will use..." rather than "It was decided..." Be specific about what is and isn't included in the decision.
5. Document the Consequences List the outcomes of this decision . positive, negative, and neutral. Good ADRs are honest about trade-offs. What becomes easier? What becomes harder? What new constraints or options does this create?

Output Format

references/TEMPLATE.md

Quality Checklist

• Title is a short, descriptive noun phrase
• Status is clearly indicated (Proposed/Accepted/Deprecated/Superseded)
• Context explains why this decision was needed
• Decision is stated clearly in active voice
• Consequences include both positive and negative outcomes
• ADR can stand alone without requiring other documents

Examples

references/EXAMPLE.md