Getting Started with Architectural Decision Records (ADR) for Your Project

2 min read ⚡️Last tended a year ago
Budding 🌿Planted a year ago


When working on an existing software project, have you ever wondered about these questions?

  1. Why were certain past decisions made in a particular manner? Why did the colleagues before you adopt this tech stack in the past? What was the context of the problem?
  2. Can I propose a change to the product? What is a good approach to begin a discussion where the benefits and drawbacks can be discussed?

First introduced by Michael Nygard, Architectural Decision Records (ADR) is the answer you are looking for.

This article will discuss what ADRs are and how I have included it in my current project.

What are ADRs?

Architectural decision records (ADR) detail important decisions the development team makes regarding a critical component of the software architecture they intend to create. Each ADR explains the architectural choice, its context, and its implications.

ADRs are short, modular documents which interested team members can scan quickly to understand the motivation behind certain decisions. They are meant to help new members to familiarise themselves with the project quickly and aid the team in tracking various decisions over time.

Why write ADRs?

  • They are short, modular documents which interested team members can scan quickly to understand the motivation behind certain decisions. They can serve as a valuable tool for documenting the software architecture and its changes for the lifecycle of the project.

  • They can help new members to familiarise themselves with the project quickly. Newcomers will grasp which components are crucial to the infrastructure and improve their contextual knowledge of the project.

  • The ADR process serves as a discussion platform for members to propose changes in a structured manner. Benefits and tradeoffs have to be considered carefully before being accepted collectively.

  • They help to improve the transparency of the team. Anyone interested in the project can read about the decision process over time.


Let's see how an ADR is typically structured.

TitleConcise name with sequential tagADR 1: Use Java or Go
ContextExplain why a decision have to be madeWe need to develop a new backend microservice
DecisionResponse to the proposalUse Go
StatusWhether it is reviewed, accepted or supersededAccepted
ConsequencesList both advantages and disadvantage to the proposed approachSome learning curve for the team

Feel free to change the format to a structure that fits your teams' needs.


As a sole developer and maintainer of my own website, I evaluate different tools, coding patterns, and design decisions to include in my website. Information will inevitably be forgotten over time. Hence, it is essential for me to retain these decision logs collectively in a timely manner. It will be a simplified ADR process, whereby I am the sole decision maker.


There are plenty of useful open-source tools to generate ADR templates and manage the decision logs. For example, I have selected phodal/adr as my tool of choice to maintain the ADRs for my personal website. Alternatively, you may opt to use any existing team collaboration tools like Confluence.

Benefits of phodal/adr

  1. Runs on Node (cross-platform)
  2. Feature-rich (includes search, export etc.)
  3. User-friendly

For detailed comparsion across other short-listed tools.

How to Use

  1. Install
npm install -g adr
  1. Init
adr init en
  1. Create new record
adr new <title>
  1. List all records
adr list

The decision logs for my project can also be found here.


I believe implementing a proper ADR process will be a worthwhile investment for your team and stakeholders. It reminds me of, a document which Aleksey Kladov proposes to help improve documentation for open source projects.


It makes my day when I see it.
Jupyter Tips & Tricks for Python, R, JuliaHow I Built My Website
Walter Teng © 2023