Ten Common Mistakes in Architectural Decision Records (ADRs)

I recently reviewed a large number of Architectural Decision Records (ADRs). This has been an interesting exercise. I won’t call any names but point out room for improvement I found multiple times.¹

Motivating Example

Let’s start with a rather extreme example (that I made up):

ADR-001: Use microservices.
Context: We need an architectural style, microservices are popular.
Status: accepted
Decision: We will use the microservices style.
Consequences: The microservices need to be implemented.

A design choice is reported in this ADR, even a popular template is conformed to. What can possibly be wrong? 🤔

Answer: The ADR content has zero value!² It does not answer the essential questions that every ADR should address (see this post for background information):

• Why is this design adequate? ADRs are supposed to preserve knowledge to stop unnecessary design reconsiderations. Which requirements and constraints led to the recorded decision, what caused the chosen design option to be selected from all alternatives?
• What is the result of the decision, its impact on stakeholder roles such as architect, developer, end user, product owner, project sponsor, operator? Such impact might include cost and effort consequences, as well as gaining desired quality properties while compromising others.

Coming back to the example: popularity of a concept can’t be the only reason for choosing it; other selection criteria should have more weight, software quality attributes in particular.³

When justifying Architectural Decisions (ADs), multiple perspectives should be taken, including a quality-oriented one. Discuss conflicts between decision drivers, including requirements and constraints.

Let’s look at the consequences section of the example now. It is somewhat obvious that the made AD has to be executed once it is accepted. Only non-obvious consequences are worth reporting, prioritized by risk and cost. Who gains what, and what is lost?

Many consequences concern architects and developers, but various other stakeholders care about decision outcomes too. Not all consequences are positive; negative ones exist and are worth recording.

Focus on tradeoffs and the need for follow-on ADs.

10 Frequent Decision Recording Issues

Not only made-up examples like the one above struggle to preserve and share rationale properly. It takes some time and practice to get ADRs right (and different styles exist). Here are some of the issues I’ve encountered in real-world ADRs (and academic work):

1. The context is underspecified. Context matters! As an ADR reader, I want to learn about the status quo and why the decision was needed. Desired qualities (the “-ilities”) should be made explicit; addressing them is a primary goal of software architecture. ADRs should be written in a factual style; some “pep talk” in the context is fine to create a sense of urgency and make curious to read on, but the context should not praise any potential solution.
2. Evaluation criteria are not made explicit. How can you decide between design options without clear decision drivers, including desired and/or affected software qualities? Such criteria may go to the context section; a dedicated section may make sense too.
3. The criteria are reverse engineered solely from the properties of a preferred design option. I understand the desire to do so, bias is only human and hard to beat. It is worth trying: context, goals and requirements should drive the decisions — and nothing else. Inverted AD rationale, constructed from the properties of a single solution, is suspicious; it might even be unethical.
4. The considered options are not recorded. A decision that does not identify alternatives and chooses one of them is not a decision. Period.⁴ Identify and discuss at least two options if you want your ADR to be a true decision record rather than a solitary design report.
5. The rejection of alternatives is not justified sufficiently. The reasons to reject certain options often are as interesting as the justification for the chosen option; runner-ups on a short list look different from no-go paths. When I say option, I mean alternative, by the way.⁵ This list item is a warning rather than an error report; sometimes it is ok not to discuss alternatives in depth, for instance when uncovering a decision made for an existing system.
6. The decision section merely repeats the ADR title. Sometimes, redundancy is a good thing; here, it hurts. The decision outcome section must be more elaborate than the title to justify its existence; at a minimum, it explains why the chosen option was selected, referring to option selection criteria and context information.
7. No negative consequences are stated. Philippe Kruchten once said: “The life of a software architect is a long and rapid succession of suboptimal design decisions taken partly in the dark.”⁶ Architecture is about tradeoffs — there are no free design lunches!⁷
8. Only technical consequences are identified. Many consequences sections leave an impression of being incomplete and unbalanced. For instance, only consequences for architects and developers might be listed. What about other stakeholders, those mentioned in the motivating example but also API clients, testers, business partners, related projects? Architects do not operate in isolation. Be empathic, show that you care about the concerns of your stakeholders — in every (design) move you make and when writing ADRs.
9. The ADR template is applied inconsistently. Sometimes, the sections defined in the chosen ADR template are not ordered consistently; extra sections go anywhere they want. Such inconsistencies harm the recognizability of the template; it takes readers longer to consume and comprehend the ADR content.
10. AI has taken over, but its output is used without quality check. I have not seen many instances of this issue in the ADRs that I reviewed this year, as most of them are older than the current AI wave. But I could not resist the temptation to include this item. 😏

Other Observations

Some of the ADRs I reviewed recently do not even cover architecturally significant design concerns; they do not qualify as decision records but descriptions of single implementation-level designs.

I found many context and decision sections to be overly verbose. IMHO, these sections (and the entire ADR) are not the right place for implementation details (as-is or to-be); detailed design specifications deserve their own place in the documentation. Marketing speech and wishful thinking are not appropriate in ADRs either.

Designing and deciding without concrete decision drivers, software quality goals in particular, is a violation of fundamental engineering principles. Architecture is a means to an end, it provides services to its stakeholders (i.e., in-time, on-budget delivery of agreed-upon functionality and quality, preserving conceptual integrity).

To provide decent software architecture services, find out what your stakeholders want and need — and then design/decide in such a way that they appreciate (or at least can live with) the consequences.

This is not only me talking, I confirmed the baseline for the above ADR issue report with many peers. Many comments on the LinkedIn post “Writing better Architecture Decision Records” mention forces (aka decision drivers), alternatives (aka options) and consequences. Both practitioner articles and academic literature identify essential ADR parts; ISO/IEC/IEEE standard 42010:2022 “Systems and software engineering — Architecture description” does so too.

Final Thoughts

To avoid the reported problems, you can annotate the chosen ADR template and/or provide a comprehensive example so that you and your fellow AD recorders are reminded of what makes an ADR valuable. Regular ADR reviews and retrospectives help too. AI can assist with reviews. See this paper and this data set for an ADR review prompt proposal.

Finally, you may want to look for templates that address the highlighted issues explicitly. MADR and its YAML ADR (YADR) sibling, for instance, have a dedicated “decision drivers” section, a place for desired -ilities. MADR comes with template explanations and a blog post that shows what to put where (and why).

Capture ADRs right to stay CALM! One learns well from mistakes, but you do not have to repeat all mistakes others have made. 😉

– Olaf (a.k.a. socadk)

There is more on AD(R)s on my blog. For instance, the blog post “How to create Architectural Decision Records (ADRs) — and how not to” shares patterns and anti-patterns. There is an architectural-decisions tag.

Notes