Skip to content

{Your Title Here}

Info

Status: { Proposed | Under Review | Accepted | Rejected | Superseded | Deprecated }

Level: { 1 - 4 }

Updated: { YYYY-MM-DD }

Summary

{This is the 'executive summary' or 'elevator pitch' for your ADR. In a few concise sentences (typically 2-4), clearly state the core problem, question, or opportunity this ADR addresses. Include a brief hint at the decision made or the area of focus. The goal is to help readers quickly understand what this ADR is about and decide if it's relevant to them, without needing to read the entire document. Think of it as the abstract of a technical paper or a very brief introduction to the main topic.}

Drivers

{This section explains why this decision is being made now. Clearly articulate the primary motivations, needs, or problems that necessitate this architectural decision. Think about the underlying reasons and pressures.}

  • {e.g. We are developing a new feature/capability that needs...}
  • {e.g. We need to improve performance, accessibility, remove debt...}
  • {e.g. Feedback from users suggests...}
  • {e.g. The current approach imposes these limitations...}

Options

{This is where you list the different options you are considering. Stick to the facts and avoid opinions, the next section covers the analysis. Include a concise description, links to relevant documentation or examples.

Include all significant alternatives you explored, even if they were ultimately not chosen. The goal is to give readers a clear, unbiased understanding of each alternative before you dive into the evaluation.}

{Option 1 Title}

{Describe the option, provide a summary, list the facts, provide links etc.}

{Option n Title}

...

Options Analysis

{This is where you critically evaluate each option presented in the Options section. For each option, provide a balanced view of its advantages, disadvantages, and any other relevant considerations or trade-offs. Be specific and, where possible, relate your points back to the Drivers.

Consider aspects like:

  • Cost (development, operational, licensing)
  • Complexity (implementation, maintenance, learning curve)
  • Risks (technical, operational, security)
  • Alignment with architectural principles or existing standards
  • Impact on performance, scalability, usability, maintainability, security etc.

Include as many Pro/Con/Other statements as required.}

{Option 1 Assessment}

Pro:

  • {A specific advantage or benefit of this option.}
  • ...

Con:

  • {A specific disadvantage, risk, or cost associated with this option.}
  • ...

Other:

  • {A relevant point that isn't strictly a pro or con.}
  • ...

{Option n Assessment}

...

Recommendation

{This is where you clearly state the final decision, and explicitly name the option that has been selected. Explain in detail why this option was chosen. You should clearly articulate how the chosen option best addresses the Drivers and meets the key requirements or solves the stated problem.}

Consequences

{This section is optional.}

{Now that a decision has been made what are the expected outcomes and impacts, both positive and negative? What known limitations, costs, or risks are being accepted by making this decision? How will this decision affect different stakeholders, other systems, development practices, operational procedures, or user experience?}

  • Pro: {A specific positive outcome or benefit expected from this decision.}

  • Con: {A specific accepted downside, cost, or risk resulting from this decision. }

  • Other: {A consequence that isn't strictly a pro or con.}

Confirmation

{This section is optional.}

{Outline how the implementation of this decision will be verified and how ongoing compliance will be ensured. This helps demonstrate that the decision isn't just theoretical but will be actively put into practice and monitored.

How will you check that the decision has been correctly implemented? (e.g., code reviews, specific tests, demonstrations, peer review).

How will adherence to this decision be maintained over time? (e.g., automated checks, periodic audits, updates to team guidelines, training).

Are there specific metrics or indicators that will show the decision is achieving its intended positive outcomes? (e.g., performance benchmarks, adoption rates, reduction in specific errors, user feedback scores).

Who is responsible for overseeing this, and what happens if the decision is not followed?}

More Information

{This section is optional.}

{Use this section to provide any supplementary information that supports the decision, adds context, or guides future actions. Links to other decisions and resources might appear here as well.

You could briefly note who was involved in the decision-making process and if/how consensus was reached. You may also want to suggest a timeframe or specific events that might prompt a re-evaluation of this decision in the future.}