The one-page note that answers 'why did we build it this way?'

Six months into any project, someone asks a question the code cannot answer: “why are we using this database and not that one?” The person who decided has left, or has forgotten, and the team either guesses or reopens a debate that was already settled once. An Architecture Decision Record (ADR) is the cheap fix: a one-page file, written when you make a significant choice, that says what you decided and why. I only learned the name recently. The habit is one of the clearest marks of someone who has worked on a real team.

Code tells you what, never why

Your codebase is a perfect record of what the project does. It is a terrible record of why it does it that way. The code shows that you use PostgreSQL. It does not show that you argued about it for a week, nearly chose a document database, and picked PostgreSQL because you needed real transactions. That reasoning lives only in someone’s head, or in a chat message that scrolled away a year ago.

Git does not save you here either. A commit shows what changed, line by line, but the message rarely captures the direction behind it. “Add user table” tells you nothing about why the whole data model looks the way it does.

Picture renovating a house. You knock through a wall and leave a small note taped inside the new one: “kept this beam, it holds the floor above.” The next person who wants to change that room reads the note and does not repeat your mistake. An ADR is that note, for a decision instead of a wall.

What actually goes in one

The original and still most common shape is Michael Nygard’s, and it is four short sections. That is the whole thing.

# ADR 0003: Use PostgreSQL for relational data

Status: Accepted
Date: 2026-09-08

## Context
Our data is highly relational (users, orders, items) and we need
transactions we can trust. The team knows SQL. We expect moderate scale.

## Decision
Use PostgreSQL as the primary database, from the first version.

## Consequences
Good: strong transactions, mature tooling, easy hiring, one database to run.
Bad: we manage schema migrations carefully; not ideal for unstructured data,
which we will revisit if that need appears.

• Title and a number. Numbered in order (0001, 0002), so they read as a timeline.
• Status. Where the decision stands: usually Proposed, then Accepted, and later maybe Superseded or Deprecated.
• Context. The situation and the forces at the time: what you needed, what constrained you, what you knew. This is the part future readers care about most, because constraints change.
• Decision. What you chose, in plain words.
• Consequences. What follows from it, the good and the bad. Being honest about the downside is what makes the record trustworthy, and what stops someone re-discovering it as a nasty surprise.

The rule that makes them trustworthy: never edit an accepted one

Here is the single habit that separates ADRs that work from a folder of stale files. Once a decision is Accepted, you do not edit it. It is a record of what you knew and chose at that time, and rewriting it destroys exactly the history it exists to keep.

When the decision changes, you write a new ADR that supersedes the old one, and you link the two. The old record stays, marked Superseded, pointing forward; the new one points back. Anyone reading later sees the whole story: what you first chose, and why you later changed your mind.

flowchart LR
  P[Proposed: written up, under discussion] --> A[Accepted: this is the decision]
  A -->|the world changes| S[Superseded by a NEW ADR]
  S -.old one kept, marked, and linked.-> A
  N[New ADR] -.points back to the old.-> S

Which decisions deserve one

Not every choice needs an ADR, and writing one for each tiny thing is how the habit dies. The test is whether a decision is architecturally significant: expensive or painful to reverse, and felt across the project. Choosing your database, your auth approach, your API style, whether to server-render or ship a single-page app, which cloud you deploy to. Not which date library you used.

flowchart TD
  Q{Hard or expensive
  to reverse later?} -->|no| Skip[Skip it: a commit message is enough]
  Q -->|yes| Q2{Will someone later ask
  why we did it this way?}
  Q2 -->|no| Skip
  Q2 -->|yes| Write[Write an ADR]

Three formats, from one sentence to two pages

You will meet a few shapes. Pick by how much the decision is worth writing down.

Start with Nygard. Reach for MADR when the “considered alternatives” really matter, and use a Y-statement when a full page would be more ceremony than the decision deserves.

The tools you actually reach for

You need no tooling at all to start. A folder of markdown files in the repo, next to the code, is the whole system. Tools just automate the numbering and the linking.

Write the why down while you still remember it

The lesson is that the most valuable thing about a decision is the reasoning you will forget by next quarter. Code preserves the outcome and loses the reason. An ADR spends ten minutes to keep the reason, and it pays off every time a new person joins, every time someone wants to undo a choice that was made on purpose, and, quietly, in an interview when you can explain not just what you built but why. It sits right next to the other durable docs a project needs, which I wrote about in what a raw codebase taught me about docs, and it is one of the professional habits from working like someone a team can rely on.

Save the reason, not just the result.

Sources

• GitHub: adr.github.io ADR templates for the Nygard, MADR, and Y-statement formats
• Michael Nygard’s original ADR template for the four-section shape
• Catio: architecture decision records, the 2026 guide for immutability, supersession, and what makes teams keep them
• Google Cloud: architecture decision records overview for why teams adopt them and what counts as significant
• Endjin: a tool for creating and managing ADRs for adr-tools and Log4brains