0. Emtpy ADR-template
- Status: proposed
- Deciders: [list everyone involved in the decision]
- Date: 2026-01-05
Technical Story: [description | ticket/issue URL]
Context and Problem Statement
[Describe the context and problem statement, e.g., in free form using two to three sentences. You may want to articulate the problem in form of a question.]
Decision Drivers
- [driver 1, e.g., a force, facing concern, …]
- [driver 2, e.g., a force, facing concern, …]
- …
Considered Options
- [option 1]
- [option 2]
- [option 3]
- …
Decision Outcome
Chosen option: “[option 1]”, because [justification. e.g., only option, which meets k.o. criterion decision driver | which resolves force force | … | comes out best (see below)].
Positive Consequences:
- [e.g., improvement of quality attribute satisfaction, follow-up decisions required, …]
- …
Negative consequences:
- [e.g., compromising quality attribute, follow-up decisions required, …]
- …
Pros and Cons of the Options
[option 1]
[example | description | pointer to more information | …]
- Good, because [argument a]
- Good, because [argument b]
- Bad, because [argument c]
- …
[option 2]
[example | description | pointer to more information | …]
- Good, because [argument a]
- Good, because [argument b]
- Bad, because [argument c]
- …
[option 3]
[example | description | pointer to more information | …]
- Good, because [argument a]
- Good, because [argument b]
- Bad, because [argument c]
- …
Additional Information
Here are some questions to maybe assess the architectural significance of the decision. Try to avoid defining every little thing as an ADR.
- The requirement is directly associated with high business value (benefit vs. cost) or business risk.
- The requirement is a concern of a particularly important stakeholder such as the project sponsor or an external compliance auditor.
- The requirement includes runtime Quality-of-Service (QoS) characteristics (such as performance needs) that deviate from those already satisfied by the evolving architecture substantially.
- The requirement causes new or deals with one or more existing external dependencies that might have unpredictable, unreliable and/or uncontrollable behavior.
- The requirement has a cross-cutting nature and therefore affects multiple parts of the system and their interactions; it may even have system-wide impact, short term and/or in the long run (examples: security, monitoring).
- The requirement has a First-of-a-Kind (FOAK) character: For instance, this team has never built a component or subsystem that satisfies this particular requirement before.
- The requirement has been troublesome and caused critical situations, budget overruns or client dissatisfaction on a previous project in a similar context.
Links
- [Link type] [Link to ADR]
You can add links via the adr tool e.g.:
adr link 12 Amends 10 "Amended by"
or while creating a new one:
adr new -l "10:Amends:Amended by" Use Mysql as a Database.
The other option is to use manual linking like this:
[ADR0001]({{< relref "docs/architecture/adr/0000-empty-adr-template.md" >}}) produces:
ADR0001
Or use normal markdown links (also supports relative linking): [\<Link Name\>]\(docs/architecture/adr/0000-empty-adr-template.md) - Produces: Link Name
…