Architecture Decision Records: The Missing Piece

The single habit that fixes most engineering documentation is also the cheapest: write a 200-word markdown file each time the team picks one architectural option over another, number it 0001-use-postgres.md, and commit it next to the code. That habit is called an Architecture Decision Record. It is fifteen years old, the templates are free, and most teams still skip it.

The original 2011 essay is by Michael Nygard, the author of Release It! — a Pragmatic Bookshelf title now in its second edition (January 2018) ¹. The essay is one paragraph long where it matters: an ADR is a short numbered document that captures the context, the decision, and the consequences of one architectural choice ². ThoughtWorks moved the technique to its "Adopt" ring in November 2017 — the canonical legitimization moment for the practice — and has kept it there ever since ³. The canonical templates live on GitHub at 16.5k stars ⁴ and 5.6k stars ⁵ (both counts as of 17 July 2026). The MADR project, the markdown-flavoured fork most teams now use, sits at 2.3k stars and shipped v4.0.0 on 17 September 2024 — still the current release as of 17 July 2026 ⁶.

The single habit that makes ADRs work

Write the decision down the day the team makes it, in the same repository as the code, in a numbered markdown file with five sections — title, status, context, decision, consequences. That is the practice. Everything else — review meetings, labels, generators — is optional ². A team that adopts the minimum still captures more than one that does not.

The reason the habit matters is that code does not record why. AWS's prescriptive guidance, written by Darius Kunce and Dominik Goby in March 2022, names the failure mode plainly: "A decision is made without any justification, and people don't understand why it was made. This results in the same topic being discussed multiple times." ⁷ The second failure mode is worse: "The decision isn't captured in an architectural decision repository, so team members forget or don't know that the decision was made." ⁷ An ADR closes both gaps with a flat file the size of a tweet thread.

Joel Spolsky, in April 2000, gave the deeper reason in one sentence — "It's harder to read code than to write it." ⁸ Code that compiles is the output of a decision; the inputs were the alternatives the team rejected, the trade-offs they accepted, the constraints that mattered that morning. None of those facts survive in git blame. The ADR is the only place they get written down.

The five-minute version

The five-minute ADR ships when the team is busy. It is one file, five sections — write it before the pull request merges. AWS, MADR, and Nygard converge on the same spine, only the optional sections differ ^{7 6 2}. If you skip a record, skip the optional sections, not the spine.

Open a markdown file inside docs/decisions/ (the MADR convention ⁶) named 0007-adopt-opentelemetry.md. Write the title in plain English. Set the status to Proposed. Write two sentences of context naming the constraint that forced the decision. Write one sentence stating the choice in active voice. Write a short bulleted list of consequences. Save. Open a pull request. Total elapsed time: five minutes.

The Nygard template is the spine the rest of the ecosystem inherits. The exact section headings are these ⁹:

# Title

## Status
What is the status, such as proposed, accepted, rejected,
deprecated, superseded, etc.?

## Context
What is the issue that we're seeing that is motivating
this decision or change?

## Decision
What is the change that we're proposing and/or doing?

## Consequences
What becomes easier or more difficult to do because
of this change?

That is the whole template — four headings, four prompts, no ornament. Nygard wrote in the original essay that the decision section "is stated in full sentences, with active voice. 'We will …'" ². The grammar matters. A passive voice ADR ("It was decided that …") fails the read-aloud test. The active voice is the same active voice every good engineering document uses.

The seven steps fit on an index card:

1. Create docs/decisions/0007-adopt-opentelemetry.md.
2. Title in noun phrase form ("Adopt OpenTelemetry for request tracing").
3. Status: Proposed.
4. Two sentences of context — the constraint, the alternatives in scope.
5. One sentence of decision in active voice — "We will adopt OpenTelemetry."
6. A short bulleted list of consequences — the new things possible, the new things harder.
7. Open the pull request. Move status to Accepted on merge.

Steps 1–2 collapse if you have a CLI installed. The npryce/adr-tools shell tool, at 5.6k stars on GitHub and last released July 2018, scaffolds files of this exact shape with adr new "Adopt OpenTelemetry" ⁵. The MADR project ships its own templates and a Gitpod link to start a record without local setup ⁶. Either tool removes the friction — and friction is the only thing standing between your team and the practice.

The thirty-minute version

The thirty-minute ADR is the one you write when getting the decision wrong will cost months of refactor. It is the same five sections, with optional MADR fields filled in: decision drivers, considered options, pros and cons, and a confirmation section naming how the decision will be measured ⁶. Default to this past month three.

The MADR long template — currently at v4.0.0, dual-licensed MIT and CC0 — adds five optional sections to Nygard's spine: Decision Drivers, Considered Options, Pros and Cons of the Options, Confirmation, and More Information ⁶. The point is to capture not only the choice but the rejected alternatives and the reasons. The Andrew Harmel-Law article published on Martin Fowler's bliki in December 2021 names the function of these sections directly: "these key elements operate like a thinking checklist, and prompt the decide-ee regarding what they need to think about, and more importantly have conversations about." ¹⁰

The expanded skeleton, in the MADR style, reads like this. Each heading is real; the bracketed prompts are the questions the writer must answer.

---
status: proposed
date: 2026-07-17
deciders: [alice, bob, carol]
consulted: [security-team]
informed: [#engineering channel]
---

# Use Postgres 17 for the document service

## Context and Problem Statement
Why are we choosing a database? What constraint is the
forcing function — latency, durability, vendor cost?

## Decision Drivers
- Latency budget under 50 ms p99
- Single-writer model — strong consistency required
- Small-scale infra budget under $20/month

## Considered Options
- Postgres 17 (managed)
- SQLite + Litestream
- DynamoDB

## Decision Outcome
Chosen option: "Postgres 17", because it satisfies the
strong-consistency requirement at the lowest operational
cost while keeping the door open to read replicas.

## Consequences
- Good, because the team already runs psql daily.
- Bad, because we now own a stateful service.

## Confirmation
The decision is confirmed if the p99 latency on the
document API stays under 50 ms for thirty consecutive days
after launch.

That is the format ThoughtWorks recommended in its 2017 Adopt entry, the format AWS recommends in its 2022 prescriptive guide, and the format the MADR project ships as adr-template.md ^{3 7 6}. The thirty-minute version is not a different document. It is the five-minute version with the optional sections honestly answered.

The Confirmation section is the one most teams skip and the one that pays off most. AWS's guidance is clear about why: "ADRs and the decision log they create represent decisions made by the team and provide a history of all decisions." ¹¹ An ADR with a measurable confirmation criterion gives the next team a way to know whether the decision was right. Without it, the record is a snapshot. With it, the record is a hypothesis.

Where to keep your ADRs and how to number them

Keep them in the source repository, in a folder called docs/decisions/ or docs/adr/, in numbered markdown files with the convention NNNN-title-in-kebab-case.md. ThoughtWorks made this convention its Adopt-ring recommendation in November 2017 for a stated reason: store the details in source control "instead of a wiki or website, as then they can provide a record that remains in sync with the code itself" ³. A wiki drifts. A docs/decisions/ folder lives in the same pull request as the code that implements the decision.

The numbering convention comes from Nat Pryce's 2014-vintage adr-tools shell utility — 0001, 0002, 0003, with leading zeros so they sort correctly in any file browser ⁵. The MADR project follows the same convention with the format NNNN-title.md ⁶. AWS recommends the same shape with a Status: Proposed | Accepted | Rejected | Superseded lifecycle ¹¹. Three independent communities converged on the same naming because the alternative — latest-database-decision-final-v3.md — fails the moment the team grows past two people.

When a new ADR supersedes an old one, do not delete the old file. Set its status to Superseded by ADR-0042 and create the new record. AWS phrases the rule with the precision of an immutability constraint: "When the team accepts an ADR, it becomes immutable. If new insights require a different decision, the team proposes a new ADR." ¹¹ An ADR log is a chain. The chain is the value. A team that overwrites old records loses the only artefact that explains why the new record exists.

Common mistakes

Most teams that try ADRs and quit do so for the same five reasons. The Joel Parker Henderson repository — 16.5k stars, the canonical English-language ADR resource — puts the warning in its teamwork advice: "decision records are a way for teams to think smarter and communicate better; decision records are not valuable if they're just an after-the-fact forced paperwork requirement." ⁴ The five mistakes below all collapse into that one line.

• Writing ADRs as compliance. If the only reader is a process auditor, the record is a chore and the team will quit by month two. The reader is the engineer who joins the team in 2027. Write for them.
• Writing ADRs after the fact. A retrospective ADR loses the alternatives. Write before the merge, not after the postmortem.
• Letting ADRs live in a wiki. Wikis drift from the code. ThoughtWorks named this anti-pattern explicitly when they moved ADRs to Adopt: store them in source control, not in the wiki ³.
• Mutating an old record instead of superseding it. Once accepted, an ADR is immutable. AWS and MADR both make this rule explicit ^{11 6}. Mutate and you destroy the chain.
• Skipping the consequences section. "What becomes easier or more difficult to do because of this change?" is Nygard's hardest prompt and the most useful one ⁹. A team that ships ADRs without consequences is shipping decisions without trade-offs — which is exactly the failure ADRs were invented to fix.

The fifth mistake — skipping consequences — is the one that breaks the practice silently. Andrew Harmel-Law's piece on Martin Fowler's bliki names the cost of skipping it: "I have always seen better, faster, more accountable decisions, and most importantly decisions which are understood and owned by those who implement them." ¹⁰ The accountability lives in the consequences section. Without it, the record is documentation theatre.

Why the ADR log is the most evergreen thing in your repo

An ADR log is the rare engineering artefact that gains value as it ages. Code gets rewritten; the reasoning behind it does not, because the constraints that produced it were real on the day they were written. Andy Matuschak's frame for durable notes fits the log exactly: notes written and organized to "evolve, contribute, and accumulate over time, across projects" ¹².

That durability depends on the format, not the tool. A docs/decisions/ folder of numbered markdown files survives every editor, wiki migration, and vendor change the team will live through — the same local-first argument that applies to any plain-text archive you intend to keep. Wiki-link syntax — [[0007-adopt-opentelemetry]] — connects records to the specs that reference them in any editor that supports it, so the chain of reasoning stays navigable without a database behind it.

Frequently Asked Questions

These are the questions that come up every time the topic surfaces on r/ExperiencedDevs and Hacker News. The answers are the honest version, written for the engineer who has read this far and is wondering whether the practice is worth the friction. The short version: it is, but not for the reasons most blog posts give.

Who invented architecture decision records?

Michael Nygard published "Documenting Architecture Decisions" on the Cognitect blog on 15 November 2011 ². Nygard is a software architect and the author of Release It!, second edition (Pragmatic Bookshelf, January 2018), whose publisher biography described him at the time as "a professional programmer and architect for more than 15 years" ¹³. ThoughtWorks moved the technique to its Adopt ring in November 2017, which is when the practice went mainstream ³.

What is the difference between MADR and the Nygard template?

The Nygard template has four sections — Status, Context, Decision, Consequences ⁹. MADR adds optional Decision Drivers, Considered Options, Pros and Cons, Confirmation, and More Information ⁶. MADR is at v4.0.0 (released 17 September 2024), dual-licensed MIT/CC0 ⁶. The format itself has academic provenance: Kopp et al.'s 2018 paper "Markdown Architectural Decision Records: Format and Tool Support" gave the project its scholarly footing ¹⁴. Use Nygard for the spine; switch to MADR when decisions get controversial enough to need recorded alternatives.

Where should I store my ADRs?

In the source repository, in docs/decisions/ or docs/adr/, in numbered markdown files. ThoughtWorks specifically recommended source-control storage when they promoted the technique to Adopt in November 2017 ³. The MADR convention is NNNN-title.md inside docs/decisions/ ⁶; the npryce adr-tools default is doc/adr/NNNN-title.md ⁵.

What is the difference between an ADR and an RFC?

RFCs are larger pre-decision documents; ADRs are smaller post-decision records. HashiCorp's RFC template includes Background, Proposal, Implementation, UI/UX, and Abandoned Ideas sections ¹⁵. Oxide Computer's RFD process, published as RFD 1 in July 2020, sits in the same family ¹⁶. Spotify frames the relationship cleanly — write an RFC first, then create an ADR once a solution is decided ¹⁷.

Are ADRs worth the time on a small team?

Yes, especially on a small team. The smaller the team, the higher the per-person cost of forgetting why a decision was made. Spotify reported in April 2020 that "ADRs have made it easier for teams to align on best practices." ¹⁷ On a team of one, future-you is the next member — and has forgotten why.

Should every decision get an ADR?

No. AWS lists five categories worth recording — structure, non-functional requirements, dependencies, interfaces, and construction techniques ¹¹. Spolsky's heuristic from "Things You Should Never Do" applies: capture the decisions future developers will be tempted to undo without understanding the constraints ⁸. A naming-convention does not need an ADR. A database choice does.

What tooling should I use?

Three options, all free and open source. The npryce adr-tools shell utility (5.6k GitHub stars, v3.0.0, July 2018) for command-line scaffolding ⁵. The MADR project for templates only — clone, copy adr-template.md, write ⁶. Log4brains by Thomas Vaillant (1.5k stars, v1.1.0, 17 December 2024) for a static-site preview with hot reload ¹⁸. Star counts as of 17 July 2026. Pick one in fifteen minutes.

Can ADRs replace technical documentation?

No, and they are not trying to. ADRs document why a decision was made; reference documentation describes how the system works. Steph Ango's file-over-app rule applies: "digital artifacts that last … must be files you can control, in formats that are easy to retrieve and read." ¹⁹ Reference docs, runbooks, and onboarding guides sit alongside the ADR log.

The first ADR

Write one ADR a week for thirty days, and the second time someone re-litigates the tracing decision, you will hand them ADR-0007 instead of repeating yourself. The record is cheaper than the argument, every time. Open 0001-use-adrs.md and write the first one tonight.

Drafting those records before they ship to your repo works in any markdown editor — MNMNOTE is a browser-based one that runs without an account.

References