Architecture Decision Records

🕑 Estimated reading time: 7mn

Table of Contents

Google News

Architecture Decision Records: A documentation that evolves with you

By Olivier Revial, Lead developer @ Stack Labs
Video [FR]

Different shades of documentation

Different types of documentations can be organized by context from study to work and level of practice from theoretical to practical. The following diagram gives an example for each category:

            Tutorial            |            How-to
   Teaching approach, basics    |   Practical, step-by-step
◄-- Study --------------------- + --------------------- Work --►
                                |                           Context
          Explanations          |           Reference
      Answers to the Whys       |   Exhaustive documentation

On this scale, Architecture Decision Records would be close to explanations. They document the technical choices, their context and their reasons.

In a Waterfall project, the functional and technical documentations are decided and written before starting the development phase. Choices and decisions being already documented, ADRs would not be useful in those cases. Thus, ADRs are more fit to Agile projects.

Not only that but the evolution from monolithic to micro-services architectures induce an increase in the number and complexity of the decisions to make on a regular basis and the importance of contextualizing and backing every decision.

One of the most common forms of documentation is to have a Wiki, an architecture diagram for your project and explain the choices and evolutions made to reach the diagram. This approach works but forces the application to always be aligned with the documentation. An alignment issue can cause the loss of part of the project history, which can lead to the ossification to a part of the project. This, in turn, can either lead to increased debt if the development team is afraid to break things or actual breakeage in case they should not have removed code that looked unused.

What if, instead of documenting the whole application at every instant, we focused on a history that has the power to render part of an application obsolete and safely detacheable? That is where ADRs come into play.

Architecture Decision Records

Rules and composition

There are many formats of ADRs and the best one fits to your team and systems. Nevertheless, an Architect Decision Record will always contain the following set of information:


Much like a decision, an ADR can deprecate and replace other ADRs. A replaced ADR must indicate that it has been replaced in its status and the newer ADR must also mention it in its context.

An ADR can only have the following statuses:

In addition, the “(Replaced)” mention can be appended to the status field when a newer decision obsoletes the one the mention is appended to.

The lifecycle of an ADR would look like this:

Writing ------- Decision ------------------------ End of Life

Proposal ---------------- Accepted ------ Accepted (Replaced)
    ▲       |     |
     -------       ------ Rejected 


Any tool can do the job. ADRs are just tables containing data. A Wiki, a repository or even a set of spreadsheets. The tool you will choose depends on the needs of your team. In any case, keep it simple.


Working with ADRs will enable you to keep a history of the choices made in a project. These choices can be shared within the teams and discussed. Maintaining this solution requires processes so its integration in your daily Agile must be clarified and agreed upon from the start, as well as the format you want to respect.

It is very important to stick to the process of redacting these documents for the future of the product you are developing!

Questions and Answers session

Is it possible to add ADRs to existing projects?

It is even desirable to do so! Still, this may be rendered difficult by the fact that context might be lost and you might spend a lot of time digging to find the exact information you need. ADRs can be added at any given moment to any project!

If ADRs are used before development, what happens after?

ADRs are considered during the design phase of a task. They may also incur during spikes or moments when you need to try solutions before deciding. As such, the deciders may not be the ones involved with the development.

What happens when an ADR does not lead to positive results?

This situation is unfortunately not prevented. In the end, the process allows the development team to analyze a solution from different perspectives. Reaching the consensus means that the whole development team is persuaded that the solution responds positively to the given problem, knowing the involved context and agrees on the choices and its specificities.