Architecture Decision Records: A Practical Guide

An Architecture Decision Record (ADR) is a short document that captures one significant architectural decision — the context, the choice, and the consequences. That's it. No 90-page design doc, no wiki page nobody updates: a single, dated, version-controlled record of why you decided what you decided. ADRs matter because architecture doesn't live in diagrams; it lives in the decisions teams make every week. When those decisions aren't written down, the reasoning leaves with the people who made it — and next quarter someone relitigates a trade-off that was already settled, or worse, quietly undoes it without knowing why it was made. ADRs are the cheapest insurance against that.

• They survive team rotation. The rationale outlives the person who had it in their head. New engineers can read why, not just what.
• They stop the same debate recurring. A decision with a written record and status ("we chose X over Y because Z") ends the quarterly re-argument.
• They make trade-offs explicit. Writing down the options you didn't pick, and why, is where most of the value is.
• They're auditable. In regulated contexts, a trail of dated decisions with rationale is evidence, not overhead.
• They keep knowledge in your organisation, not a vendor's. An engagement that leaves ADRs in your repos leaves you able to change the system yourself — the opposite of vendor lock-in.

• Title — a short noun phrase, numbered (e.g. "ADR-014: Use event sourcing for the ledger").
• Status — Proposed / Accepted / Deprecated / Superseded (by ADR-NNN).
• Context — the forces at play: the problem, the constraints, the requirements that make this decision necessary.
• Decision — what you're doing, stated plainly ("We will…").
• Consequences — what becomes easier and what becomes harder as a result, including the risks you're accepting.

• Write it when the decision is made, not after. ADRs authored retroactively lose the real context and become box-ticking.
• One decision per record. If you're documenting five things, you have five ADRs.
• Record the options you rejected. The "why not" is often more useful to the next reader than the "why".
• Store them with the code, in the repo (/docs/adr/ or similar), versioned alongside what they describe — not in a separate wiki that drifts.
• Never edit an accepted ADR to change the decision. Supersede it with a new one and set the old status to "Superseded by ADR-NNN". The history is the point.
• Keep them short. If it's growing past a page or two, it's probably more than one decision.
• Make writing them a team ritual, not one architect's chore — decisions are better when the people affected help record them.

• The ADR graveyard. A folder created once and never added to. ADRs only work as a habit.
• Design docs disguised as ADRs. A 20-page document isn't an ADR; it's a design doc. Keep the decision record separate and short.
• Editing history. Rewriting an accepted ADR erases the very context that makes it valuable.
• No status field. Without status, readers can't tell a live decision from a superseded one.