Skip to content
Software Architecture Guide

ADR Common Mistakes and Review Checklist

Explanation

Section titled “Explanation”

An architectural decision record (ADR) documents one important design decision. See the article Architectural Decision Record. Records often show the same flaws. Each flaw has a simple remedy.

Common mistakes and remedies

  • Criteria bent to fit the favorite. Some records build their criteria only from the properties of the option the author already prefers. Remedy: derive criteria from the context and the requirements, and make them explicit.
  • Missing alternatives. Teams often do not record the options they considered. They also reject alternatives without enough justification. Remedy: list the options and say why each rejected one lost.
  • A decision section with no “why.” Some records only repeat the ADR title in the decision section. Remedy: state the rationale, meaning the reasons for the choice.
  • Hidden downsides. Two named anti-patterns cover this. The “Free Lunch Coupon” documents no consequences, or only harmless-looking ones. The “Fairy Tale” gives pros but no cons. Remedy: state the negative consequences.
  • Unchecked AI output. Some teams use AI-generated ADR content without a quality check. Remedy: review it critically before accepting it.

Review checklist

A reviewer can ask these questions:

  1. Is the problem relevant enough to be solved and recorded in an ADR?
  2. Do the options have a chance to solve the problem? Are valid options missing?
  3. Are the decision drivers (the criteria) mutually exclusive and collectively exhaustive? Are conflicting criteria prioritized?
  4. Are the pros and cons of each option reported as objectively as possible?
  5. Is the rationale logical?
  6. Is the chosen solution described in an actionable way?
  7. Can the choice be traced back to requirements?

Example

Section titled “Example”

A team records “Use a message queue between the order and billing services.” The decision section only repeats that title. The criteria listed are “supports queues” and “has a queue library,” which describe the chosen option itself. No other option appears. No downside appears either.

A reviewer asks the checklist questions. The team then adds criteria taken from the requirements and lists two other options with reasons for rejecting them. They also add the cons of the queue and a sentence explaining why it wins.

Trade-offs

Section titled “Trade-offs”

The facts here do not describe costs of the checklist itself. One limit is visible: the checklist only exposes gaps. It does not fix them. The team must still write the missing context, options, and consequences. AI output, in particular, needs a critical human read.

Checks

Section titled “Checks”
  • The criteria in the ADR come from the context and requirements, not from the properties of the preferred option.
  • The ADR lists the considered options and justifies the rejection of each alternative.
  • The decision section explains why the option was chosen and does not just repeat the ADR title.
  • The ADR documents negative consequences, not only pros or harmless-looking effects.
  • The chosen solution is described in an actionable way and can be traced back to requirements.
Section titled “Related”

Sources

Section titled “Sources”