Architectural Decision Record

I firmly believe there is no such thing as a "bad" or a "good" architecture. It either fits the business needs from a technical perspective, or

3 years ago

Latest Post Deferring decisions in Evolutionary Architecture by Tim Sommer public

I firmly believe there is no such thing as a "bad" or a "good" architecture. It either fits the business needs from a technical perspective, or it doesn't. A technical design is always the result of a series of "choices" and "decisions" throughout the lifetime of that design. But it's not good or bad, it's a matter of how fit the design is, given the current and historical constraints and requirements.

It's critical that you hold a good "record" or "log" of those design decisions. Because that's the reason why any design is at a certain state, at any given point in time. This post is meant to aid developers and architects into creating such "decision logs". And for this, we will use Architectural Decision Records (or ADR's).

The art of decision making

Having to make decisions on a regular basis can create a great deal of uncertainty and anxiety. Especially if that decision has an impact on the evolvability of your design. Did I think this decision over long enough? Did I take enough data into consideration? But in the end, you'll find that you never could take enough data into consideration. The data for any given situation is infinite.

And as such, worriers are people who think of all the variables beyond their control, and what might happen, and as a result are afraid to make the wrong decision.

To be clear, I'm not implying that you shouldn't think about your decisions. But you should never be afraid to make one. Even if every decision you make throughout the path of your evolving design is wrong, as long as your design is evolving, you're on the correct path. And as long as you record your decision process, you open new doors down the road, to correct the incorrect.


Your technical documentation should have different "types". A high level (system-) design, an application design, infrastructure details, etc.
ADR's are a bit a-typical, but they should not (!) be regarded as a replacement for other types of technical documentation!

The Architectural Decision Record (as the name implies) is a log of decisions made by a team while they evolve the design of their application. It can be documented in many ways, with all sorts of templates. It should, however, always include the following information:

So an ADR, once integrated in your technical workflow, allows you to document informed decisions in a formal way.  A design record is created for future reference, and can be used to present your decisions to management in a formal and conclusive way.

A solution summary will look something like the picture below.

Decision process

So, I've explained the what, who and why of ADR's. Let's take a look at the how. When documenting ADR's, keep the following in mind:


Architectural Decision Records are a powerful tool for documenting the design decision making process.
Does that mean that you will now automatically make all the right decisions with these ADR's? Nope. But it will provide insights as to why certain choices were made. If the decision turns out wrong, the most valuable part is getting a grasp on why it was wrong. Who made the call, did he/she have the right information, did anyone else see the problem in a different way? This information is extremely valuable for evolving your design in the way you want, and to gain more experience in the process.

Big thanks to Karin Wauters and Marijke Walgraeve for reviewing this post.

Photo by Kaleidico on Unsplash

Tim Sommer

Published 3 years ago


Leave us your opinion.