Documenting Architectural Decisions with ADRs

1. The Problem: The Mystery of the "Why"

As a developer, you've likely encountered code, a library, or a design pattern in a project and had no idea why it was chosen. This "codebase archaeology" is a common and frustrating experience that slows down development and increases the risk of making poor changes.

The core issue is the loss of context. The original team understood the constraints, the alternatives they considered, and the reasons for their final choice. But this knowledge often exists only in meetings, chat logs, or people's heads, and it fades over time.

To understand this problem more deeply and see how ADRs provide a solution, let's start with a short video.

As the video highlights, the goal is to create a persistent log that captures the context and reasoning behind significant decisions. This is precisely the purpose of an Architecture Decision Record.

2. What is an Architecture Decision Record?

An Architecture Decision Record (ADR) is a short, text-based document that captures a single, important architectural decision. The collection of all ADRs for a project forms an Architecture Decision Log (ADL).

So, what makes a decision "architecturally significant"? It's any choice that has a measurable effect on the system's structure, non-functional characteristics (-ilities), dependencies, interfaces, or construction techniques.

To get a formal definition, let's turn to another expert.

Key points to remember:

• One Decision per Record: Each ADR focuses on a single decision to maintain clarity.
• Immutable Log: ADRs are not "living documentation" that you constantly update. They are a historical record of a decision made at a point in time. If a decision is changed later, you create a new ADR that supersedes the old one, preserving the history.
• Stored with the Code: ADRs are typically written in a format like Markdown and stored in the project's version control repository (e.g., in a docs/adr/ directory). This keeps them close to the code they describe.

3. The Anatomy of an ADR

While various templates exist, the most common one, proposed by Michael Nygard, consists of a few key sections. Understanding these is key to writing effective ADRs.

Let's explore these sections with a reading and a video walkthrough.

Now, let's see these components come to life with a concrete example.

To summarize, a standard ADR includes:

• Title: A short, numbered noun phrase describing the decision. E.g., 001-Record-architecture-decisions.
• Status: The current state of the decision (e.g., Proposed, Accepted, Superseded by ADR-005).
• Context: This is the "why." It describes the problem, the forces at play, the constraints, and the alternatives considered. This is arguably the most important section.
• Decision: This is the "what." A clear and affirmative statement of the chosen course of action. It often starts with "We will..." to be unambiguous.
• Consequences: This captures the "so what?"—the trade-offs. It should list both the positive outcomes of the decision and any negative impacts, new risks, or future decisions that are now required.

While text-based templates are common, some teams use more visual or collaborative formats.

4. The ADR Workflow and Tooling

Creating ADRs should be a lightweight process integrated into your team's workflow.

The Process:

1. Draft: When a significant decision point arises, a team member creates a new ADR file and drafts the Context, listing alternatives.
2. Review: The draft is shared with the team (e.g., via a pull request). This is where discussion and debate happen. The goal is to reach a consensus.
3. Approve: Once the team agrees, the Decision and Consequences are filled out, the status is set to Accepted, and the ADR is merged into the main branch.
4. Supersede: If a future decision invalidates an old one, a new ADR is created. This new ADR explicitly states that it supersedes the old one (e.g., Supersedes ADR-002), and the old ADR's status is updated to Superseded by ADR-015. The history is preserved.

Tooling and Resources:

You can manage ADRs with simple text files, but tools can streamline the process. adr-tools is a popular command-line utility that helps initialize a directory, create new ADRs from a template, and link between them.

The video from CodeOpinion you watched earlier demonstrates these tools in action from 04:08 onwards.

For practical application, having good templates and examples is invaluable. The following resource is a comprehensive collection.

Conclusion

You have now learned how to formalize and document the "why" behind your architectural choices. This simple practice elevates your work from just writing code to building a sustainable, understandable, and evolvable system. It's a fundamental skill for moving from a developer to an architect.

Key Takeaways:

• ADRs solve the problem of lost context by creating a permanent, written record of why a decision was made.
• An effective ADR captures the Context, the Decision, and the Consequences (trade-offs).
• ADRs form an immutable log, stored with the codebase, where new decisions supersede old ones without erasing history.
• This practice is a powerful communication tool that helps align teams, onboard new members, and guide the long-term evolution of a software system.

Preview of the Next Lesson:
With this module on architectural patterns complete, we will shift our focus in the next module, "Designing Scalable & Resilient Systems," to the specific components and techniques used to build systems that can handle growth and failure gracefully. We will begin by exploring a fundamental building block for scalability: the load balancer, and analyze the different algorithms it can use to distribute traffic.