How to Write Architecture Decision Records (with a Template)

A five-part template, five habits that keep ADRs useful, and how to tie them to your diagrams

Six months after a team picks a database, someone asks why. If the answer lives in a chat thread nobody can find, the decision gets re-argued, or worse, quietly reversed. An architecture decision record (ADR) is a short document that captures one decision and the reasons for it, kept next to the code so it survives team changes.

The smallest useful template

The widely used format, popularised by Michael Nygard, has five parts:

# 7. Use PostgreSQL for the orders service

Status: accepted

## Context
Orders need transactions across line items and payments. The team already
runs PostgreSQL for billing. Expected volume is under 50 writes per second.

## Decision
We will store orders in PostgreSQL, in the same cluster as billing.

## Consequences
- Easy: one database to operate, joins with billing data.
- Harder: orders and billing now share a failure domain.
- Revisit if write volume grows tenfold.

Title: a short noun phrase, numbered so records sort in order.
Status: proposed, accepted, deprecated or superseded.
Context: the forces at play, in plain language.
Decision: what you chose, in one or two sentences.
Consequences: what becomes easier and what becomes harder. Honest downsides are the most useful part.

Habits that keep ADRs useful

One decision per record. If it has an "and", split it.
Write it when you decide, not weeks later, while the alternatives are still fresh.
Do not edit history. When a decision changes, write a new record and mark the old one superseded, linking both ways.
Keep them in the repository, for example in docs/adr/, so they are reviewed in pull requests and versioned with the code they describe.
Link the record to the picture. A decision about a queue means more next to the diagram that shows the queue.

A decision record points at the part of the architecture it affects

Doing this in Archgram

Archgram Flow (a Pro feature you switch on under Settings → Experimental Features) has a decision record object with a status, the context, the alternatives you weighed and the consequences. You link each record to the diagram nodes it affects, so selecting a node shows the decisions behind it. Records export to Markdown, so they can live in your repository too. If you prefer plain files, the template above works anywhere. See the Flow guide.