Architecture Decision Record (ADR)
An Architecture Decision Record (ADR) is a short document that captures one significant architecture decision: the situation that prompted it, the choice the team made and the consequences it accepted. ADRs are numbered, kept in sequence alongside the code and not rewritten, so anyone joining later can see why the system is built the way it is.
How Architecture Decision Records Work
Michael Nygard proposed the format in a 2011 blog post, "Documenting Architecture Decisions." His template has a few short sections:
- Title: a short noun phrase, such as "ADR 7: Use PostgreSQL for event storage."
- Status: proposed, accepted, deprecated or superseded.
- Context: the forces at play, including technical, business and team constraints, described neutrally.
- Decision: the response, written in full sentences and active voice ("We will...").
- Consequences: everything that follows from the decision, good and bad.
Nygard recommended keeping each record to one or two pages, storing records in the project repository (for example as doc/arch/adr-NNN.md) in a lightweight markup language such as Markdown, and numbering them sequentially without reusing numbers. When a decision changes, the team does not edit the old record. It writes a new one and marks the earlier ADR as superseded, so the history of reasoning stays intact.
Not every choice needs an ADR. Nygard reserves them for architecturally significant decisions: those that affect structure, non-functional characteristics, dependencies, interfaces or construction techniques.
Why Architecture Decision Records Matter
Without a record, teams lose the reasons behind their architecture. New developers either accept a past decision blindly or reverse it without knowing what it protected against. ADRs give product and engineering a shared, durable source of truth for technical rationale, which makes it easier to revisit a choice when scale, cost or compliance needs shift.
They are also useful when an AI coding agent works in the codebase. An agent that can read the ADR folder is less likely to "fix" a deliberate choice, such as reintroducing a library the team removed for licensing reasons. The same idea applies beyond architecture: decision traceability for product teams covers how to preserve the rationale, alternatives and revisit conditions behind feature approvals.
Architecture Decision Record Example
"ADR 12: Use a managed queue for email delivery. Status: Accepted. Context: Sending confirmation emails inside the web request slows checkout and fails when the email provider is slow. Nobody on the team has time to run a message broker. Decision: We will publish email jobs to our cloud provider's managed queue and process them with a background worker. Consequences: Checkout no longer waits for email. Emails may arrive a few seconds late. We depend on the provider's queue service and its pricing."
ADR vs. Design Document
A design document describes how a system or feature should be built, often before work starts, and is updated as the design evolves. An ADR records a single decision and its reasoning at a point in time, and is not edited once accepted. Teams often use both: the design document proposes, and ADRs capture the decisions that come out of it.