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.
Why architecture decision records are worth the effort
- They survive team rotation. The rationale outlives the person who had it in their head. New engineers can read the why along with the 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. That's the opposite of vendor lock-in.
What goes in an ADR
Keep it short: one decision per record, ideally a page. The widely used structure (originally from Michael Nygard) has just a few fields:
- 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.
Optionally add Options considered (the alternatives and why they lost) and Related decisions (links to other ADRs).
A copy-ready ADR template
Architecture decision record examples
Two filled-in records in the format above. The first is a small, reversible choice; the second supersedes an earlier decision, which is exactly what the status field is for.
Example 1: choosing a vector store
Example 2: splitting a module out of a monolith
Tools for managing ADRs
You do not need special software. A folder of Markdown files in the repository is enough, and the tools below only make it easier:
- adr-tools: a small command-line tool by Nat Pryce that creates numbered records and links superseded ones.
- MADR (Markdown Any Decision Records): a widely used template with an explicit options-and-outcome section.
- Log4brains: turns the ADR folder into a searchable static site that you can publish next to your docs.
- Pull requests: propose each ADR as a pull request, so the discussion and the approval live next to the record.
Best practices for writing good ADRs
- 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, instead of 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.
Anti-patterns to avoid
- 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.
Architecture decision records FAQ
A short, version-controlled document that captures one significant architecture decision (its context, the choice made, and the consequences) so the reasoning survives beyond the people who made it.
At minimum: title, status, context, decision, and consequences. Optionally the options considered and links to related ADRs. One decision per record, ideally a single page.
In the code repository, versioned alongside the system they describe (commonly /docs/adr/), so they don't drift the way a separate wiki does.
A design doc explores a solution in depth; an ADR records a single decision and its rationale concisely. They complement each other: the ADR is the durable "why", the design doc is the detailed "how".
Whenever you make a consequential, hard-to-reverse architectural choice (service boundaries, data ownership, a technology selection, an integration approach), and do it at the moment the decision is made, not months later.
Tell us what you are building. On a 30-minute call a senior engineer walks through your architecture and how decisions get recorded. Or get a first view of the team and timeline in two minutes.