Architecture Decision Records That People Actually Maintain

Every team I've worked with has the same archaeological layer in its history: a decision nobody can explain. Why are we on this database? Why is auth its own service but billing isn't? Why did we pick this message broker? The people who knew have left or forgotten. So the team does one of two bad things — cargo-cults the decision forward out of fear, or rips it out and rediscovers, painfully, the exact reason it existed.

I've watched a team spend a full sprint re-debating a technology choice that had been settled — correctly — eighteen months earlier. The original reasoning was sound. It just lived nowhere. So they paid for it twice.

This is the problem Architecture Decision Records solve, and it's why ADRs are the highest-leverage documentation you can write. Not because documentation is virtuous — most of it isn't worth the keystrokes — but because the why behind a hard-to-reverse decision is the one piece of knowledge that stays valuable for years and is most expensive to lose.

The catch: most ADR initiatives die. Someone reads a blog post, creates a heavyweight template, writes three beautiful ADRs, and then the team never writes another. This is how to make them stick.

What an ADR is (and isn't)

An ADR is a short document that captures one architecturally significant decision: the context and forces, the options considered, the choice, and the consequences. That's it.

What it isn't:

• Not a design doc (those describe how a system works; ADRs capture why a choice was made).
• Not a wiki page (wikis describe current state and get edited; ADRs are immutable records of a moment).
• Not exhaustive — an ADR for "which database" is one page, not twenty.

The mental shift: a design doc rots because the system changes and the doc doesn't. An ADR doesn't rot, because it's a record of what was true and what was decided at a point in time. You never go back and "update" history — and that's exactly what makes it low-maintenance.

The five rules that make ADRs survive

Most of what kills ADRs is friction and ceremony. These five rules remove it.

Rule 1: Keep them tiny

The best ADR template fits on one screen: title, status, date, context, options, decision, consequences. If writing an ADR feels like a project, nobody writes them. The famous Michael Nygard format is ~6 short sections for a reason. A two-paragraph ADR that exists beats a perfect ADR that doesn't.

Rule 2: Live in the repo, next to the code

Put ADRs in version control — /docs/adr/0001-use-postgres.md — not in Confluence, not in a Google Drive nobody opens. Three reasons this matters enormously:

• They're discoverable where engineers already are.
• They're versioned alongside the code the decision shaped — git blame can lead you to an ADR.
• They go through pull request review, which means the decision gets debated before it's recorded, by the people it affects.

Documentation that lives outside the repo is documentation that dies. (Same principle as docs people actually read.)

Rule 3: Record the forces and the rejected options

This is the rule that separates a useful ADR from a useless one. The decision is the least valuable part — future-you can see what was chosen by looking at the code. What you can't recover is why: which constraints were binding (team size, deadline, a compliance requirement, existing skills), and critically, what was rejected and why.

The rejected options are gold. When someone proposes "let's switch to X" two years later, the ADR that says "we considered X and rejected it because Y" either ends the debate instantly or — if Y is no longer true — justifies revisiting. Without it, you re-run the entire analysis from scratch.

The forces are the payload. An ADR that records what but not why is a commit message pretending to be a decision.

Rule 4: Write them at the right moment

Too early and the decision isn't real yet (you're speculating). Too late and you're reconstructing reasoning you've half-forgotten. The right trigger: when a decision is architecturally significant and about to be acted on — hard to reverse, affects multiple teams or components, or constrains future choices.

A quick test for "significant enough to ADR": would a new senior engineer be confused or burned by not knowing why we did this? If yes, write the ADR. If it's a reversible, local choice, skip it — ADR-ing everything is its own way to kill the practice.

Rule 5: Never edit a decided ADR — supersede it

ADRs are immutable. When a decision changes, you don't edit the old one; you write a new ADR that supersedes it, and mark the old one Superseded by ADR-0042.

This preserves the history of thinking, which is the whole point. You can trace how the architecture evolved and why each turn was taken. Editing history erases exactly the knowledge ADRs exist to keep. The status field (Proposed → Accepted → Superseded/Deprecated) is what makes the chain readable.

A minimal template

# ADR-0001: Use PostgreSQL for the primary datastore

- Status: Accepted
- Date: 2026-06-01
- Deciders: Ruchit, Platform team

## Context
We need a primary datastore for a transactional system. Forces:
5-person team strongest in SQL; ~2M transactions/month; strong
consistency required for payments; EU data residency; 18-month runway.

## Options considered
- **PostgreSQL (chosen):** mature, strong consistency, team knows it,
  managed options in-region. Con: manual sharding if we get huge.
- **MongoDB:** flexible schema, easy scale-out. Rejected: weaker
  transactional guarantees for our payment flows; team lacks depth.
- **DynamoDB:** serverless scale. Rejected: access patterns still
  fluid; lock-in; team unfamiliar.

## Decision
We will use PostgreSQL (managed, EU region) as the primary datastore.

## Consequences
- Positive: strong consistency for payments; fast team velocity; one
  fewer thing to learn.
- Negative: we own sharding strategy if we exceed single-instance scale.
- Revisit when: sustained write load approaches single-primary limits.

That's a complete, useful ADR. It took ten minutes to write and will save someone a sprint in two years. A ready-to-copy version lives in the /adr folder of the architecture catalog repo.

How ADRs change a team

Once the habit takes, the second-order effects are bigger than the documents themselves:

• Onboarding collapses from months to days. A new engineer reads the ADR log and understands not just what the architecture is but why — the reasoning, the trade-offs, the dead ends. That context used to live only in senior heads.
• Debates end faster. "We considered that, here's why we didn't" is a sentence, not a sprint.
• Decisions get better. Writing the forces down forces clarity. I've changed my own mind mid-ADR more than once, because articulating the rejected options revealed the "obvious" choice wasn't.
• The architecture becomes legible. The ADR log is the narrative of how the system came to be — the missing manual for why the architecture looks the way it does.

What to do Monday morning

1. Create /docs/adr/ in your main repo and copy a one-page template in. Lower the friction to near zero before you ask anyone to use it.

2. Write ADR-0001 for a decision you already made — retroactively. Pick the architectural choice people most often ask "why did we do this?" about. This proves the value immediately and seeds the log.

3. Add "write an ADR" to your definition of done for significant decisions. Not every decision — just the hard-to-reverse, multi-team, future-constraining ones. Make it part of the PR that implements the decision.

4. The next time a settled decision gets re-litigated, point at the ADR. If there isn't one, that's the signal to write it. The pain is the prompt.

Key takeaways

• ADRs capture the one thing that stays valuable: why. A decision's reasoning and rejected alternatives are the knowledge most expensive to lose and most likely to be lost. The choice itself is visible in the code; the why isn't.

• They survive only if friction is near zero. Keep them tiny (one screen), in the repo next to the code, and reviewed via pull request. Heavyweight templates and external wikis are how ADR initiatives die.

• Record the forces and the rejected options. The binding constraints and the "we considered X and rejected it because Y" are what end future debates and justify revisiting. An ADR without the why is just a commit message.

• Write them at the right moment and for the right decisions. When a significant, hard-to-reverse choice is about to be acted on — not for every local, reversible decision. The test: would a new senior engineer get burned by not knowing this?

• Never edit history — supersede it. Immutability preserves the evolution of thinking. Mark old ADRs superseded and link forward; this chain is the readable story of your architecture.

Your next step

Write one ADR today, retroactively, for the decision your team most often re-explains to newcomers. It'll take ten minutes and it does two things at once: it captures knowledge that's currently trapped in someone's head, and it shows the team — by example, not by mandate — exactly how cheap and how valuable this is. The best documentation isn't the most complete. It's the kind that gets written, and the kind that explains why.

Frequently asked questions

What is an Architecture Decision Record (ADR)?

An ADR is a short document that records a single architecturally significant decision: the context and forces at play, the options considered (including rejected ones), the decision made, and its consequences. Its purpose is to preserve the why behind hard-to-reverse choices — the reasoning that's most expensive to lose and that the code itself doesn't reveal. Unlike design docs (which describe how a system works) or wikis (which describe current state), an ADR is an immutable record of a decision at a point in time, which is what keeps it from rotting.

How is an ADR different from a design document?

A design document describes how a system or feature works and tends to go stale as the system evolves, because the system changes and the doc doesn't. An ADR captures why a specific decision was made and is never updated after it's accepted — when the decision changes, you write a new ADR that supersedes the old one. Because an ADR is a record of a moment rather than a description of current state, it stays accurate and low-maintenance indefinitely.

What should an ADR contain?

A good ADR is one screen: a title and number, a status (Proposed / Accepted / Superseded / Deprecated), a date, the context and forces (the constraints driving the decision), the options considered including why alternatives were rejected, the decision itself, and the consequences (what becomes easier and harder, and when to revisit). The most valuable parts are the forces and the rejected options — they're what end future debates and explain the choice to people who weren't there.

When should you write an ADR?

Write one when a decision is architecturally significant and about to be acted on — meaning it's hard to reverse, affects multiple teams or components, or constrains future choices. A useful test is: would a new senior engineer be confused or burned by not knowing why this was done? Don't write ADRs for every small, reversible, local decision — over-documenting adds friction and is a common reason ADR practices collapse. Significant, durable decisions only.

Should you edit an ADR when the decision changes?

No. ADRs are immutable. When a decision changes, write a new ADR that documents the new decision and mark the old one as "Superseded by ADR-NNNN," linking the two. This preserves the history of how and why the architecture evolved, which is the entire value of keeping ADRs. Editing a decided ADR erases exactly the reasoning the practice exists to retain.