Architecture Decision Records Guide 2026
Architecture Decision Records Guide 2026
Architecture Decision Records (ADRs) are one of the highest-leverage documentation practices available to engineering teams. They take 30 minutes to write and prevent weeks of wasted effort relitigating decisions that were already made, poorly understood, or forgotten entirely.
Yet most engineering teams either don't write them, write them inconsistently, or let them rot into irrelevance. This guide covers everything you need to implement ADRs well: what they are, which format to use, when to write one, how to integrate them into your workflow, and how to keep them from dying in a forgotten directory.
TL;DR
An ADR is a short document that captures a significant architectural decision, the context that drove it, and the trade-offs considered. The most popular formats are Michael Nygard's original template and MADR (Markdown Architectural Decision Records). ADRs belong in your code repository, evolve through statuses (proposed, accepted, deprecated, superseded), and are most valuable when integrated into the PR and code review process.
Key Takeaways
- ADRs capture the "why" that code cannot express — essential for onboarding, audits, and preventing repeated debates
- Start with a minimal format (Nygard) and graduate to structured formats (MADR) as the practice matures
- ADRs belong in the repository next to the code they describe
- Status management (proposed → accepted → deprecated → superseded) keeps the ADR log honest
- The PR review process is the right time to require ADRs for significant changes
- Tools like log4brains and adr-tools automate ADR management; a simple numbered directory works just as well
What Is an Architecture Decision Record?
An ADR is a document that captures a single architectural decision, including:
- The context and problem being addressed
- The decision made
- The options considered and why they were rejected
- The consequences — positive and negative — of the decision
The concept was formalized by Michael Nygard in a 2011 blog post. The core insight was simple: code documents what the system does, but rarely why. Engineers maintain code without understanding the trade-offs that shaped it. They change things that were designed intentionally, not accidentally. They relitigate decisions that were already made after careful consideration.
ADRs solve this by making architectural reasoning a first-class artifact.
What Makes a Decision "Architectural"
Not every technical decision needs an ADR. The test is whether the decision:
- Is difficult or expensive to reverse
- Has significant impact on system quality (performance, maintainability, security, scalability)
- Constrains or enables future decisions
- Would not be obvious to a new engineer reading the code
If a future engineer reading the code would reasonably ask "why did they do it this way?" — that's an ADR candidate.
Examples of decisions that warrant ADRs:
- Choosing a database technology (relational vs. document vs. columnar)
- Selecting a message broker and messaging pattern
- Deciding on a service decomposition boundary
- Choosing an authentication mechanism
- Selecting a frontend framework
- Deciding to use event sourcing vs. CRUD for a domain model
- Choosing a deployment architecture (monolith vs. microservices vs. serverless)
- Adopting a specific API design convention
Examples of decisions that do not need ADRs:
- Choosing a code formatter
- Selecting a minor utility library
- Styling conventions
- Individual function implementations
ADR Format Options
Two formats dominate: Nygard's original template and MADR (Markdown Architectural Decision Records).
Michael Nygard Format
The original format, designed to be minimal and fast to write.
# ADR-001: Use PostgreSQL as the primary database
## Status
Accepted
## Context
We need a persistent data store for user accounts, subscription data, and application state. The system will need to handle relational data with complex query patterns.
## Decision
We will use PostgreSQL as our primary relational database, hosted on Neon (serverless PostgreSQL).
## Consequences
- We get a mature, well-understood relational database with strong ACID guarantees.
- The team has existing PostgreSQL expertise, reducing learning curve.
- We are constrained to relational data modeling — document or wide-column storage patterns require more creative schema design.
- Neon's serverless model gives us autoscaling and branch-based development databases.
- We may need to reconsider for workloads that are fundamentally document-oriented in a future phase.
When to use Nygard format: Early-stage teams, teams new to ADRs, or whenever you want to optimize for writing speed over structure. The lower barrier to writing means more ADRs get written.
MADR (Markdown Architectural Decision Records)
A more structured format designed to facilitate decision-making as well as recording. MADR explicitly separates options considered, their pros and cons, and the rationale for the chosen option.
# ADR-001: Use PostgreSQL as the primary database
## Status
Accepted
## Context and Problem Statement
We need a persistent data store for user accounts, subscription data, and application state with complex relational query patterns. What database system should we use?
## Decision Drivers
- Relational data model is the primary access pattern
- Team has existing SQL expertise
- Need strong ACID guarantees for financial transactions
- Must support complex JOIN queries for reporting
- Budget constraints favor managed/serverless options
## Considered Options
- PostgreSQL (Neon, serverless)
- MySQL (PlanetScale, serverless)
- MongoDB (document database)
- DynamoDB (AWS-managed NoSQL)
## Decision Outcome
Chosen option: **PostgreSQL on Neon**, because it best fits the relational data model, leverages existing team expertise, and Neon's serverless model reduces operational overhead.
### Positive Consequences
- Strong ACID guarantees for financial data
- Mature ecosystem with extensive tooling (Prisma, Drizzle, pgAdmin)
- Team expertise reduces onboarding time
- Neon branch databases enable per-PR test databases
### Negative Consequences
- Horizontal write scaling requires careful sharding strategy at high volume
- Document-heavy domains (user-generated content) require more complex schema design
## Pros and Cons of Options
### MySQL (PlanetScale)
- Pro: Similar relational model, good managed offering
- Pro: PlanetScale's branching model is excellent for schema migrations
- Con: Less team expertise than PostgreSQL
- Con: PlanetScale discontinued free tier in 2024, cost structure less favorable
### MongoDB
- Con: Document model doesn't match our primary access patterns
- Con: No ACID transactions across documents (until recent versions)
- Con: Introduces a new paradigm the team would need to learn
### DynamoDB
- Con: Requires upfront data access pattern design; our access patterns are not yet fully understood
- Con: AWS lock-in; higher operational complexity for complex queries
When to use MADR: Teams that want the ADR process to improve decision quality (not just record decisions), larger teams where decisions involve multiple stakeholders, or any time the decision involves non-obvious trade-offs that should be explored explicitly.
Where to Store ADRs
ADRs belong in the same repository as the code they describe. The conventional location is docs/decisions/ or docs/adr/ at the repository root. Each ADR is a numbered, sequentially-named Markdown file:
docs/
decisions/
001-use-postgresql-as-primary-database.md
002-use-event-sourcing-for-order-domain.md
003-use-rest-over-graphql-for-public-api.md
Why the repository, not a wiki?
ADRs in wikis (Confluence, Notion) are decoupled from the code. They are not subject to code review. They are not versioned with the changes they describe. They are not searchable alongside the codebase. They accumulate link rot.
ADRs in the repository are reviewed in PRs, versioned with git, and visible to any engineer browsing the codebase. They can reference specific commit hashes, file paths, and code that was current when the decision was made.
For organizations with many repositories, a separate architecture repository or monorepo docs/ directory for cross-cutting decisions is appropriate alongside per-service ADR directories.
ADR Status Lifecycle
ADRs are not static documents. They evolve as the system evolves. Managing ADR status is what prevents ADR rot.
Proposed: A decision is being considered and is open for comment. Used in teams that use ADRs as a decision-making tool rather than just a recording tool. Proposed ADRs can be reviewed in PRs before the decision is finalized.
Accepted: The decision has been made and is current. The system should reflect this decision.
Deprecated: The decision is no longer relevant (e.g., the component it described was retired) but is preserved for historical context.
Superseded by [ADR-XXX]: The decision has been replaced by a subsequent decision. The superseding ADR link is included so the history of the decision is traceable.
When an ADR is superseded, do not delete the old ADR. Mark it as superseded with a link to the new one. This preserves the reasoning history — important for audits, postmortems, and understanding why the system evolved the way it did.
Integrating ADRs into the PR Workflow
The PR review process is the most effective enforcement point for ADR requirements. The goal is to make writing an ADR feel like a natural part of shipping significant changes, not a separate obligation.
PR Template Integration
Add an ADR checkbox to your PR template:
## Checklist
- [ ] Tests added/updated
- [ ] Documentation updated
- [ ] **Does this PR make a significant architectural decision? If yes, an ADR is included or linked.**
This prompts authors to consider whether an ADR is warranted without mandating one for every PR.
Code Review Guidelines
Add ADR expectations to your code review standards:
For PRs that introduce new dependencies, change data storage patterns, modify API contracts, or change deployment architecture, reviewers should ask whether an ADR is present or linked. If none exists and the decision is significant, request one before merging.
This connects directly to how teams build effective code review cultures — for a full treatment of code review practices including PR templates and reviewer guidelines, see code review best practices for teams.
Making ADR Review Lightweight
The risk of integrating ADRs into the PR process is adding friction that slows down shipping. Mitigate this by:
- Using the Nygard format (fast to write) for first ADRs
- Allowing "draft" ADRs to be refined after merge for time-sensitive changes
- Making clear that ADRs are for significant decisions — not every PR
Tooling for ADR Management
adr-tools
adr-tools is a command-line tool by Nat Pryce that automates ADR file management. It creates new ADRs with sequential numbering, manages the status links (superseded ADRs link to new ones automatically), and provides basic search.
# Install
brew install adr-tools
# Initialize ADR directory in a project
adr init docs/decisions
# Create a new ADR
adr new "Use PostgreSQL as primary database"
# Creates: docs/decisions/0001-use-postgresql-as-primary-database.md
# Mark ADR-0001 as superseded by a new decision
adr new -s 1 "Use CockroachDB for global distribution"
# Updates ADR-0001 status to Superseded, creates ADR-0002
adr-tools is lightweight, requires no server, and works well for single-repository setups.
log4brains
log4brains is a more modern tool that generates a searchable static website from your ADR Markdown files. It is particularly useful for teams that want to make their ADR log browsable by non-technical stakeholders.
# Install
npm install -g log4brains
# Initialize
log4brains init
# Preview the ADR site
log4brains preview
# Build static site
log4brains build
log4brains supports multi-package repositories (a monorepo with per-package ADRs), generates a browsable history with decision search, and can be deployed to GitHub Pages.
Manual Approach
For teams that want minimal tooling overhead, a simple numbered directory with a consistent naming convention is entirely sufficient. The discipline of writing and reviewing ADRs matters more than the tooling used to manage them.
Create a docs/decisions/README.md as a table of contents and update it when ADRs are added or changed.
Avoiding ADR Rot
ADR rot is the state where the ADR log exists but is no longer accurate or used. It happens when:
- ADRs are written for the initial architecture but never updated as the system evolves
- New engineers don't know ADRs exist
- ADRs reference outdated context that makes them misleading rather than helpful
- The ADR directory becomes a graveyard of "accepted" decisions that were actually superseded by code changes
Preventing ADR Rot
Supersede, don't delete. When a significant architectural decision changes, create a new ADR that supersedes the old one. This maintains history while keeping the current state accurate.
Include ADRs in onboarding. Every engineering onboarding should include: "Read the ADR directory. It explains why the system looks the way it does." If new engineers don't know ADRs exist, they can't use them.
Quarterly ADR review. Once per quarter (or after major architecture changes), review the ADR directory and update statuses. This takes one hour and prevents months of confusion.
ADR as part of incident postmortem. When an incident postmortem reveals that a system decision contributed to the incident, that decision should either have an existing ADR updated or generate a new ADR explaining the current state and the path forward.
Link ADRs from code. In files that are directly shaped by an ADR decision, add a comment linking to the relevant ADR. This makes the connection between decision and implementation explicit.
# See docs/decisions/0003-use-event-sourcing-for-order-domain.md
# for the rationale behind this command handler pattern
class CreateOrderCommandHandler:
...
ADRs and Team Process
ADRs integrate naturally with other engineering practices. They are a natural companion to:
Tech debt management. An ADR for deliberate tech debt documents the trade-off being made and sets the expectation for future paydown. "We are using a synchronous API here for time reasons; the correct long-term architecture is documented in ADR-042."
Code review. Reviewers who understand the ADR context can give better feedback. "This change contradicts ADR-031 — do we need to update the ADR or reconsider the approach?"
Engineering planning. ADRs for architectural migrations provide the context teams need to estimate and plan the work. Rather than debating "why did we build it this way?", the team starts from documented intent.
For teams using structured project management, the relationship between ADRs and sprint planning connects to how engineering teams balance feature work with architectural work — a challenge covered in detail in agile vs waterfall methodologies.
Onboarding. ADRs are one of the most valuable onboarding resources available. New engineers who read the ADR log arrive at the codebase with context that previously required months of informal knowledge transfer.
Architecture reviews. When presenting architectural changes to peers or leadership, ADRs provide a structured artifact for the discussion. "Here is ADR-055 describing the proposed migration from our current authentication system to the new one" is far more productive than presenting slides.
Common ADR Anti-Patterns
The BDUF ADR. Writing ADRs as big upfront design documents that attempt to predict all future consequences. ADRs should document decisions, not replace design thinking. The decision context should be concise enough to re-read in 5 minutes.
ADRs as approval tickets. Requiring an ADR review and sign-off process that gates every architectural change. ADRs are documentation, not bureaucracy. The review of a proposed ADR can be lightweight — a PR review, not a committee meeting.
ADRs only for major decisions. If the bar for "requires an ADR" is set too high, minor-but-significant decisions go unrecorded. The Nygard format is intentionally low-overhead precisely to lower the bar for writing.
The update trap. Updating an accepted ADR to reflect a changed decision rather than creating a new superseding ADR. This loses the history of the change and makes the ADR log harder to audit.
ADRs in the wrong place. ADRs in a wiki, a Google Drive folder, or a separate system from the code are ADRs that will be forgotten. The repository is the right place.
ADRs in the Context of Engineering Culture
A team that writes ADRs consistently is a team that has internalized certain cultural values: that the "why" is as important as the "what," that future engineers deserve context, and that decisions should be deliberate and documented rather than implicit and tribal. This is one dimension of the broader engineering culture work described in engineering culture: building high-performing teams.
The teams that do ADRs best are usually the same teams that do blameless postmortems well — they have internalized that transparency and documentation serve the team, not just the individual.
Measuring ADR Effectiveness
How do you know your ADR practice is working? A few signals:
- New engineers cite ADRs when asked how they understood architectural decisions
- Code review discussions reference ADR numbers ("does this align with ADR-023?")
- Incidents reveal fewer "we didn't know why it was built this way" root causes
- Architecture discussions are shorter because context is documented, not reconstructed
Methodology
This guide draws on Michael Nygard's original ADR formulation (2011), the MADR specification (Olaf Zimmermann et al., 2019), the adr-tools project documentation (Nat Pryce), the log4brains project documentation, and analysis of ADR practices at engineering organizations of various sizes. The format comparisons are based on practitioner experience and community discussion in engineering forums including the Software Architecture community on LinkedIn and the Architecture as Code community.