Do you use Architectural Decision Records (ADRs)?
Loading last updated info...
Architectural Decision Records (ADRs) are lightweight documents used to record important decisions in your project, and the reasons behind them.
These records aren't limited to architectural choices but can encompass any crucial decision made by the team, making ADRs versatile as "Architecture/Any Decision Records".
Typically, this is the data it will have:
- Title
- Deciders
- Problem / Context
- Decision
- Decision Drivers
- Options and Pros/Cons
Video: Architecture Decision Records (ADRs) | Daniel Mackay (9 min)
⚠️ The dangers of not documenting important decisions
- Lack of transparency and communication
- Loss of intellectual property
- Loss of historical context
- Risk of repeating mistakes
- Difficulty in auditing and governance
✅ The advantages of using ADRs
- Providing documentation and historical context
- Collaboration and communication
- Informed Decision making
- Decision re-evaluation
- Avoiding blind acceptance or reversal
The act of documenting an important decision, forces developers to think more objectively about their decision. If the decision is likely to cause contention it may be quicker to document it via an ADR and get feedback, than it would be to implement the change and let the reviewer try to infer your reasoning.
Additionally, documenting decision 'deciders' ensures that we have a 2nd pair of eyes across the decision, just like we do with the checked by rule, test please rule, and pull-requests.
ADRs can also help with knowledge sharing across teams, as other Solution Architects will have access to a succinct explanation of the problem and the decided solution.
Another benefit is that future developers joining the project now have access to the historical context as to why certain decisions were made.
Where should ADRs be stored?
They should be stored wherever the technical documentation for your project lives. Storing them in Git along with your code works well, but alternatively wherever your technical documentation lives (i.e. a wiki).
What decisions go in an ADR?
- High impact decisions
- Irreversible or costly to change
- Decisions with long term implications
- Anything that needs to be discussed with others
- Choosing between multiple options with different pros and cons
What can I use to create and manage ADRs?
An ADR can be in any format, but it should be easily readable and accessible. Some options are:
- ⭐ Recommended - A dedicated ADR tool like Log4Brains (see details below)
- Markdown files in your git repo
- Wiki (e.g. GitHub or Confluence)
- Loop
Log4Brains
Log4Brains can help to create and view ADRs.
This can be installed by running:
npm install -g log4brains
You can then initialize your git repo by running:
log4brains init
Which will guide you through a simple setup process.
To create a new ADR, run:
log4brains adr new
Lastly, to preview your ADRs, run:
log4brains preview
ADR examples
Figure: SSW.CleanArchitecture KB showing all ADRs
Figure: Example of a single ADR from SSW.CleanArchitecture
You can see more examples of ADRs with log4brains in action on our SSW.CleanArchitecture template.