ADR Title

Overview

This template provides a structured approach to documenting architectural decisions. Use the YAML drafting guide below to organize your thoughts before writing the full ADR.

YAML Drafting Guide

Use this comprehensive YAML template to draft your ADR before writing the full documentation:

# ADR Drafting Worksheet - Complete this first to organize your thinking
adr:
  title: "[Clear, descriptive title of the decision]"
  description: "[Brief summary of what is being decided]"
  author: "[Your name or team name]"
  date: "[YYYY-MM-DD]"

  context:
    scenario: "[What business scenario or use case is this for?]"
    problem: "[What specific problem are you solving?]"
    background: "[Additional context that readers need to understand]"

    stakeholders:
      primary: "[Who is most affected by this decision?]"
      secondary: "[Who else needs to know about this decision?]"

    constraints:
      technical:
        - "[Platform limitations]"
        - "[Integration requirements]"
        - "[Performance requirements]"
      business:
        - "[Budget constraints]"
        - "[Timeline requirements]"
        - "[Regulatory compliance]"
      organizational:
        - "[Team expertise]"
        - "[Operational capabilities]"
        - "[Strategic direction]"

    success_criteria:
      quantitative:
        - "[Measurable performance target]"
        - "[Cost target]"
        - "[Timeline goal]"
      qualitative:
        - "[Maintainability goal]"
        - "[Security posture]"
        - "[Developer experience]"

  decision:
    summary: "[One clear sentence stating what was decided]"
    rationale: "[Why this decision was made - key reasoning]"
    implementation_approach: "[High-level approach to implementing this decision]"

  decision_drivers:
    - name: "[Driver 1 - e.g., Performance Requirements]"
      description: "[Why this factor influenced the decision]"
      weight: "[High/Medium/Low priority]"
    - name: "[Driver 2 - e.g., Cost Optimization]"
      description: "[Why this factor influenced the decision]"
      weight: "[High/Medium/Low priority]"
    - name: "[Driver 3 - e.g., Team Expertise]"
      description: "[Why this factor influenced the decision]"
      weight: "[High/Medium/Low priority]"

  considered_options:
    - name: "[Option 1 - e.g., Technology A]"
      description: "[Brief description of what this option entails]"

      technical_details:
        - "[Architecture approach]"
        - "[Key components]"
        - "[Integration requirements]"

      pros:
        - "[Specific advantage 1]"
        - "[Specific advantage 2]"
        - "[Quantifiable benefit]"

      cons:
        - "[Specific disadvantage 1]"
        - "[Specific disadvantage 2]"
        - "[Quantifiable limitation]"

      risks:
        - risk: "[Risk description]"
          probability: "[High/Medium/Low]"
          impact: "[High/Medium/Low]"
          mitigation: "[How to address this risk]"

      dependencies:
        - "[External dependency]"
        - "[Internal capability requirement]"
        - "[Timeline dependency]"

      costs:
        initial: "[Implementation cost]"
        ongoing: "[Operational cost]"
        effort: "[Development effort required]"

    - name: "[Option 2 - e.g., Technology B]"
      description: "[Brief description]"
      technical_details: ["[Key technical aspects]"]
      pros: ["[Advantages]"]
      cons: ["[Disadvantages]"]
      risks:
        - risk: "[Risk]"
          probability: "[Level]"
          impact: "[Level]"
          mitigation: "[Mitigation strategy]"
      dependencies: ["[Dependencies]"]
      costs:
        initial: "[Cost]"
        ongoing: "[Cost]"
        effort: "[Effort]"

  comparison_matrix:
    criteria:
      - name: "[Evaluation criteria 1]"
        weight: "[High/Medium/Low]"
        option_1_score: "[Score/Rating]"
        option_2_score: "[Score/Rating]"
      - name: "[Evaluation criteria 2]"
        weight: "[High/Medium/Low]"
        option_1_score: "[Score/Rating]"
        option_2_score: "[Score/Rating]"

  consequences:
    positive:
      - "[Positive outcome 1]"
      - "[Positive outcome 2]"
    negative:
      - "[Negative impact 1]"
      - "[Negative impact 2]"
    neutral:
      - "[Neutral change 1]"
      - "[Neutral change 2]"
    risks:
      - "[Risk that remains after decision]"
      - "[Monitoring requirement]"

  implementation:
    phases:
      - "[Phase 1 description]"
      - "[Phase 2 description]"
    timeline: "[Expected timeline]"
    resources_required: "[Team/budget/tools needed]"
    success_metrics: "[How to measure success]"

  future_considerations:
    monitoring:
      - "[What to watch for]"
      - "[When to re-evaluate]"
    evolution:
      - "[Future technology to consider]"
      - "[Upcoming decisions that may affect this]"
    triggers_for_review:
      - "[Condition that would trigger re-evaluation]"
      - "[Timeline for regular review]"

---

ADR Document Structure

After completing the YAML drafting guide above, use this structure for your final ADR:

Status

[Mark the most applicable status for tracking purposes]

• Draft
• Proposed
• Accepted
• Deprecated

Context

Scenario Context: [Describe the business scenario or use case]

Problem Statement: [Clearly articulate the problem being solved]

Constraints and Requirements: [Document technical, business, and organizational boundaries]

Success Criteria: [Define measurable outcomes for success]

Decision

Decision Statement: [Clear, single sentence stating what was decided]

Decision Rationale: [Explain the reasoning behind this decision]

Implementation Approach: [Outline how this decision will be implemented]

Decision Drivers (optional)

List the key factors that influenced this decision:

• [Driver 1]
• [Driver 2]
• [Driver 3]

Considered Options (optional)

Option Evaluation Framework: [For each option considered, provide:]

Option [Number]: [Option Name]

Description: [What this option entails]

Technical Details: [Architecture, components, requirements]

Pros: [Specific advantages with supporting detail]

Cons: [Specific disadvantages with impact assessment]

Risks and Mitigation: [Risks with probability, impact, and mitigation strategies]

Dependencies: [External dependencies and prerequisites]

Cost Analysis: [Implementation and operational costs]

Comparison Matrix (optional)

Criteria	Option 1	Option 2	Option 3	Weight
[Criteria 1]	[Score]	[Score]	[Score]	[H/M/L]
[Criteria 2]	[Score]	[Score]	[Score]	[H/M/L]

Consequences

Positive Consequences: [Benefits and positive outcomes]

Negative Consequences: [Risks and negative impacts]

Neutral Consequences: [Other changes or considerations]

Future Considerations (optional)

Monitoring and Evolution: [What to watch for and when to re-evaluate]

Review Triggers: [Conditions that would require re-evaluation of this decision]

---

🤖 Crafted with precision by ✨Copilot following brilliant human instruction, then carefully refined by our team of discerning human reviewers.