Architecture Decision Records

Some decisions are big and hard to reverse: which database, why a particular architecture, why you rejected the "obvious" approach. Months later, someone (maybe you) asks "why is it like this?" — and the reasoning is gone. An Architecture Decision Record (ADR) captures that reasoning at the moment you make the call, so it survives.

What an ADR is

An ADR is a short markdown file, kept in the repo (commonly docs/adr/), that records one significant decision. They're numbered and append-only: you don't edit old ones to lie about the past — if a decision changes, you write a new ADR that supersedes the old.

A reliable template has three parts:

# 0007: Use PostgreSQL for primary storage

## Context
What's the situation and the forces at play? What constraints,
requirements, and options are on the table?

## Decision
What did we choose, stated plainly?

## Consequences
What becomes easier, what becomes harder, what we're now committed to,
and what we explicitly gave up.

Which decisions deserve one

Not every choice — only the ones that are expensive to reverse or that future readers will question:

• Choosing a database, framework, or core dependency.
• A significant structural pattern (the boundaries from the architecture lesson).
• Rejecting a tempting approach — recording why not is often the most valuable.

Small, easily-changed decisions belong in code and commit messages, not ADRs.

Why it beats memory

The "Consequences" section is the payoff. It forces you to state the trade-off honestly now, while you understand it — and it tells a future maintainer what they're allowed to change and what they'd be undoing. It also makes onboarding dramatically easier: a new person reads the ADRs and understands not just what the system is, but why.

Where to go next

ADRs document decisions for maintainers. Finally, changelogs and release notes document changes for your users.