Architecture Decision Records (ADRs): The Complete Guide

Every engineering team makes hundreds of architectural decisions over the course of a project. Which database to use. How to handle authentication. Whether to build a monolith or microservices. What message broker to adopt. These decisions shape the system for years — but in most teams, the reasoning behind them lives only in the heads of the people who made them.

When those people leave, the knowledge walks out the door. New team members inherit a system full of choices they do not understand, and they either blindly accept the status quo or, worse, reverse good decisions because they do not understand the context. Architecture Decision Records solve this problem elegantly. After implementing them in every team I have led over the past 15 years, I can confidently say they are one of the highest-ROI practices in software engineering.

What Are Architecture Decision Records?

An Architecture Decision Record (ADR) is a short document that captures a significant architectural decision along with its context and consequences. The concept was popularized by Michael Nygard in 2011, and it has since become a standard practice in mature engineering organizations.

Each ADR typically contains:

• Title: A short description of the decision
• Status: Proposed, Accepted, Deprecated, or Superseded
• Context: The forces at play, including technical, business, and organizational constraints
• Decision: The decision itself, stated clearly
• Consequences: What will happen as a result of this decision, including both positive and negative outcomes

The beauty of ADRs is their simplicity. They are not 50-page design documents that nobody reads. They are short, focused, and written in plain language. A good ADR takes 15-30 minutes to write and saves hundreds of hours of future debate and confusion.

Why ADRs Matter More Than You Think

ADRs address several critical problems in software engineering:

They Preserve Institutional Knowledge

When a senior engineer who designed the event-driven architecture leaves, the team does not lose the "why." The ADR explains the constraints that existed, the alternatives considered, and the reasons the current approach was chosen. This prevents new team members from re-litigating settled decisions or making changes that reintroduce problems the original design solved.

They Improve Decision Quality

The act of writing down your reasoning forces you to think more carefully. Vague intuitions become concrete arguments. Unconsidered trade-offs surface. I have seen many decisions change during the writing process because the author realized their initial reasoning did not hold up when articulated clearly.

They Reduce Decision Fatigue

Without ADRs, the same debates recur every few months. "Why are we using PostgreSQL instead of MongoDB?" "Why did we choose gRPC over REST?" With ADRs, you can point to the documented reasoning. If the context has changed, great — write a new ADR that supersedes the old one. If not, the decision stands.

They Enable Asynchronous Decision-Making

ADRs can be reviewed as pull requests, commented on asynchronously, and approved without requiring everyone to be in the same room. This is especially valuable for distributed teams.

They Build Team Alignment

When the entire team participates in reviewing ADRs, everyone understands the technical direction. There are no "shadow architectures" or decisions made in hallway conversations that half the team never heard about.

When to Write an ADR

Not every decision needs an ADR. Writing ADRs for trivial choices creates bureaucracy without value. Here is a simple heuristic:

Write an ADR when:

• The decision affects the structure of the system (new services, databases, frameworks)
• The decision is hard to reverse without significant effort
• The decision involves trade-offs that are not immediately obvious
• Multiple team members have different opinions about the right approach
• The decision will affect other teams or systems
• You find yourself explaining the same decision to new team members repeatedly

Skip the ADR when:

• The decision is easily reversible (e.g., choosing a utility library)
• The decision follows an established pattern or standard
• The scope is limited to a single function or module
• The team is in full agreement and the reasoning is straightforward

The ADR Template

After years of refinement, here is the template I recommend. It balances completeness with brevity:

# ADR-{number}: {Title}

## Status
{Proposed | Accepted | Deprecated | Superseded by ADR-xxx}

## Date
{YYYY-MM-DD}

## Context
What is the issue that we are seeing that is motivating this decision
or change? What forces are at play (technical, business, organizational)?

## Decision
What is the change that we are proposing and/or doing?
State the decision clearly and concisely.

## Alternatives Considered
What other options were evaluated? Why were they rejected?

### Alternative 1: {Name}
- Pros: ...
- Cons: ...
- Why rejected: ...

### Alternative 2: {Name}
- Pros: ...
- Cons: ...
- Why rejected: ...

## Consequences

### Positive
- What becomes easier or possible?

### Negative
- What becomes harder?
- What are the risks?

### Neutral
- What other changes are required?

## References
- Links to relevant documents, discussions, or research

This template is intentionally simple. You can extend it with additional sections like "Compliance Considerations" or "Security Impact" if your organization requires them, but start simple and add complexity only when needed.

Real-World ADR Examples

Example 1: Database Selection

# ADR-007: Use PostgreSQL as Primary Data Store

## Status
Accepted

## Date
2024-11-15

## Context
Our application needs a primary data store for user data, transactions,
and product catalog. We expect 100K users in year one, growing to 1M
by year three. We need ACID transactions for payment processing.
Our team has strong SQL experience but limited NoSQL experience.

## Decision
We will use PostgreSQL 16 as our primary data store, hosted on
AWS RDS with read replicas.

## Alternatives Considered

### MongoDB
- Pros: Flexible schema, good for rapid prototyping
- Cons: Weaker transaction support, team lacks experience
- Why rejected: ACID requirements for payments, team skill gap

### CockroachDB
- Pros: Distributed SQL, horizontal scaling
- Cons: Higher operational complexity, smaller community
- Why rejected: Over-engineered for our current scale

## Consequences
### Positive
- Team can leverage existing SQL expertise
- Strong ACID guarantees for payment processing
- Excellent tooling and community support
### Negative
- May need sharding strategy if we exceed vertical scaling limits
- Schema migrations require more discipline than NoSQL
### Neutral
- Need to set up connection pooling (PgBouncer)
- Will use Flyway for migration management

Example 2: Communication Pattern

# ADR-012: Adopt Event-Driven Architecture for Order Processing

## Status
Accepted

## Date
2024-12-03

## Context
Order processing currently uses synchronous REST calls between services.
As we add more downstream consumers (notifications, analytics, inventory),
each new consumer requires changes to the order service. Latency is
increasing as the chain of synchronous calls grows.

## Decision
We will adopt an event-driven architecture using Amazon EventBridge
for order lifecycle events. The order service will publish events;
downstream services will subscribe independently.

## Alternatives Considered

### Keep synchronous REST with circuit breakers
- Pros: Simpler mental model, existing infrastructure
- Cons: Does not solve the coupling problem
- Why rejected: Coupling will continue to increase with each consumer

### Apache Kafka
- Pros: High throughput, replay capability
- Cons: Significant operational overhead for our team size
- Why rejected: Over-engineered for current message volume

## Consequences
### Positive
- New consumers can subscribe without modifying the order service
- Improved resilience (failures are isolated)
- Natural audit trail through event history
### Negative
- Eventual consistency requires careful handling in the UI
- Debugging distributed events is harder than tracing REST calls
- Team needs training on event-driven patterns
### Neutral
- Need to define event schema standards
- Will adopt CloudEvents specification for event format

Where to Store ADRs

The most effective approach I have seen is storing ADRs in the code repository alongside the code they affect. This has several advantages:

• Versioning: ADRs are version-controlled just like code
• Discoverability: Developers find ADRs when they are exploring the codebase
• Review process: ADRs can go through the same PR review process as code
• Proximity: The decision is near the code it affects

Create a docs/adr/ directory in your repository. Name files with a sequential number: 0001-use-postgresql.md, 0002-adopt-event-driven-architecture.md, etc. Include an index.md file that lists all ADRs with their status for quick reference.

For organizations with multiple repositories, consider a central ADR repository for decisions that span systems, and local ADRs for decisions specific to a single service.

How to Introduce ADRs to Your Team

Introducing any new practice requires a careful approach. Here is the playbook I have used successfully across multiple teams:

Step 1: Lead by Example

Write the first 3-5 ADRs yourself. Choose decisions that the team regularly debates or that new members always ask about. Show, do not tell.

Step 2: Show the Value

The next time a team member asks "why did we choose X?", point them to the ADR. The next time a debate resurfaces, reference the documented reasoning. Let the value demonstrate itself.

Step 3: Make It Easy

Create a template in the repository. Add a script or alias that generates a new ADR file with the template pre-filled. Remove friction wherever possible. If writing an ADR takes more than 30 minutes, the process is too heavy.

Step 4: Integrate with Existing Workflows

Make ADRs part of the PR process for significant changes. If someone proposes a new dependency, framework, or architectural change, an ADR should accompany the code. But be careful not to make this a blocker for small changes — only significant architectural decisions need ADRs.

Step 5: Celebrate and Iterate

Acknowledge team members who write good ADRs. Share particularly well-written ones in team meetings. Ask for feedback on the template and process, and refine based on what the team finds useful.

In the First Lead course, we go deeper into change management strategies for introducing engineering practices like ADRs, including how to handle resistance from team members who see documentation as "waste."

ADR Governance and Lifecycle

ADRs are living documents with a clear lifecycle:

Proposed: The ADR is drafted and open for discussion. This is the state during the PR review process. Team members can comment, suggest alternatives, or raise concerns.

Accepted: The team has agreed on the decision. The ADR is merged and becomes the authoritative reference for this decision.

Deprecated: The decision is no longer relevant — perhaps the system it applied to has been decommissioned. The ADR remains for historical context but is marked as deprecated.

Superseded: A new ADR has replaced this one. Link to the new ADR so readers can follow the evolution. Never delete old ADRs — they provide valuable historical context about how the system evolved.

Who Approves ADRs?

This depends on the scope of the decision:

• Team-scoped decisions: The tech lead and at least one senior engineer review and approve.
• Cross-team decisions: Relevant tech leads from affected teams review. Consider a lightweight architecture review board for very high-impact decisions.
• Organization-wide decisions: Principal engineers, architects, or a formal architecture council.

Keep the approval process proportional to the decision's impact. Over-governance kills adoption.

Common Mistakes and How to Avoid Them

• Writing ADRs after the fact: An ADR written months after a decision misses the context and alternatives. Write them when the decision is being made.
• Making ADRs too long: If your ADR is more than two pages, you are writing a design document. ADRs capture the decision and reasoning, not every implementation detail.
• Not documenting rejected alternatives: The alternatives you considered and why you rejected them are often more valuable than the decision itself. They prevent future teams from re-evaluating the same options.
• Treating ADRs as immutable law: ADRs document decisions in a specific context. When the context changes, the decision should be revisited. Create a new ADR that supersedes the old one.
• Requiring ADRs for everything: This creates process fatigue and kills adoption. Reserve ADRs for decisions that are significant and hard to reverse.
• Ignoring consequences: The consequences section is where much of the value lies. Be honest about the negative consequences — they help future teams understand the trade-offs and anticipate challenges.

Advanced ADR Practices

Once your team has established a solid ADR practice, consider these advanced techniques:

ADR Radar

Maintain a quarterly review of all active ADRs. Are the contexts still valid? Have consequences materialized that were not anticipated? This proactive review catches decisions that need updating before they cause problems.

Decision Logs

Create a lightweight decision log for smaller decisions that do not warrant full ADRs — a simple table with the decision, date, and brief rationale. This fills the gap between "no documentation" and "full ADR."

Cross-Reference with Code

Reference ADR numbers in code comments where relevant architectural decisions are implemented. For example: // See ADR-012: Event-driven architecture for order processing. This creates a bidirectional link between decisions and implementation.

ADR Metrics

Track how often ADRs are referenced (through git blame, searches, or link tracking). This helps you understand which ADRs are providing value and which topics generate the most questions.

Onboarding with ADRs

Include a curated set of ADRs in your onboarding materials. New team members who read the key architectural decisions ramp up significantly faster because they understand not just what was built, but why.

"The best documentation is the documentation that gets used. ADRs succeed because they are short, focused, and answer the one question engineers ask most often: 'Why did we build it this way?'"