What Is an ADR?
An Architecture Decision Record (ADR) is a short document that captures a single architectural decision and its context. Where an RFC is a proposal that solicits feedback before a decision is made, an ADR is a record of a decision that has already been made. ADRs answer the question that every engineer eventually asks when reading legacy code: "Why was it built this way?"
ADRs were popularized by Michael Nygard in his 2011 blog post and have since become a standard practice in mature engineering organizations. They are lightweight, easy to write, and immensely valuable over time.
Why ADRs Matter
- Organizational Memory: Engineers leave, context is lost. ADRs preserve the reasoning behind decisions.
- Onboarding: New engineers can read ADRs to understand why the system is designed the way it is.
- Avoiding Repeated Debates: When a decision has been documented with its rationale, the team does not relitigate it every few months.
- Evolution Tracking: ADRs can supersede previous ADRs, creating a history of how the architecture evolved.
- Accountability: Documenting decisions makes the decision-making process more deliberate and thoughtful.
The ADR Format
ADRs are intentionally short, typically one page or less. The classic format includes four sections:
# ADR-017: Use PostgreSQL as the Primary Database
## Status
Accepted (2026-02-15)
## Context
We are building a new order management system that requires:
- ACID transactions for financial data integrity
- Complex queries with JOINs across multiple tables
- Full-text search for order lookups
- JSON support for flexible product metadata
The team has experience with both PostgreSQL and MongoDB.
Our existing infrastructure runs PostgreSQL for other services.
## Decision
We will use PostgreSQL 16 as the primary database for the
order management system.
We considered:
1. MongoDB - Better for flexible schemas, but we need strong
transactional guarantees. The team is less experienced with
MongoDB operations.
2. MySQL - Viable option, but PostgreSQL's JSON support and
full-text search eliminate the need for a separate search
service. Our existing tooling and monitoring is set up for
PostgreSQL.
## Consequences
### Positive
- Leverages existing team expertise and operational tooling
- Strong transactional guarantees for financial data
- Built-in JSON support avoids a separate document store
- Full-text search reduces need for Elasticsearch
### Negative
- Schema migrations require more planning than a document DB
- Horizontal scaling is more complex than MongoDB sharding
- Must design the schema upfront rather than evolving freely
### Risks
- If we outgrow single-node PostgreSQL, we will need to
evaluate CitusDB or read replicas (estimated 12+ months away
based on current growth projections)ADRs vs RFCs
When to Use Each
| Characteristic | RFC | ADR |
|---|---|---|
| Timing | Before the decision | After the decision |
| Purpose | Propose and solicit feedback | Record and explain a decision |
| Length | 3-7 pages | 0.5-1 page |
| Audience | Reviewers and decision makers | Future engineers and current team |
| Scope | Large, complex changes | Any significant decision |
| Workflow | Draft -> Review -> Accepted/Rejected | Proposed -> Accepted -> Superseded |
In practice, the two complement each other perfectly: large decisions go through the RFC process, and the outcome is captured in an ADR. Smaller decisions that do not warrant a full RFC can still be captured in an ADR for the historical record.
Where to Store ADRs
- In the repository: Store ADRs in a
docs/adr/directory in the relevant repository. This keeps decisions close to the code they affect and ensures they are version-controlled. - Central wiki: For organization-wide decisions that span multiple repositories, a central wiki or documentation site works better.
- Naming convention: Use a sequential numbering scheme:
ADR-001-use-typescript.md,ADR-002-choose-postgresql.md
ADR Lifecycle
ADRs have a lifecycle that reflects how decisions evolve:
- Proposed: The decision is being considered but not yet finalized
- Accepted: The decision has been adopted and is in effect
- Deprecated: The decision is no longer recommended but existing implementations are not required to change
- Superseded: A new ADR has replaced this one. The old ADR links to the new one.
# ADR-023: Migrate from REST to GraphQL for Client APIs
## Status
Accepted (2026-03-01)
Supersedes: ADR-008 (Use REST for all client-facing APIs)
## Context
Our mobile app requires 12 separate REST calls to render the
home screen, leading to high latency and over-fetching. The
frontend team spends significant time aggregating data from
multiple endpoints.
## Decision
New client-facing APIs will use GraphQL via Apollo Server.
Existing REST endpoints remain unchanged until their owning
team migrates them.
## Consequences
- Reduces mobile app network calls from 12 to 1 for home screen
- Requires team training on GraphQL (2-week investment)
- Need to implement rate limiting and query complexity analysis
- Existing REST APIs continue to work; no breaking changesTips for Effective ADRs
- Write the ADR when the decision is made, not months later when context has been forgotten
- Keep them short. If an ADR takes more than 30 minutes to write, it might need to be an RFC instead.
- Include the "what we considered and rejected" context. This is the most valuable part for future readers.
- Do not edit accepted ADRs. If a decision changes, write a new ADR that supersedes the old one.
- Review ADRs during onboarding. New engineers should read all active ADRs in their team's repositories.
Summary
Architecture Decision Records are one of the simplest yet most valuable documentation practices an engineering team can adopt. They are quick to write, easy to maintain, and provide enormous value over time as organizational memory. Start writing ADRs today, even retroactively for recent decisions, and your future team members will thank you.