TECH | Architecture decision record (english version)

Architecture Decision Records (ADR) is a little-known technique in the living documentation palette, it centralizes and makes explicit a set of architectural decisions made over time, capturing the context and their possible alternatives. It complements the documentation very well with the code when these decisions concern the evolutionary architecture of your project.

An ADR1 can be local (within a component), or global (within an IT department).

As we will see, an ADR derives its strength from transparency and collaboration.

We will also consider a possible usecase outside IT.

There is always a reason to choose

A decision starts with conscious or unconscious reasoning, whether it is a managerial constraint, laziness to explore several avenues, a habit, or a study.

The aim of ADR is to capture this reasoning in the form of a log (Decision Record) with the following properties:

The strength of Decision Records

The architectural decisions you make don’t just impact you. They impact the current team, future developers but also people external to the projects.

By systematizing the writing of Decision Record you force yourself to start from the space of the problem before entering the space of solutions (explain why before exploring the how).

By systematizing review by at least one peer, you ensure that the choice made is shared and understood by others, that the context is right, that alternatives have been explored. That a future developer will be able to understand this decision.

Notice the glaring similarities with development. It’s not for nothing that most ADRs are actually git repositories, where every decision is a commit, a proposed decision, or a decision review is a merge request.

Interestingly, most of the ADR examples on github have their first decision record: adopt ADR. The technique is used to validate the technique decision.

If the process is correctly followed, the very act of validating the adoption of the technique must go through a stage of contextualization, clarification and approval.

The weaknesses of Decision Records

Like any collaboration technique based on knowledge transfer, it encounters limitations. Let’s take a quick tour of the weaknesses and ways to overcome them.

Cumbersome to write a decision record

It is not for nothing that Thoughtwork talks about “Lightweight Architecture Decision Records”, the goal is to find a decision record format that is easy to write. The form (eg Markdown) can be simplified, but what about the substance?

Complexity of defining a decision record

As with many things, it is about defining the characteristics that define the quality of a decision, allowing its value to be maximized while maintaining a certain pragmatism.

Spend as much time as possible defining the properties you want to achieve. More often than not, solutions will emerge on their own.

If several solutions emerge, do not be afraid to choose a solution and try, there is no such thing as a perfect architecture, if you have defined and documented the properties you want to achieve upstream you have done a great job of architecture, the final choice will then be a measured risk-taking.


Here the word is out. Who is responsible for ADR? Everybody ? But if it’s everyone, it’s nobody. The architect? There aren’t always, and he’s not all-knowing anyway.

Here we put our finger on the larger problem of documentation, when it is not documentation by code. At the beginning of the article I wrote that “Architecture Decision Records (ADR) is a technique”, in reality it is a discipline.

This documentation must fit into a definition of done framework, just like a rest API or library documentation.

Beyond Tech

It’s not just developers who have problems with implicit, forgotten or misunderstood decisions. Take any team in your company with some turnovers and you’ll hear the same king od questions:

This discipline has a greater scope than Tech. Like any technique / discipline it can evolve to be reused and adapted to sectors other than the one that popularized it.

Now I’m going to complete my Life Decision Record explaining why I decided to write an article on ADR.

  1. If you would like to see an example of an ADR implementation I invite you to follow this link