Solving \"Why Did We Choose This Again?\" - The Concept of ADR

Recently, I wrote an article on Zenn about selecting a project management tool, and someone commented with advice: "I think you should write an ADR."

To be honest, until that moment, I had never heard of the term ADR.

"What's an ADR?"

"Here comes another confusing acronym..."

That's what I thought as I started researching, but once I understood it, I thought, "I wish I had known about this earlier." In this article, I'll share what I learned about ADR, written for those who, like me, are hearing about it for the first time.

What is ADR?

ADR stands for "Architecture Decision Record."

Simply put, it's a document that records the reasons and background behind technical decisions. The concept was introduced by Michael Nygard in his 2011 blog post "Documenting Architecture Decisions" and is relatively well-known in the software engineering community.

Basic Structure

Typically, it consists of these sections:

# [Number]. [Decision Title]

## Status
Proposed | Accepted | Deprecated | Superseded by: ADR-XXX

## Context
Why was this decision necessary?
What problems or challenges existed?

## Decision
What did we choose?

## Consequences
What are the benefits and drawbacks of this decision?

That's it. Surprisingly simple, right?

Why ADR is Necessary

Six months later, when someone wonders "Why are we using this tool?", what happens?

Common patterns:

With ADR, you can understand the following by reading just one file:

Difference from Meeting Minutes

Some may wonder, "Isn't that just meeting minutes?"

Actually, ADR and meeting minutes serve different roles.

Meeting Minutes (Record of Process)

14:00 Person A: I think Linear is good
14:05 Person B: But it has an English UI, right?
14:10 Person C: What about Jira?
14:15 Person A: Jira is expensive
...(conversation continues)

Records what happened chronologically

ADR (Record of Decision)

## Decision: Adopt Linear

## Reasons
- Simple (learned from past mistakes)
- Reasonable cost
- Enables cross-organizational visibility

## Rejected Options
- Jira: Expensive and complex
- GitHub Projects: Insufficient reporting features

Records why the decision was made in a structured format

Which would be clearer to read six months later?

Both are necessary, but as an explanation to your future selves, ADR is more suitable.

Practical Implementation Methods

Git Management

ADRs are commonly managed in Git.

project-root/
├── docs/
│   └── adr/
│       ├── 0001-choose-database.md
│       ├── 0002-use-microservices.md
│       └── 0003-select-pm-tool.md

File names often follow the number-slug format. You can see "what decisions were made" just by looking at the list.

5-Minute Template

If you aim for perfection, it won't last. This simple approach is fine:

# 0003. Adopt Linear

## Context
- Redmine and Azure DevOps are mixed
- Want to unify

## Decision
Adopt Linear
- Simple
- Cost: $3,000/year

## Consequences
Good: Simple, cheap
Bad: English UI, limited customization

Details: [Meeting minutes](link)

If you can't write it in 5-10 minutes, something is wrong.

Preventing It from Becoming a Formality

As I deepened my understanding of ADR, a question arose: "Isn't preventing documentation from becoming a formality the most important thing?"

When I researched, I found typical patterns where ADR becomes a formality:

Common Failures

Practical Countermeasures

1. Lower the Barrier

70% of the information is enough. The remaining 30% can be supplemented with links to meeting minutes.

Completion over perfection. Publishing over completion.

2. Create a Mechanism to be Read

Just writing is not enough. It needs to be actually used in situations like:

3. Make it a Living Document

It's not over once written.

## Status
Accepted (2026-01-22)

## Update (2026-04-15)
What we learned after using it for 3 months:
- The English UI wasn't as problematic as we thought
- However, custom fields were insufficient, ended up using spreadsheets alongside

Create a mechanism that continuously generates value.

4. Don't Force It

If you mandate "ADR required for all technical decisions!", you'll mass-produce superficial ADRs.

Culture doesn't arise from enforcement. It arises from experiencing usefulness.

First, write one and share it with the team. If someone feels "this is useful," it will naturally spread.

The Trap of Perfectionism

"Isn't it hard to create an ADR that properly covers all information?"

This question is a point where many people stumble when introducing ADR.

Realistic Perspective

Actually, ADR doesn't need to cover 100%.

What new members want to know first six months later:

This alone solves 80% of questions.

The remaining 20% (like "detailed budget discussions?") can be checked in meeting minutes when needed.

Comparison: Perfectionism vs Pragmatism

【Perfectionism】
Creation time: 3 hours
Completeness: 100%
Writing frequency: 1-2 times per year

Result: Most decisions are not recorded

【Pragmatism】
Creation time: 5-10 minutes
Completeness: 70-80%
Writing frequency: 2-3 times per month

Result: Most decisions are recorded

Having 70% of the information is far better than having 0% of 100% perfect information.

In My Case

The article I recently wrote about selecting a project management tool was actually already structured like an ADR.

What's missing is "complete record of detailed discussions," but that's not necessary from the start.

Rather, the moment you think "let's create a perfect ADR," nobody will write them, and having nothing recorded is the real problem.

Summary

What I learned as someone who didn't know about ADR:

I aim to write articles where you can feel "a real person is writing this," and I felt that ADR, which records technical decision-making processes, has a similar philosophy.

Leave minimal information as a letter to your future selves.

That's what I understood as the essence of ADR.

Related Books

For those who want to learn more deeply about architecture design and technical decision-making, the following book is recommended.

References

ADR Basics

Practical Examples

Templates