Skip to content


Remote work

Architecture Decision Records: the memory of your distributed software development team

01 Apr 2020


Cedric Pontet


It is always good for a team to keep track of the decisions that are made within it. It makes the integration of a new team member easier and avoids asking yourself the same question again six months after a decision has been made. What is a good practice for a co-located team, becomes a mandatory practice for a distributed team.

For an agile team, it is customary to documented such decisions in a lightweight manner, usually thanks to a wiki or similar tools. This is especially true for team conventions and work agreements. But what about technical decisions?

With Architectural Decision Records (ADR), a team can keep track of any significant software design choice that addresses a functional or non-functional requirement. But instead of keeping these records in a wiki, which is not necessarily the favorite tool of developers, why not use MADR, a Markdown template specifically designed for this task? The MADR npm package provides a template to write down your decisions and a tool called adr-log that will allow you to generate an index file for all your decision records. Alternatively, you can decide to install adr-tools that will make your life even easier.

The main advantage of this approach is that all your architectural decisions are directly tracked within your codebase, in your Git repository. Therefore you never need to ask yourself the dreadful question Where is this thing documented again? All your decisions are right there, and they are automatically versions thanks to your source control system.

Since November 2017, Lightweight Architecture Decision Records have been the Adopt ring of Thoughtworks' Technology Radar. This proves that this practice is generalizing. Again, this practice makes even more sense for a distributed team, where it requires mode discipline to keep track of the any decision taken in order to keep a consistent architecture.

So put all the chances on your side and start with ADR right from the start for your new project. If you are working on a brownfield project, it's not too late either. Just start logging your ADR now and catch up with all the decisions that have already been taken whenever you remember one.


Do you have a software development project? Do you need help with Agile?