ADR-[NUMBER]: [Descriptive Title]

Date: [YYYY-MM-DD]
Status: [Proposed | Accepted | Deprecated | Superseded]
Deciders: [List of people involved in the decision]
Technical Story: [Ticket/Issue reference if applicable]

Context and Problem Statement

[Describe the situation that necessitates this decision. What challenge are we facing? What opportunity are we addressing? Write this in 2-3 clear sentences that someone new to the project could understand.]

Why is this decision necessary?

[Explain the importance and urgency of making this decision. What happens if we don't address this? What pain points does it solve? This section helps readers understand the motivation.]

Decision Drivers

Key factors influencing our decision:

• [Driver 1 - e.g., Performance requirements]
• [Driver 2 - e.g., Team expertise]
• [Driver 3 - e.g., Time constraints]
• [Additional drivers as needed]

Considered Options

We evaluated the following approaches:

1. [Option 1 Name] - [Brief description]
2. [Option 2 Name] - [Brief description]
3. [Option 3 Name] - [Brief description]

Decision Outcome

Chosen option: "[Selected Option]"

We selected this option because [provide clear justification linking back to the decision drivers].

Why this option?

[Provide detailed explanation of why this option best addresses our needs. Include:

• How it satisfies our key requirements
• What trade-offs we're accepting
• Why other options were less suitable]

Consequences

Positive Outcomes

• [Benefit 1 - e.g., Improved developer experience]
• [Benefit 2 - e.g., Better performance]
• [Additional benefits]

Trade-offs and Considerations

• [Trade-off 1 - e.g., Increased complexity in certain areas]
• [Trade-off 2 - e.g., Additional learning curve]
• [Other considerations]

Implementation Details

File Structure Impact

# Show how this decision affects project organization
src/
├── core/
│   └── [new/modified structure]
└── features/
    └── [affected areas]

Code Examples

// Current implementation approach
[Show existing pattern or structure]

Validation

How we'll measure success:

• [Metric 1 - e.g., 50% reduction in related bugs]
• [Metric 2 - e.g., New developer onboarding time under 2 days]
• [Metric 3 - e.g., Decreased "where does this go?" questions]

Related Resources

• [Link to related ADRs]
• [Link to implementation documentation]
• [Link to example implementations]