What ADRs are, when to write one, and how to start using Architectural Decision Records
- Background
Recently, I’ve been looking into how large engineering organizations manage and document architectural decisions over time.
Across most teams I’ve worked with, there’s rarely a clear record explaining why a given approach was chosen. The implementation lives in code, but the reasoning is lost. This makes it harder to:
Understand historical decisions
Onboard new team members
Revisit or improve past solutions
Avoid repeating previous discussions
To address this, many companies use Architectural Decision Records (ADRs).
- What Are ADRs?
An Architectural Decision Record (ADR) is a short document that captures:
A significant architectural decision
The context in which it was made
The alternatives considered
The reasoning behind the chosen solution
The consequences of that decision
ADRs are:
Lightweight (usually 1–2 pages)
Stored in the Git repository
Written in Markdown
Version-controlled alongside the code
They are not long design documents — just focused records of important decisions.
- Why Use ADRs?
Preserve Decision Context
Instead of asking: “Why did we implement it this way?”
We can look at the ADR and see:
What constraints existed
What trade-offs were considered
Why other options were rejected
Improve Onboarding
New team members can:
Read ADRs to understand major system choices
Learn system philosophy faster
Avoid repeating already-discussed ideas
Enable Better Future Decisions
When revisiting architecture, ADRs help us:
Evaluate whether assumptions still hold
Understand consequences of past trade-offs
Make changes intentionally instead of reactively
Align Team Thinking
Writing ADRs forces us to:
Clarify trade-offs
Explicitly evaluate alternatives
Make decisions more intentional
- What Kind of Decisions Should Have an ADR?
If you’re unsure, ask in your team’s design review or ping whoever owns that part of the system.
Not every small change needs one.
ADRs are useful for decisions that are:
Hard to reverse
When there are multiple viable options
When the decision involves trade-offs — You’re balancing things like: speed vs scalability, simplicity vs flexibility, cost vs performance
Cross-cutting (affects multiple systems/services)
Security-related
Performance-critical
Infrastructure-related
Affecting external APIs or contracts
Introducing new frameworks or major dependencies
If a decision is important, create an ADR even if there are no clear trade-offs or alternatives. Documenting the context and reasoning is still valuable.
Examples:
Choosing between REST and gRPC for a new internal service
Adopting a message queue instead of synchronous calls
Picking a multi-tenancy strategy (shared DB vs schema-per-tenant)
Introducing a caching layer and its invalidation strategy
- A Simple ADR Template
We can use a simple template like this:
## StatusProposed | Accepted | Rejected | Superseded
## DateYYYY-MM-DD
## ContextDescribe the problem, background, and why this decision is needed.
- What is happening?- What constraints exist? (technical, business, timeline)- What problem are we solving?
## DecisionDescribe the chosen solution.
## Alternatives Considered- Option A- Option B- Option C
## Consequences### Positive- ...
### Negative- ...
Each ADR would:
Have a number (ADR-0001, ADR-0002, etc.)
Be stored in /docs/adr/
Be committed in the same PR as the related change (when possible)
- Example From Industry
Many large engineering organizations use ADRs.
For example, GitLab documents architectural and design decisions publicly in their handbook:
When making a significant architectural decision: Create a new ADR file in /docs/adr/
Share it in PR for review
Once agreed, mark the status as Accepted
If the decision changes later:
Create a new ADR
Reference the previous one
Mark the old one as superseded.
Keep it simple. No heavy governance.
- What You Get Out of It
If we adopt ADRs, we can expect:
Better long-term maintainability
Clear historical record of architectural evolution
Faster onboarding
More structured technical discussions
Reduced knowledge silos
- How to Start
You don’t need everyone to agree before you start. You can do this on your own:
Make a /docs/adr/ folder and put a simple template in it
Write ADR-0001 about a decision your team already made. Writing it after the fact is fine
Add a link to it in your next PR
Wait and see if people find it useful before you add any rules around it
How long an ADR takes depends on the decision. A big one may need days of investigation and discussion. But that work happens anyway before you decide. The ADR just captures what you already worked out, so the writing part is usually short.
- Take the Template
The full template is here, free to copy and change however you want:
Save it as /docs/adr/0000-template.md in your repo and copy it every time you write a new ADR. If you change something to fit your team better, I'd like to hear about it. Leave a comment on the gist.