ADR Template
ADR-XXX
Section titled “ADR-XXX”Status
Section titled “Status”[Proposed | Accepted | Deprecated | Superseded by ADR-XXX]
Context
Section titled “Context”What is the issue that we’re seeing that is motivating this decision or change? Provide enough context so that someone reading this in the future understands the “why” behind the decision.
Decision Drivers
Section titled “Decision Drivers”- Driver 1: [e.g., Performance requirements]
- Driver 2: [e.g., Developer experience]
- Driver 3: [e.g., Maintenance burden]
- Driver 4: [e.g., Cost considerations]
Considered Options
Section titled “Considered Options”Option 1: [Name]
Section titled “Option 1: [Name]”Description: Brief description of this approach
Pros:
- Advantage 1
- Advantage 2
Cons:
- Disadvantage 1
- Disadvantage 2
Option 2: [Name]
Section titled “Option 2: [Name]”Description: Brief description of this approach
Pros:
- Advantage 1
- Advantage 2
Cons:
- Disadvantage 1
- Disadvantage 2
Option 3: [Name]
Section titled “Option 3: [Name]”Description: Brief description of this approach
Pros:
- Advantage 1
- Advantage 2
Cons:
- Disadvantage 1
- Disadvantage 2
Decision
Section titled “Decision”We will go with Option X because [justification].
Implementation Details
Section titled “Implementation Details”// Include code examples if relevantconst example = 'implementation details';Consequences
Section titled “Consequences”Positive
Section titled “Positive”- What becomes easier or better as a result of this change
- Performance improvements expected
- Developer experience improvements
Negative
Section titled “Negative”- What becomes more difficult
- Technical debt we’re accepting
- Additional complexity introduced
Neutral
Section titled “Neutral”- Things that change but aren’t necessarily better or worse
- Migration requirements
- Training needs
Validation
Section titled “Validation”How will we know if this decision was correct?
- Metric 1: [e.g., Bundle size remains under 160KB]
- Metric 2: [e.g., Build time under 2 minutes]
- Metric 3: [e.g., Developer satisfaction survey]
References
Section titled “References”- [Link to relevant documentation]
- [Link to proof of concept]
- [Link to benchmark results]
- [Link to team discussion]
Additional implementation notes, migration strategies, or other relevant information that doesn’t fit in the sections above.
Date: YYYY-MM-DD
Participants: [List of people involved in the decision]
Outcome: [Accepted | Rejected | Deferred]