How to Write an Architecture Decision Record (ADR)

Architecture decisions are some of the most consequential choices made in a software project. Yet they are often documented poorly — or not at all. Architecture Decision Records (ADRs) are a lightweight, structured way to record why a significant architectural choice was made, what alternatives were considered, and what trade-offs were accepted. This guide explains how to write effective ADRs in clear technical English.

What Is an ADR?

An Architecture Decision Record is a short document that captures a significant architectural decision along with its context and consequences. ADRs were popularised by Michael Nygard and are widely adopted in engineering teams as part of a “decisions-as-code” or “decisions-in-repo” practice.

ADRs answer three questions:

1. What was the situation when this decision was made?
2. What did we decide?
3. What are the expected consequences?

Standard ADR Structure

The most widely used ADR format includes the following sections:

Title

A short, descriptive title using a decision-focused format:

“ADR-007: Use PostgreSQL as the primary database” “ADR-014: Adopt event sourcing for the order domain”

Number your ADRs sequentially. Once written, the number and title should never change — even if the decision is later superseded.

Status

One of: Proposed, Accepted, Deprecated, or Superseded by ADR-XXX.

“Status: Accepted (2026-03-15)“

Context

Describe the situation that made this decision necessary. What constraints existed? What problem were you solving? Who was affected?

“Our monolithic application has reached a point where multiple teams are deploying to the same codebase. Deployment conflicts and long review queues are slowing delivery. We need to decide whether to decompose the application into separate deployable units.”

This section should be factual and specific, not opinionated. Save your opinion for the Decision section.

Decision

State clearly what was decided. Use active voice and direct language.

“We will adopt a service-per-domain architecture, starting with the Order and User domains. Each domain will have its own repository, database, and deployment pipeline.”

Consequences

List the expected results — both positive and negative. Good ADRs do not hide trade-offs.

“Positive consequences: - Teams can deploy independently, removing cross-team deployment dependencies. - Domain boundaries will be explicit, reducing accidental coupling.

Negative consequences: - Cross-domain queries will require API calls or event-based data synchronisation, adding complexity. - We will need to invest in service discovery, distributed tracing, and inter-service authentication.”

Full ADR Template

# ADR-[number]: [Short title of the decision]

**Date:** YYYY-MM-DD
**Status:** Proposed | Accepted | Deprecated | Superseded by ADR-XXX
**Deciders:** [List of people involved in the decision]

## Context

[Describe the situation, constraints, and the problem that prompted this decision.]

## Decision

[State clearly what was decided and why.]

## Consequences

### Positive
- [Expected benefit]
- [Expected benefit]

### Negative
- [Known trade-off]
- [Known trade-off]

## Alternatives Considered

[Briefly describe alternatives and why they were not chosen.]

Common Mistakes to Avoid

Writing the Decision as a Problem Statement

Wrong:

“We need to decide how to handle authentication.”

Right:

“We will use JSON Web Tokens (JWTs) for stateless authentication across all services.”

The decision section should state what was decided, not restate the problem.

Hiding Trade-offs

Omitting the negative consequences makes an ADR useless. Future engineers need to understand what trade-offs were knowingly accepted.

“Negative: JWTs cannot be invalidated before they expire without a blocklist, which adds operational complexity for logout and account suspension scenarios.”

Writing ADRs After the Fact Without Acknowledging It

If you are writing an ADR for a decision already implemented, note that:

“Note: This decision was made and implemented in March 2025. This ADR was written retrospectively to document the reasoning.”

Using Vague Language

Avoid phrases like “we should consider” or “it might be good to.” ADRs document decisions, not possibilities.

Practical Phrases for Writing ADRs

• “At the time of this decision, the primary constraint was…”
• “Three alternatives were considered: X, Y, and Z. We chose X because…”
• “This decision introduces a trade-off between simplicity and scalability.”
• “Future teams should be aware that this decision assumes…”
• “If the following assumptions change, this ADR should be revisited: …”
• “This decision supersedes ADR-003, which recommended…”

Where to Store ADRs

The most common convention is to store ADRs in a docs/decisions/ directory within the repository, named NNNN-title-with-hyphens.md. This keeps decisions versioned alongside the code they describe.

Tools like adr-tools automate the creation and linking of ADR files.

ADRs are a form of institutional memory. Without them, teams repeatedly revisit the same decisions, and engineers joining a project cannot understand why things are the way they are. A well-written ADR takes 30 minutes to produce and saves hours of confused archaeology in the future. Make writing them a habit.