An architecture decision record (ADR) is a short, structured document that captures a significant architectural decision made during software development — recording what was decided, the context driving the decision, what alternatives were considered and rejected, and what consequences are expected. ADRs live in the codebase alongside the code they describe, creating a chronological decision log that future developers can consult to understand why the system is designed the way it is.
An ADR answers the question every engineer asks when they join a project: "Why does this work this way?"
Where ADRs Come From
The architecture decision record format was introduced by Michael Nygard in a 2011 blog post, "Documenting Architecture Decisions." Nygard observed a persistent problem in software teams: architecturally significant decisions got made and then forgotten. New team members couldn't understand why the system was structured as it was. Teams revisited decisions that had already been made and discarded, wasting time. Hotly debated decisions became invisible as soon as they were resolved.
Nygard's proposed solution was deliberately minimal: a short, flat-file text document per decision, stored in the codebase under docs/adr/, with a handful of standard sections. The goal was to make it easy enough to write that engineers would actually do it — not to create a comprehensive design document.
ADRs gained significant traction in the 2010s:
- ThoughtWorks Technology Radar featured ADRs as a "Trial" technique in 2016 and "Adopt" by 2020
- Several tooling projects emerged (
adr-tools, log4brains, Backstage plugins) to manage ADR collections
- Major engineering organizations (Spotify, Amazon, Netflix) began publishing their use of ADRs in engineering blog posts
- The term "MADR" (Markdown Architectural Decision Records) emerged as a specific template variant with more structured sections
ADRs are now a standard practice in mature engineering organizations, particularly those practicing evolutionary architecture or working with distributed systems.
The Standard ADR Structure
Nygard's original format included five sections:
Title: A short noun phrase identifying the decision. "Use PostgreSQL as the primary data store."
Status: The current state of the decision — proposed, accepted, deprecated, or superseded (with a reference to the superseding ADR).
Context: The situation or forces driving this decision. What was the problem? What constraints existed? Why did this decision need to be made at all?
Decision: What was decided. Written as a single, clear statement. Active voice.
Consequences: What happens as a result — both positive and negative. Tradeoffs accepted. Future implications.
Extended versions (MADR template) often add:
- Problem statement (what specific question is being answered)
- Considered options (the alternatives that were evaluated and why they were rejected)
- Decision outcome (rationale for the chosen option)
A Worked Example
ADR-0015: Use PostgreSQL for the primary relational data store
Status: Accepted (2024-03-12)
Context:
We need a relational database for the user account, billing, and subscription data that require ACID compliance. The team is evaluating the choice for the MVP launch. We have three engineers; all have experience with PostgreSQL and MySQL. Cloud hosting is AWS.
Decision:
We will use PostgreSQL on Amazon RDS as our primary relational database.
Considered options:
- PostgreSQL on RDS: strong ACID compliance, team familiarity, rich JSON support for flexible data, excellent AWS integration, managed backups and failover
- MySQL on RDS: team familiar, fewer advanced features (full-text search, JSONB less capable)
- Amazon Aurora (PostgreSQL-compatible): better performance and availability but significantly higher cost for our current scale; revisit at 10M+ rows
- DynamoDB: poor fit for relational data models with complex joins and transactions
Consequences:
Positive: team can move fast with existing knowledge; JSONB gives flexibility for evolving data models; pg extensions (pgvector, PostGIS) available if needed later.
Negative: we commit to PostgreSQL-specific features — migration away would be non-trivial. Aurora's performance ceiling unavailable until we upgrade.
This decision supersedes no prior ADRs. If we cross 10M rows with performance issues, revisit Aurora migration (see ADR-0008 on scaling strategy).
This ADR takes 10 minutes to write and provides permanent context for future engineers asking "why PostgreSQL and not DynamoDB?"
What Decisions Warrant an ADR
Not every technical decision needs an ADR — that would create noise that undermines the value of the record. ADRs are valuable when:
The decision is architecturally significant:
Decisions that affect the structure, scalability, security, or constraints of the system. Choice of database, message broker, authentication approach, monolith vs. microservices, API design patterns.
The decision is non-obvious:
If the reasoning isn't immediately apparent from the code or configuration, an ADR captures the "why." A decision that required research, debate, or trade-offs probably warrants an ADR.
The decision will be questioned later:
Decisions that colleagues or future team members will encounter, disagree with, or need to change — recording the reasoning prevents revisiting settled ground and gives future changers the context to understand what they're trading away.
The decision was debated:
If the team seriously considered alternatives, that debate deserves to be recorded. The rejected options are often as valuable as the accepted decision.
Where ADRs Live
The standard location is a docs/adr/ directory in the repository, with files named NNNN-title-in-kebab-case.md. Numbering is sequential (ADR-0001, ADR-0002, etc.).
Keeping ADRs in the repository provides:
- Version history (git tracks when the ADR was written and how it changed)
- Proximity to the code it describes
- Discovery in code review (engineers can see ADRs alongside PRs)
- Automatic surfacing when engineers clone or browse the repo
Some organizations store ADRs in wikis (Confluence, Notion) for broader discoverability — this trades proximity to code for accessibility to non-engineers. Both approaches work; the choice depends on who needs to access ADRs and how.
Common Misconceptions About Architecture Decision Records
"ADRs are only for major decisions — big architecture choices."
ADRs are most valuable for significant decisions, but "significant" is lower-threshold than teams often assume. A decision about which logging format to use, whether to use an ORM or raw SQL, or which error-tracking service to adopt can all be worth recording if the reasoning isn't obvious from the code and the decision might be questioned later.
"ADRs should capture the current architecture, not just decisions."
ADRs capture decisions (the moment of choice and its reasoning), not architecture (the current state of the system). Architecture diagrams, README files, and documentation serve the state-description purpose. ADRs serve the decision-history purpose. Trying to make ADRs describe current state rather than historical decisions undermines both functions.
"Once written, ADRs shouldn't change."
ADRs shouldn't be edited retroactively to make past reasoning look better — that corrupts the historical record. But an ADR can be superseded: when a later decision replaces it, the earlier ADR is marked "superseded by ADR-0042" and a new ADR captures the new decision. The status field manages the lifecycle.
Related Concepts
Institutional knowledge: ADRs are a specific mechanism for capturing the most durable category of engineering institutional knowledge — the reasoning behind architectural decisions.
Runbooks: The operational complement to ADRs — runbooks document procedures; ADRs document architectural decisions.
Documentation debt: The gap between what should be documented and what is — ADRs are a targeted intervention for one specific and high-value category of missing documentation.
Technical debt: The code equivalent of documentation debt — ADRs often record decisions that accept technical debt in exchange for short-term velocity, making the trade explicit.
Frequently Asked Questions
What's the difference between an ADR and design documentation?
Design documentation describes how a system works — architecture diagrams, component descriptions, data models. ADRs document why it works that way — the decision points, the alternatives, the reasoning. Both are valuable; they answer different questions. ADRs are lighter-weight and decision-focused; design docs are heavier and state-focused.
How do you handle teams that don't write ADRs consistently?
Consistency is the hard part. Common approaches: make ADR creation part of the definition of done for architectural decisions; review ADR-worthiness in architecture review or pull request review; start small and build the habit with 3-5 clear examples of what your team considers ADR-worthy. Tooling helps (adr-tools makes creation fast), but culture is more important than tooling.
How long should an ADR be?
Typically 200-400 words. Nygard's original format was intentionally short — long enough to capture the essential context, reasoning, and consequences, short enough that engineers will actually write and read them. If an ADR is running to 1,000+ words, it may be combining multiple decisions or crossing into design documentation.
Key Takeaways
- Architecture decision records (ADRs) are short structured documents capturing significant architectural decisions — what was decided, why, what alternatives were considered, and what consequences follow.
- Created by Michael Nygard (2011) — deliberately minimal format to maximize the likelihood of adoption.
- Standard sections: title, status, context, decision, consequences (with considered options often added).
- Live in the repository (
docs/adr/) for proximity to code, version history, and automatic discovery.
- Not all decisions need ADRs — focus on architecturally significant, non-obvious, or debated decisions.
- ADRs are superseded, not edited — historical accuracy is preserved; later decisions reference the prior ADR and record the new choice.
Conclusion
Architecture decision records are one of the highest-return documentation investments an engineering team can make. They're quick to write, live in the codebase where they're immediately useful, and directly answer the question that every engineer who touches the system will eventually ask: "Why is this the way it is?" The pattern of documenting not just the decision but the rejected alternatives and the reasoning is what gives ADRs their distinctive value — preserving not just the outcome of engineering thinking but the thinking itself.
Try WebSnips free — as you research architectural options (blog posts, documentation, benchmarks, case studies), clip and organize the relevant references by decision topic into collections, so the research backing your ADRs is organized and accessible when you need to revisit those decisions.