Architectural Decision Records (ADRs) are important vehicles for communicating the architectural decisions a development team makes about a system. Lacking a clear definition of what is architectural, and also lacking anywhere else to record important decisions, they can start to drift from their original purpose and lose focus and effectiveness.

ADRs are intended to expose architectural decisions, and in so doing improve transparency and accountability. But when it becomes bloated with every decision a team makes, it becomes the antithesis because the architectural decisions can’t be easily seen amidst everything else that’s been thrown into an ADR.

Why are ADRs needed?

In a previous article, we observed that in a dynamic software development approach, in which solutions evolve over time (e.g. agile), software architecture is defined by a set of decisions about how the system will handle quality attribute requirements. This is in contrast to an up-front architectural approach in which the architecture is defined primarily in a software architecture document.

An ADR makes architectural decisions transparent, helping the development team to clarify what it is doing and why, and to preserve that reasoning for people who will support and enhance the system in the future.

When software architecture evolves through a series of decisions, themselves born of hypotheses and experiments that test those hypotheses, development teams need a way to keep track of the architectural decisions they have made.

Over time, some of these decisions may change, and the development team needs a way to easily examine the decisions. Even when they don’t change, future teams will need to understand the choices and trade-offs that were considered so they can make better decisions about the evolution of the system.  

What is the purpose of an ADR?

There isn’t a simple answer to this. Authors writing on the subject agree that it should document significant decisions, and some go further to say architecturally significant decisions. This sounds reasonable, but it’s hard to come to a consensus on what is significant, and even harder to decide what is architectural.

Many teams, lacking a place to record any sort of significant decision, put any decision they consider significant into an ADR, diluting the architectural aspects and turning an ADR into an “Any Decision Record”. Doing so overloads the ADR with lots of decisions that should not be there, and whose presence merely makes the really significant architectural decisions harder to see. So to decide what to put in an ADR, we have to decide what is architectural? And that’s not as easy as it might seem.

What is “architectural”?

Recently, we’ve caught ourselves in one of those “Princess Bride” moments in which Iñigo Montoya, played by Mandy Patinkin, says to Vizzini, played by Wallace Shawn, “You keep using that word … I do not think it means what you think it means.”

We throw around the word “architecture”, at least in the software context, and we act like we know exactly what it means. But when we more closely examine the concept, we have a hard time pinning down exactly what this means. In this article, we try to more clearly define what we think is architectural and what is not, and provide more explicit criteria for making the decision.

The term “architecture”, as it is applied to software development, is actually part of the problem; it’s the wrong metaphor. Architecture in the physical world is concerned largely with usability and aesthetics. What we call “software architecture” is more similar to structural engineering, which is mostly concerned with how a physical system resiliently handles loads.

Similarly, the art of “software architecture” is to anticipate the loads of a software system and to design for them. A key difference is that struc