Who hasn’t had someone ask why an option was decided some time ago that now, on paper, seems like the most reasonable one? Or who made that decision? No one in the room usually knows. Someone will probably start searching through emails and chats and find a message with some clues, but no one knows for sure. After half an hour of discussion, it’s deemed impossible to figure out what happened. These kinds of situations, which occur in almost every organization, are exactly the problem that Architecture Decision Records (ADRs) help solve.
What Is an ADR
An ADR is a brief document that records a significant decision, the context in which it was made, the alternatives that were considered, and the consequences (both positive and negative) that are accepted by making that decision. It is neither a lengthy design document nor a technical specification; rather, it is a snapshot of the reasoning at a specific moment, designed so that anyone reading it months or years later can understand not only what was decided, but also the full context—including the why, who was involved, and other details deemed relevant to the decision.
The structure is usually simple: a title, a status (proposed, accepted, rejected, replaced), the context that led to the decision, the decision itself, and the consequences that result from it. That simplicity is precisely its strength: an ADR can be written in half an hour and read in five minutes, which ensures it’s actually used—unlike other, more cumbersome documentation that almost no one keeps up to date.
Depending on the type of decision and its impact, additional fields can be added, such as rejected options, people involved, or risks.
What They’re For
The most obvious benefit is traceability: when someone wonders why the system is the way it is, or why a process is done a certain way, there’s a place to look for the answer instead of reconstructing it from memory or, worse, repeating a debate that’s already taken place. But there are other, perhaps less obvious, benefits:
- Onboarding. A new team member can read the relevant ADRs and quickly understand the reasoning behind decisions that would otherwise seem arbitrary or even debatable.
- Consistency over time. Organizations see people come and go, and with them, tacit knowledge is lost. ADRs are a way to preserve that knowledge regardless of who is present in the room.
- Better decision quality. The simple act of having to write down the context and alternatives forces people to think more rigorously before deciding—similar to what we discussed some time ago regarding the importance of documentation.
- Avoiding debates over what has already been decided. When a decision is documented—along with its context and rationale—it’s much harder for anyone to question it without providing new information. And if new information does emerge, the ADR is precisely the place to record that the decision has evolved.
They’re not just for technical decisions
I want to pause here, because this is the central idea of this post. When people talk about ADRs, the almost automatic association is with software architecture decisions: which database to use, which messaging pattern, whether or not to adopt microservices. And it’s true that this was the origin of the concept. But reducing ADRs to purely technical matters is to squander much of their potential.
Any significant decision—one that’s difficult to reverse and has a major impact on the organization—is a candidate for its own ADR, regardless of the domain it belongs to. Deciding to centralize a function that was previously distributed across business units, choosing a data governance model, defining what information is shared with third parties, establishing a vendor policy, or even organizational decisions such as changing the reporting structure of a department—all of these follow the same pattern as a technical decision. There is a context, there are alternatives, there is a choice, and there are consequences that someone will have to live with afterward.
This approach aligns naturally with how we understand enterprise architecture. If we recall the four domains typically described in frameworks such as TOGAF—business, information, applications, and technology—we’ll see that ADRs make sense and add value in each of them, not just the last one.
Business Domain
In this domain, an ADR can document decisions regarding the operating model, organizational structure, definition of key processes, or the distribution of responsibilities among units. For example, the decision to centralize customer service rather than keep it distributed by region has profound and lasting implications. Documenting why that decision was made, which alternatives were ruled out (for example, a hybrid model), and which consequences were accepted (for example, less local proximity in exchange for greater consistency) prevents someone from proposing, three years down the line, to reverse the change without understanding the real reasons that justified it.
Information Domain
Here, ADRs are particularly valuable because decisions about data often have consequences that take years to fully manifest. Choosing a centralized or federated data governance model, deciding what constitutes master data and who owns it, or establishing a retention and privacy policy are decisions that silently shape everything built thereafter. A well-written ADR in this domain helps ensure that, when a data quality or duplication issue arises, it is clear whether it is an intended consequence of a previous decision or an unforeseen effect that warrants review.
Application Domain
This is the most common area for ADRs and likely where the reader is already most familiar with them: decisions regarding integration patterns, choosing between an off-the-shelf product and custom development, adopting a microservices or event-driven architecture, and criteria for decoupling systems. What’s interesting is that when these decisions are documented using the same format as business or information decisions, it becomes much easier to see how they relate to one another: an application decision is almost always the consequence of a business decision, and having both documented using the same language helps maintain the consistency we discussed earlier when referring to systems thinking.
Technology Domain
Finally, in the technology domain, we find decisions regarding infrastructure, cloud providers, security standards, and platform tools. These are decisions that typically involve particularly high long-term costs and dependencies, closely related to what we discussed when talking about lock-in. An ADR that documents why a specific provider was chosen, which alternatives were evaluated, and which dependency risks were consciously accepted is a very useful tool for critically reviewing that decision when market conditions change.
When to Use Them and Who Should Use Them
Not every decision warrants an ADR. Writing one for every minor choice would generate more noise than value and would end up, like so many other documentation initiatives, falling into disuse. The rule of thumb that works best is to ask whether the decision is significant, whether it is costly to reverse, and whether it is likely that someone in the future will wonder why it was made. If the answer to those questions is yes, it warrants an ADR.
As for who should use them, the honest answer is: any role that makes structural decisions, not just the software architect. A business process manager, a data director, a security manager, a product manager who decides the scope of a platform—all of them make decisions of the same type, albeit in different domains, and all would benefit from leaving that same trail of reasoning.
The Underlying Benefit for the Organization
Beyond the individual benefit of each ADR, what truly adds value is the accumulation of many of them over time: a coherent history of why the organization is the way it is today. This history reduces reliance on the memories of just a few people, facilitates the onboarding of new hires, prevents the unnecessary reopening of debates that have already been settled, and—perhaps most importantly—forces us to make explicit the reasoning behind decisions that would otherwise remain mere assertions of authority (“we do it this way because I say so”).
At its core, an ADR is an exercise in humility: acknowledging that no decision is self-evident, that there are always alternatives that were ruled out and consequences that someone will have to manage, and that it’s worth documenting all of this for those who come after us. It doesn’t have to be long, perfect, or definitive. It just needs to be honest.
The next time someone in a meeting asks, “Why did we do this this way?”, the ideal situation isn’t having to reconstruct the answer from memory, sifting through several conflicting versions. The ideal situation is being able to say, “It’s in the ADR,” and open it up.