Architecture Decision Record (ADR) Template

Last updated:

What it is

An Architecture Decision Record (ADR) is a short document that captures a single significant architectural decision made during the design or evolution of a software system. Each ADR records the context in which a decision was made, the decision itself, and the consequences that follow from it — both the benefits and the trade-offs accepted.

ADRs were popularized by Michael Nygard and have since become a standard practice in teams that value architectural transparency. They live close to the code — typically in a docs/adr/ or decisions/ directory within the repository — so they age alongside the system they describe. Each ADR is immutable once accepted: rather than editing an old record, a new one supersedes it, preserving the full decision history.

The term "architecture decision" is intentionally broad. It includes choices about frameworks, patterns, infrastructure, data models, communication protocols, and any other technical direction whose rationale is worth preserving for future maintainers and stakeholders.

Why it exists

Software systems accumulate decisions invisibly. A year after a choice is made, the engineers who made it may have moved on, the original constraints may have changed, and the codebase may carry the consequences without anyone knowing why. ADRs are an antidote to this institutional amnesia. They make the reasoning behind a design explicit and durable, allowing teams to distinguish between "we designed it this way intentionally" and "nobody knows why this is here."

ADRs also improve decision quality at the moment of writing. The discipline of articulating the context, the options considered, and the trade-offs accepted tends to surface unstated assumptions and gaps in reasoning before a decision is locked in. Teams that write ADRs regularly report fewer "why did we do this?" post-mortems and faster onboarding of new engineers.

Finally, ADRs support reversibility awareness. By explicitly recording the status of a decision (Proposed, Accepted, Deprecated, Superseded), teams can track which decisions are still valid, which have been revisited, and which are candidates for re-evaluation as the system evolves.

When to use

  • When choosing between meaningfully different technical approaches (e.g., REST vs. gRPC, SQL vs. NoSQL, monolith vs. microservices) where the trade-offs will affect the team for months or years.
  • When adopting a new framework, library, or platform dependency that becomes a first-class architectural constraint.
  • When establishing a cross-cutting convention — such as a logging strategy, authentication pattern, or error-handling approach — that all teams must follow.
  • When consciously accepting a known limitation or technical debt with a justification that future engineers need to understand.
  • When a significant decision was made implicitly and needs to be documented retroactively to avoid confusion or re-litigation.

When NOT to use

  • For routine implementation details that have no lasting architectural impact (e.g., variable naming, minor refactoring, choosing a utility method).
  • As a substitute for a full design document when the decision requires extensive background, multi-component diagrams, or detailed API specifications — use a Design Doc instead.
  • For decisions that are easily reversible and carry no meaningful trade-off, where the overhead of documentation exceeds the value of recording it.
  • As a meeting minutes replacement — ADRs capture decisions, not discussions. Use separate meeting notes for that purpose.

Template

# ADR-[NUMBER]: [Short imperative title — e.g., "Use PostgreSQL as the primary datastore"]

## Date
[YYYY-MM-DD]

## Status

Proposed

## Deciders

- [Name / Role]
- [Name / Role]

## Context and Problem Statement

[2–4 sentences describing context and the problem being solved]

## Decision Drivers

* [Driver 1 — e.g., Must support horizontal scaling with no shared state]
* [Driver 2 — e.g., Team has existing expertise in X]
* [Driver 3 — e.g., Must be deployable on our existing Kubernetes cluster]
* [Driver 4 — e.g., Licensing must be compatible with our open-source policy]

## Considered Options

* [Option A — name only here]
* [Option B — name only here]
* [Option C — name only here]

## Decision Outcome

Chosen option: **[Option A]**, because [concise justification referencing the decision drivers].

### Positive Consequences
* [Benefit 1]
* [Benefit 2]
* [Benefit 3]

### Negative Consequences / Trade-offs Accepted
* [Trade-off 1]
* [Trade-off 2]

## Pros and Cons of the Options

### [Option A]
**Pro:** [Advantage]
**Pro:** [Advantage]
**Con:** [Disadvantage]
**Con:** [Disadvantage]

### [Option B]
**Pro:** [Advantage]
**Pro:** [Advantage]
**Con:** [Disadvantage]
**Con:** [Disadvantage]

### [Option C]
**Pro:** [Advantage]
**Con:** [Disadvantage]
**Con:** [Disadvantage]

## Links

* Supersedes: [ADR-NNN link if applicable]
* Superseded by: [ADR-NNN link if applicable]
* Related: [ADR-NNN — title]
* Reference: [URL or document title]

---


# ADR-0042: Use Kafka for Asynchronous Event Streaming

## Date
2024-11-15

## Status
Accepted

## Deciders
- Alice Chen (Staff Engineer)
- Bob Martins (Platform Lead)
- Carol Davis (Engineering Manager)

## Context and Problem Statement
The Order Service currently calls the Inventory Service and Notification Service
synchronously during checkout. This creates tight coupling, increases p99 latency
during peak load (observed 1,800ms at 95th percentile), and causes cascading failures
when downstream services are degraded. We need to decouple these integrations using
an asynchronous messaging layer.

## Decision Drivers
* Must tolerate transient failures in downstream services without impacting checkout
* Must support at-least-once delivery with consumer-side idempotency
* Must support replay of past events for new consumers and disaster recovery
* Team has existing operational expertise in Kafka on our GKE cluster

## Considered Options
* Apache Kafka (managed via Confluent Cloud)
* RabbitMQ (self-hosted)
* AWS SQS + SNS (cloud-native)

## Decision Outcome
Chosen option: **Apache Kafka via Confluent Cloud**, because it best satisfies the
replay and at-least-once delivery requirements, and the team already operates Kafka
for the analytics pipeline, reducing operational overhead.

### Positive Consequences
* Checkout is fully decoupled from Inventory and Notification services
* Events can be replayed for new consumers or incident recovery
* Confluent Cloud handles broker scaling and patching

### Negative Consequences / Trade-offs Accepted
* Additional cost: ~$800/month for Confluent Cloud
* Consumers must implement idempotency — added development effort

## Links
* Related: ADR-0038 — Event-Driven Architecture for Order Pipeline
* Reference: https://www.confluent.io/blog/kafka-fastest-messaging-system/

Pros and cons

Benefits

  • Creates a permanent, version-controlled record of architectural reasoning that survives team turnover.
  • Improves decision quality by forcing explicit articulation of options and trade-offs before committing.
  • Dramatically reduces onboarding time for new engineers who need to understand why the system is built the way it is.
  • Provides a clear audit trail for compliance, security reviews, and architectural assessments.

Pitfalls

  • ADR drift: decisions get implemented but ADRs are never updated to "Accepted," making the index unreliable.
  • Over-documentation: teams write ADRs for trivial decisions, devaluing the signal-to-noise ratio of the ADR log.
  • Retrospective writing without honest trade-off capture, producing advocacy documents rather than decision records.
  • Not linking related ADRs, leaving readers unable to trace the evolution of a decision over time.

Writing guidance

The most valuable part of an ADR is the Context and Problem Statement. Write it as a factual description of the situation, not as justification for the outcome. A reader unfamiliar with the system should be able to understand what problem existed and why action was needed. Use concrete numbers (latency, error rates, team size, cost) wherever possible — vague problem statements produce vague decisions.

The Decision Drivers section is your evaluation rubric. Write it before you evaluate options, not after. If you find yourself adding drivers retroactively to justify a preferred option, that is a sign the decision has already been made and you are rationalizing rather than deciding. Keep drivers measurable or at least falsifiable: "must support 10k req/s" is better than "must be performant."

Keep the document short. A good ADR fits on one to two pages. If you find yourself writing five paragraphs about an option, consider whether a separate Design Doc is warranted and reference it from the ADR. The ADR captures the decision; the design doc captures the detailed analysis. Number your ADRs sequentially within each repository and name the files to match (e.g., 0042-use-kafka-for-event-streaming.md) so they sort chronologically in any file browser.

Common mistakes

  • Writing the ADR after the decision is irreversible: ADRs written purely retroactively often omit the real reasons for a decision and capture only the polished justification, losing the nuance that makes them useful.
  • Listing only one option: An ADR with a single option is not a decision record — it is an announcement. Always document at least two serious alternatives, even when the choice seems obvious.
  • Conflating status with quality: "Accepted" means the team agreed to it, not that it was the optimal choice. Be honest about accepted trade-offs in the Negative Consequences section.
  • No ownership: ADRs without named Deciders become orphaned documents. If there are no named individuals, it is unclear who has the authority to supersede or deprecate the record.

Review checklist

  • Does the Context section describe the problem factually without advocating for a solution?
  • Are at least two meaningfully different options documented with honest pros and cons?
  • Do the Decision Drivers map clearly to the outcome — can a reader trace why the chosen option wins?
  • Are accepted trade-offs explicitly called out in Negative Consequences?
  • Is the ADR cross-linked to related ADRs, design docs, or tickets that informed the decision?

Example usage

  • Database selection: A team writes ADR-0012 to document the choice of PostgreSQL over MongoDB for a new service, recording that the team prioritized ACID transactions over flexible schema evolution given the financial nature of the data.
  • Framework adoption: After evaluating React, Vue, and Svelte, a platform team writes ADR-0028 choosing React for the design system, citing the existing team expertise and component library ecosystem as the primary drivers.
  • Supersession: Two years later, ADR-0071 supersedes ADR-0012, documenting the decision to migrate from PostgreSQL to CockroachDB after the service scaled to multi-region requirements that the original decision explicitly deferred.

Further reading