ADR Template

Context

Describe the context and background that led to this decision. Include:

• What is the problem or opportunity?
• What are the current constraints?
• What business or technical drivers are relevant?
• What is the scope of this decision?

Be factual and neutral. This section should help readers understand the situation without bias toward any particular solution.

Current State

If relevant, describe the current state of the system:

• How does the system work today?
• What are the pain points?
• What are the limitations?

Decision

State the decision clearly and concisely.

We will [do X].

Explain the decision in more detail:

• What specifically are we doing?
• What are the key aspects of this decision?
• What are the boundaries of this decision?

Implementation Approach

If relevant, outline the high-level implementation approach:

1. Step one
2. Step two
3. Step three

Alternatives Considered

Alternative 1: [Name]

Description: Brief description of this alternative.

Pros:

• Pro 1
• Pro 2

Cons:

• Con 1
• Con 2

Why not chosen: Explanation of why this was rejected.

Alternative 2: [Name]

Description: Brief description of this alternative.

Pros:

• Pro 1
• Pro 2

Cons:

• Con 1
• Con 2

Why not chosen: Explanation of why this was rejected.

Alternative 3: Do Nothing

Description: Maintain the status quo.

Pros:

• No implementation effort
• No risk of regression

Cons:

• Problem remains unsolved
• [Other cons]

Why not chosen: The cost of inaction outweighs the cost of change.

Consequences

Positive

• Benefit 1
• Benefit 2
• Benefit 3

Negative

• Drawback 1 (and how we’ll mitigate it)
• Drawback 2 (and how we’ll mitigate it)

Neutral

• Change 1 (neither good nor bad, just different)
• Change 2

Security Considerations

Describe any security implications of this decision:

• Does this affect authentication or authorization?
• Does this introduce new attack surfaces?
• Does this change data handling or storage?
• What security reviews or testing are needed?

Performance Considerations

Describe any performance implications:

• Expected impact on latency
• Expected impact on throughput
• Expected impact on resource usage
• Benchmarks or estimates

Migration

If this decision requires changes to existing systems or data:

Migration Strategy

1. Phase 1: Description
2. Phase 2: Description
3. Phase 3: Description

Rollback Plan

How can this decision be reversed if needed?

Timeline

• Start date: YYYY-MM-DD
• Target completion: YYYY-MM-DD

Validation

How will we know this decision was successful?

• Metric 1: Target value
• Metric 2: Target value
• Success criteria

Related Decisions

• ADR-NNNN: Related decision 1
• ADR-NNNN: Related decision 2

References

• [Link to relevant documentation]
• [Link to relevant discussion]
• [Link to relevant research]

Decision History