Using ADRs
An Architectural Decision Record (ADR) is a short note about a decision that affects how a system is built: what we chose, why we chose it, and what we give up by choosing it. I use ADRs to make the reasoning visible, not to add paperwork or make every code change a committee meeting. Keep them with the code, in a place the team knows to look, so they can be reviewed alongside the work and found later.
Benefits of Using ADRs
- Remembering why: Later, the team can see why we made a choice instead of having to guess from the code.
- Getting aligned: Writing down the tradeoffs gives the people who have to live with a decision a chance to discuss it before it is hard to change.
- Onboarding: New team members can get the context behind the system, not just a list of tools and patterns.
- Revisiting decisions: An ADR does not make a decision permanent. It gives us a place to start when the requirements or constraints change.
Example of an ADR
Here is a small example. I would keep this Markdown file in the repository and review it with the people affected by the decision. It starts as Proposed; if the team agrees, change it to Accepted and merge it. If the team does not agree, record that too. The point is to keep the decision and its reasoning around, not to force every proposal through.
# Use ADRs for Significant Architectural Decisions
Date: 2026-10-03
Status: Proposed
## Context
Decisions that shape the system are discussed in meetings, pull requests,
and chat. Later, it can be hard to find why we made a choice or what
alternatives we considered.
## Decision
Write a short ADR for decisions with a lasting effect on the system or
how the team works. Keep it in the repository and review it with the
affected team before implementing the decision. Routine implementation
choices do not need an ADR.
## Consequences
- The reasoning and alternatives will be easier to find later.
- The team has a clear point to revisit if the constraints change.
- Writing and maintaining ADRs takes time, so keep them focused.
ADRs in Practice
This was a lot of technical information on why to use an ADR, but what about the human element? This is where an ADR can really shine. Once upon a time, I was onboarding into a new team and we were told by the architects to use CQRS style commands and queries and to use the Mediatr library in .Net. The team was all new to this company and more familiar with the Service onion approach where you have a service interface that you import into the Controller. The decision felt very arbitrary and we got the feeling that some architect in their ivory tower was making pronouncements that we must follow.
There was no ADR, no documentation on why we would want to make this change. The team fought against it. We found all the pain points and ignored all the benefits. If we had been given an ADR cleanly defining why and making it clear that this approach was thought through and well-considered, a lot of the friction and resistance would have dissipated. If we had a chance to approve the decision for the project, we could have had the conversations upfront. As it stands, the team eventually bought into the approach but only after fighting against it for over a year.
Fast forward to a few years ago, I'm joining a new company. This time, I'm working on a "mature" project that was already in production. A team of contractors maintained the project. No ADRs, no documentation. One of the first things I did is come through and create ADRs for the existing decisions and C4 documentation for the existing system. The team actually fought against the creation of documentation, claiming it was a waste of their time. This was a classic case of "nobody can maintain the product if I don't tell anyone what it does". The CTO and I went through the decisions and found a whole lot of waste and bad faith development. For instance, we found that when the name of the product was changed, the team spent almost 6 weeks updating all of the code references. Not just the copy, but the namespaces, the project folders, the git project name. All stuff that didn't actually need to change, but since they were paid for all the work, they stretched it out. They also actively sabotaged an attempt to add Unit Tests to the project because a brittle project takes more work. We ended up dropping that contracting firm for failing to deliver what they promised and going over budget. A new team that was brought in and was able to quickly come to terms with what the reality was and how to move forward. And you better believe that we made ADRs explaining the decisions and getting the team's buy-in.