Architecture Decision Records: Why You Need Them and How to Write Them

The Problem That ADRs Solve

Here's a scenario that plays out in almost every engineering organization:

Six months after a major architectural decision, a new engineer joins the team. They look at the system and ask why it's built the way it is. Nobody who made the original decision is available — they've changed teams, left the company, or simply don't remember the details of a discussion that happened on a Tuesday afternoon. The codebase reflects the decision, but not the reasoning behind it.

The new engineer, reasonably, looks at the structure and thinks "this doesn't make sense." They propose a change that seems obviously better given the current context. What they don't know — what nobody told them — is that the "obvious" approach was considered and rejected for a specific reason that still applies. The team relitigates a solved problem, sometimes making the same mistake it avoided six months ago.

Architecture Decision Records (ADRs) are the antidote. They capture not just what was decided, but why — the context, the alternatives considered, and the trade-offs accepted. They make architectural decisions a persistent artifact of the project rather than institutional memory that lives only in the heads of the people who were in the room.

What an ADR Is (and Isn't)

An ADR is a short document that captures a significant architectural decision: what was decided, the context that made the decision necessary, the alternatives that were considered, and the consequences — both the benefits and the costs.

It is not:

A design document for the feature itself
A post-mortem or incident review
A proposal for future work
A technical specification

ADRs are narrow by design. Each one covers exactly one decision. They're meant to be written quickly and read quickly. A three-page ADR that takes an hour to write and thirty minutes to read doesn't serve its purpose — the friction is too high and the decision log won't be maintained.

The Format That Actually Gets Used

There are several ADR templates in circulation. After experimenting with most of them, the format I've settled on is a stripped-down version of Michael Nygard's original format:

# ADR-NNNN: Title

**Status:** Proposed | Accepted | Deprecated | Superseded by ADR-XXXX
**Date:** YYYY-MM-DD
**Deciders:** Names or roles of people who made this decision

## Context

What is the situation that makes this decision necessary? What forces are at play — technical constraints, business requirements, team capabilities, organizational structure? What would happen if you didn't make this decision?

## Decision

What was decided? State it clearly and without hedging. "We will use X" not "We might consider X."

## Consequences

What becomes easier because of this decision? What becomes harder? What new problems does it create? What technical debt is being accepted?

## Alternatives Considered

List the alternatives you seriously evaluated. For each, note why it was not chosen. This is often the most valuable part.

The section that gets skipped most often is "Alternatives Considered," and it's the most important one. The alternatives section is what explains the decision to someone who doesn't have your context. "We chose Kafka over RabbitMQ" is less useful than "We chose Kafka over RabbitMQ because we need log replay capability for our audit requirements and the ability to support multiple independent consumers without message deletion — RabbitMQ's queue model would have required significant workarounds for both."

When to Write an ADR

Not every decision needs an ADR. If you did, you'd spend all your time writing documentation instead of building software. The guideline I use: write an ADR for any decision that:

Is expensive to reverse once made
Affects multiple teams or services
Involves non-obvious trade-offs that reasonable engineers might evaluate differently
Would benefit from being explicitly documented for future team members
Involves rejecting a seemingly obvious approach for non-obvious reasons

Practical triggers:

Choosing a database for a new service
Deciding between synchronous and asynchronous communication for a critical flow
Adopting a new framework, language, or platform
Defining an API contract that other teams will consume
Choosing a service decomposition strategy
Deciding how to handle authentication and authorization across services
Any significant security architecture decision

You do not need an ADR for: naming conventions (put those in a style guide), local implementation choices that don't affect interfaces, or decisions that are trivially reversible.

Building a Decision Log That Survives

An ADR written in isolation is useful. An ADR that's part of a maintained decision log is invaluable. The difference is findability and completeness.

Where to Store ADRs

The best place for ADRs is close to the code — typically a docs/decisions/ or decisions/ directory in the repository. This has several advantages:

ADRs are versioned alongside the code they describe
They appear in code searches
Pull requests for code changes can link to or create corresponding ADRs
Engineers encounter them naturally when exploring the codebase

For multi-repository organizations, a central architecture repository or wiki can supplement per-repo ADRs, but the per-repo location should be the primary home for decisions about that service.

Numbering and Naming

Sequential numbering makes ADRs easy to reference: ADR-0001, ADR-0002. File names follow the pattern: ADR-0001-choose-postgresql-for-user-data.md. The number provides ordering; the name provides instant context.

Keeping ADRs Current

ADRs should be immutable once accepted. When a decision is superseded, you don't edit the original — you write a new ADR that explicitly supersedes it. The original remains as a record that the old decision existed and why it's no longer in effect.

Update the status field:

Proposed — under discussion
Accepted — in effect
Deprecated — no longer recommended but not actively replaced
Superseded by ADR-0042 — replaced by a newer decision

An Example ADR

To make this concrete:

# ADR-0014: Use PostgreSQL for the Orders Service

**Status:** Accepted
**Date:** 2026-02-15
**Deciders:** James Ross (Architect), Sarah Chen (Orders Team Lead)

## Context

The Orders service needs a persistent data store for order records, payment state,
and order line items. The service processes approximately 500 order writes per minute
at peak with complex relational queries for order history and reporting.

## Decision

We will use PostgreSQL as the primary data store for the Orders service.

## Consequences

Positive:
- Strong ACID guarantees for financial transactions
- Mature tooling for migrations, backups, and replication
- Support for complex reporting queries without a separate reporting store
- Team has existing operational expertise

Negative:
- Vertical scaling limits will require attention if order volume grows 10x+
- We accept some schema migration overhead compared to document stores

## Alternatives Considered

**MongoDB:** Rejected because our order model is highly relational and the lack of
cross-document transactions would complicate financial consistency guarantees.

**MySQL:** Technically viable, but the team has deeper PostgreSQL expertise and
PostgreSQL's JSON support is superior for order metadata storage.

**DynamoDB:** Rejected because reporting queries across the full order history would
require a secondary data store (e.g., DynamoDB Streams + Redshift), adding operational
complexity without clear throughput benefits at our current scale.

Start Small and Build the Habit

The most common failure mode with ADRs is never starting. Teams think they need a perfect system before they begin, or they think they'll backfill decisions from the past six months before writing new ones.

Don't. Start with the next architectural decision you make. Write the ADR as part of the decision-making process, not after. Put it in the repository. Reference it in the PR. Tell the team where to find it.

After ten ADRs, the habit forms. After fifty, the decision log becomes genuinely useful. After a year, new engineers onboard faster because the reasoning behind the system's design is documented and findable.

It takes less time than you think, and the return is compounding.

If you're building out an architectural documentation practice or want to talk through your decision-making process, I'm happy to help.