Architectural Decision Records - A Guide to Better Software Decisions

The content here is under the Attribution 4.0 International (CC BY 4.0) license

Earlier in my career, I realized that the way software was built in industry projects was often based on personal opinions and tastes. For example, familiarity with frameworks, programming languages, and deployment pipelines. As I advanced in the software development lifecycle, I came across this standard that focuses more on what needs to be done and the alternatives that might exist to tackle the same problem.

Moving to a discussion based on pros/cons and architectural features leads to a shared goal and understanding of what needs to be done and how it will be done. Architectural Decision Records (ADRs) come into play to facilitate the dynamics for teams to make decisions that are important and can’t be changed in an afternoon [1].

Throughout ADRs and its different templates it is possible to discuss and put into perspective different profiles that need to be involved in the decision taking process for architectural changes.

What is the problem with taste

As normal as it might sound, personal preferences exist and they should not be avoided, they should be rather controlled. This is because it gets into the way on focusing on the object that the architectural change needs to accomplish.

Favoring taste over objective measurements and options lead to a poorly defined metric or change that might not fulfill the needs of the architecture that aims at targeting the business impact.

It comes from different places, but in my experience most of the personal tastes come from the experience of oneself. The experience is important and should not be neglected, however, when it gets into the way of lacking arguments to defend an idea over another, it is time to evaluate again if the taste is not coming first instead of the solution.

Why ADRs

The reason ADRs became part of my daily work is their simplicity and effectiveness in structuring architectural discussions. They provide a lightweight way to explore ideas, focus on the proposed change, and evaluate the pros and cons of different approaches[2]. Beyond just comparing alternatives, ADRs also offer a space to propose concrete implementation strategies, helping teams align on how a decision will be executed. Importantly, they shift the conversation from personal preferences—such as “I prefer X” to reasoned arguments based on context, trade-offs, and long-term impact.

In addition, ADRs play a crucial role in improving communication within the team. By documenting decisions in a shared, accessible format, they ensure that everyone understands the rationale behind key architectural choices. This transparency fosters trust, reduces misunderstandings, and promotes a culture of shared ownership. Rather than relying on memory or verbal agreements, teams can refer to ADRs as a single source of truth to stay aligned and make informed future decisions.

ADRs history

Before ADRs, architectural decisions were often:

• Discussed verbally or in meetings
• Scattered in emails or chat threads (when recorded at all)
• Different formats
• Many sources of truth for the change done

ADRs were popularized by Michael Nygard (Documenting Architecture Decisions). They provide a lightweight, structured way to capture key architectural choices, the context in which they were made, and their consequences.

The motivation behind ADRs is to avoid losing the reasoning behind important decisions—especially as teams grow or change. Rather than revisiting the same discussions or repeating mistakes, teams can review past ADRs and understand what led to a given decision.

ADRs are de facto standard in many engineering teams. They are used to onboard new developers, revisit decisions, and align architecture with business needs. Often integrated into pull requests.

ADRs in practice

ADRs are typically written in Markdown and stored in a version control system (like Git). They can be organized in a directory structure that reflects the project’s architecture or decision-making process, the following is an example of such structure:

docs/
  ├──
    adrs/
      ├── 0001-background-processing-of-heavy-workload.md
      ├── adr-template.md

The first file is the ADR itself, while the second one is a template that can be used to create new ADRs. GitHub hosts one of the most popular ADR templates, which is a simple Markdown file. Each template has a title, a status (proposed, accepted, rejected, etc.), a context (the problem being solved), however, they differ in the number of sections and the level of detail. At this same place, there is a list of examples of ADRs, such as: Monorepo vs multirepo, Programming languages, Environment variable configuration and etc.

I personally prefer to use the MADR project template as a base and I add sections that I find useful for the project I am working on. Often, I add sections with Proof of concepts and piece of code to compare one another.

Resources

• Why you should be using architecture decision records to document your project
• A personal project built to edit ADRs
• Design It!

References

1. [1]S. Brown, Software Architecture for Developers, 1st ed. 2014 [Online]. Available at: https://leanpub.com/software-architecture-for-developers
2. [2]J. Van der Ven, A. Jansen, P. Avgeriou, and D. K. Hammer, “Using Architectural Decisions,” p. 10, Jan. 2006.