Architectural Decision Record: A Guide to Tracking and Discussing as a Software Engineering Team
What ADRs are and why you should include them in your process
Decisions are a crucial part of our life in a team.
We make daily decisions: how to structure a new functionality, what tool to use, and what library to install. All of these decisions can impact our work and other people’s work. That’s why it is essential to discuss and track decisions.
Once you get your idea accepted, it is essential also to track the decision.
Why has the folder structure of your project changed? Why did you choose one tool instead of another one? Why did you implement this piece of code with that structure?
The reasons behind the decision get lost very fast.
Architectural Decision Records
An Architectural Decision Record (ADR) is the document used to track a decision.
Each decision has its own ADR. You can’t have an ADR related to multiple decisions. The ADR follows the same lifecycle as the related decision.
Let’s start with the structure of the ADR.
The structure
The ADR is a file inside the codebase, in a dedicated section or a documentation folder.
ADR filenames must follow this structure:
0001-my-adr-title.mdThe first part of the name is an incremental number. The second part is the title of the ADR.
There are multiple templates you can use to write your ADRs.
I’ve always used Michael Nygard’s template. It is very basic, and it only has four sections:
Title
Status
Context
Decision
Consequences
Title
The title of the ADR should be a very concise expression of the ADR’s decision.
Reading the title should be enough to understand the topic of the ADR. ADRs are files, and the title will also be the filename. The title should be easy to search.
Some examples we used in your codebase are:
Migrate from flow to typescript
Packages naming convention
Application errors: definition and usage
Status
Every ADR has a status.
The Status reflects the status of the ADR’s decision. The ADR is created with a status Proposal, as its decision still needs to be discussed. Once the decision has been discussed, it can be Approved or Rejected.
When the decision is no longer relevant, it becomes Superseded.
When an ADR becomes Superseded, writing another ADR explaining why the previous one was deprecated is fundamental.
Context
The Context is the section where you explain why the decision is needed.
Why do you need a new library? Why do you need a new tool? Why do you want to change the structure of the current code? Why is the current situation not good?
The Context is the introduction to the decision.
The Context represents the current situation. It is essential for both the discussion and the history of the decision. The reasons behind a decision are all in the Context.
The Context is the “why” of the decision.
Decision
The Decision is the core of the ADR.
It should concisely explain what you want to do based on the Context. What tool did you choose? How do you want to change your current architecture?
Summarize the decision you want to take.
Consequences
The Consequences section should contain all the implications of the Decision.
Assuming the Decision is accepted, what are the Consequences? How will the Decision improve your work? How will it affect the current situation? What should we keep in mind? Are there any downsides?
This is the section where examples are crucial.
The process
Every company might have its process for ADRs.
There are some ground rules, but generally speaking, it is up to you and what is the best fit for your team. In this post, I will explain the process I use with my current team.
Who writes the ADR?
The ADR is written by the developer who wants to make the decision.
Writing ADRs plays a crucial role in holding people accountable. People feel involved and empowered. They have more Context, so they best fit the task.
The ADR should be written by one or more people with more Context.
How is the ADR discussed?
The ADR is presented and discussed in two different situations.
Every two weeks, we hold a general Engineering meeting with all the company's engineers, engineering managers, and the CTO. During this meeting, we have a dedicated section to expose new ADRs. The authors can briefly present their ADRs during this section, with little time for questions.
Most of the time, a dedicated meeting is scheduled for people to discuss things in depth.
Usually, after the dedicated meeting, people had time to read the ADR independently and have enough Context to decide. The decision can be made during the meeting or the following engineering meeting. We try not to rush decisions but do not let ADRs live in the Proposal state for too long.
Usually, we have a decision in a couple of weeks.
After the discussion
When the discussion is finished, the ADR can be Approved or Rejected.
When an ADR is Approved, its Status changes from Proposal to Approved. If it is Rejected, the Status changes from Proposal to Rejected. It is a good practice to move Rejected ADRs to dedicated folders.
This makes it easier to navigate the ADRs folder, ignoring the Rejected ones.
Can you delete Rejected ADRs?
No, you can’t!
Rejected decisions must also be tracked. This is crucial to avoiding the same mistakes in the future. Rejected ADRs record the reasons why a decision was dismissed.
Tracking Rejected ADRs is crucial.
Tools
We use the adr-tool.
It is a straightforward CLI that creates ADRs automatically. It follows the incremental order of the ADRs, and it is shipped with the template.