Record context, options and consequences in a concise Architecture Decision Record for everyday project work.
Who is this for? Architecture and development teams who want to understand the reasons for technical decisions on a permanent basis.
Use cases and context
An Architecture Decision Record, or ADR for short, records a relevant decision and its justification. Later, it is often not the chosen technique that is unclear, but why alternatives were rejected and what conditions applied at the time.
An ADR should remain compact enough to actually be read. It complements architecture overviews and binding specifications, but does not replace them. Entries on decisions with longer-term effects, such as data responsibility, integration patterns or central platform services, are particularly helpful.
The approach in detail
- Formulate the decision question. Describe the context, goals, and constraints in a way that future team members can understand.
- Compare seriously considered options. Record advantages, disadvantages and open uncertainties based on the relevant criteria.
- Document the decision, status and consequences. Link a new entry in the event of a later change instead of overwriting the old justification in a way that is unrecognizable.
Expected outcomes
- Comprehensible decision question
- Documented alternatives and trade-offs
- Recognizable consequences for implementation and operation
- Linked history of changed decisions
Prepare for an informed decision
A short template includes the title, status, context, options, decision, consequences, and references. Name stakeholders and decision date if this information is actually known.
Avoid pure product advertising and blanket statements such as "future-proof". Instead, describe which requirement is met and which disadvantage the team consciously accepts.
Questions and answers
Does every small change need an ADR?
No. The effort should match the scope. Recurring local decisions can often be covered by existing standards.
What happens to an overhauled ADR?
It is preserved as history and refers to the replacement decision. In this way, the prerequisites of that time are not lost.