Architecture Decision Records (ADRs)

What it is

An Architecture Decision Record (ADR) is a short, structured document — typically one to two pages — that captures a single significant architectural decision. The term was popularized by Michael Nygard in 2011. An ADR records the context that made a decision necessary, the decision itself, and the consequences — both positive and negative — of that choice. Unlike heavyweight architecture documents, ADRs are intentionally small and live next to the code in version control.

The key insight is that the most valuable part of a decision record is not the decision itself — it is the context that made the decision appropriate at the time. Teams six months later who encounter a peculiar architectural choice and ask "why on earth did we do this?" need context more than they need a summary of what was decided. ADRs provide that context in a durable, discoverable format.

Why it exists

Architectural decisions decay invisibly. The engineers who made a decision leave, business context changes, and new team members reverse decisions without understanding why they were originally made — often reintroducing bugs or scaling problems that the original decision was designed to avoid. ADRs are the antidote to architectural amnesia. They make the institutional memory of the architecture explicit, versioned, and searchable.

ADRs also improve the quality of decisions at the time they are made. The discipline of writing down context, options considered, and rationale forces a level of clarity and rigor that verbal discussions do not. Teams that adopt ADRs often find that the act of writing the record surfaces unconsidered alternatives or unconvincing rationale before the decision is finalized.

When to use

• Any decision that is architecturally significant — meaning it would be costly or difficult to reverse.
• Technology selections: choice of database, message broker, programming language, cloud provider.
• Structural decisions: service boundaries, communication patterns, data ownership.
• When overriding an existing architecture principle or accepted convention — the deviation must be explained.
• When rejecting a widely used pattern in favor of something simpler or domain-specific.

When not to use

• Do not write ADRs for implementation details that do not affect the system's structure or quality attributes (e.g., variable naming conventions, internal algorithm choices).
• Do not write ADRs for decisions that are trivially reversible with low cost.
• Do not let ADRs replace design documents for complex features that require detailed specification — they are complementary, not substitutes.

Typical architecture

ADRs are stored as numbered Markdown files in a docs/decisions/ directory at the root of the repository. Each file is immutable once accepted — changes are made by superseding an ADR with a new one, not by editing the original. This preserves the historical record of when and why decisions changed.

project-root/
└── docs/
    └── decisions/
        ├── 0001-use-postgresql-as-primary-store.md    [Accepted]
        ├── 0002-use-kafka-for-event-streaming.md      [Accepted]
        ├── 0003-adopt-hexagonal-architecture.md       [Accepted]
        ├── 0004-replace-rest-with-grpc-internal.md    [Proposed]
        └── 0005-migrate-to-aurora-serverless.md       [Supersedes 0001]

ADR Anatomy (MADR format):
──────────────────────────
# ADR-0002: Use Kafka for Event Streaming

## Status
Accepted

## Context
Services need to communicate state changes without tight coupling.
We evaluated RabbitMQ, ActiveMQ, and Kafka.

## Decision
We will use Apache Kafka as our primary event streaming platform.

## Consequences
+ Supports high-throughput, replay, and multiple consumer groups.
+ Decouples producers from consumers.
- Operational complexity: requires Zookeeper/KRaft cluster management.
- Team needs to learn Kafka consumer group semantics.
- Higher latency than direct RPC for low-volume synchronous flows.
          

Pros and cons

Implementation notes

MADR format: Michael Nygard's original format (Context, Decision, Consequences) is the simplest starting point. The Markdown Architectural Decision Records (MADR) format adds optional sections for considered options and a pros/cons analysis of each. For most teams, a five-section template — Title, Status, Context, Decision, Consequences — is sufficient. Resist the urge to add sections until you feel the pain of not having them.

ADR lifecycle and states: A proposed ADR is open for comment. An accepted ADR is binding until superseded or deprecated. A deprecated ADR was accepted but is no longer applicable (e.g., the system it governed has been decommissioned). A superseded ADR was replaced by a later decision — it is never deleted, only marked superseded with a reference to the new ADR. This history is invaluable when auditing why the system evolved as it did.

Tooling: adr-tools (by Nat Pryce) is a CLI that automates numbering and superseding. log4brains provides a web UI for browsing ADRs with timeline, status filtering, and full-text search. Both are useful at scale; at small scale, a simple naming convention and a README index is sufficient.

When to write an ADR: A useful heuristic is the "reversibility test" — if undoing this decision would require more than one sprint of work, write an ADR. Another useful trigger is team disagreement: if two or more engineers have meaningfully different opinions about a decision, the act of writing an ADR surfaces the disagreement and forces resolution.

Common failure modes

• Post-hoc rationalization: Writing an ADR after the decision is implemented, producing a document that justifies rather than explains.
• Stale ADRs with no curation: Accepted ADRs that are no longer relevant but are never deprecated, misleading future readers.
• Missing context: Documenting what was decided but not the constraints and pressures that made it the right decision at the time.
• Too few ADRs: Reserving ADRs for only the biggest decisions, leaving many medium-sized choices undocumented.
• Not in version control: ADRs stored in a wiki or shared drive become disconnected from the code and are eventually abandoned.

Decision checklist

• Is the decision architecturally significant — would reversing it cost more than one sprint?
• Does the ADR document the context (constraints, forces, requirements) that made the decision necessary?
• Does it list at least two or three options that were considered, including the option to do nothing?
• Are the consequences listed honestly — both the benefits and the costs accepted?
• Is the ADR stored in the repository's version control under a consistent path (e.g., docs/decisions/)?
• Is there a clear status (Proposed / Accepted / Deprecated / Superseded)?
• Has the ADR been reviewed by at least one other engineer or architect before being accepted?
• If this decision supersedes a previous one, does it reference the prior ADR by number?

Example use cases

• A startup documents its choice of a monolithic architecture over microservices in an ADR, explicitly noting the team size constraint (8 engineers) and the plan to revisit at 30 engineers.
• A regulated fintech maintains an ADR index as evidence for compliance auditors that architectural decisions affecting data residency were made deliberately with documented rationale.
• A platform team uses ADR status to communicate to consuming teams which platform decisions are final vs still open for input (Proposed vs Accepted).

Related patterns

• Architectural Trade-off Analysis — the analysis that feeds into an ADR's options and rationale sections.
• Architecture Principles — ADRs can reference the principles they apply or override.
• Reference Architectures — ADRs can document deviations from a reference architecture and the reasons for them.

Further reading

• Documenting Architecture Decisions — Michael Nygard — the original blog post that introduced ADRs.
• MADR: Markdown Architectural Decision Records — the most widely adopted ADR template format.
• adr-tools — Nat Pryce — CLI tooling for managing ADR files.