Topic: when to write an adr
When to Write an ADR (and When You Shouldn't)
Most ADRs that get written shouldn't have been, and most decisions that needed an ADR never got one. The cure is a sharper threshold — four yes/no questions you ask before opening the template. Below: the tree, twelve worked examples sorted into yes / no / maybe, and an honest baseline for how many ADRs a 5–50 person team should actually produce per quarter.
TL;DR
Write an ADR when the decision is durable (still relevant in 18 months), cross-team (more than one team will read it), contested (a real alternative was on the table), and costly to reverse (rework would take days, not minutes). Three or four yeses → write the ADR. One or two yeses → leave it as a PR description, design doc, or chat snippet. Zero yeses → it's not a decision worth recording, and writing one anyway is what kills the practice. Realistic cadence: 4–10 ADRs per quarter for a 5–50 person engineering team. More than that and nobody reads the directory; less than that and durable choices are being lost.
Why this question matters more than the template
Every ADR-template page on the internet — including ours — assumes the harder decision is already made: that this thing in front of you deserves an ADR at all. That's backwards. The dominant failure mode for ADR practices isn't picking the wrong format; it's picking the wrong threshold. Teams that write down everything end up with a 200-row directory that nobody reads, then stop writing. Teams that write down nothing end up with the new-CTO problem: "why did we pick Postgres over Mongo?" with no answer in the repo. Both failures look like an ADR-discipline problem; both are actually a threshold problem.
The four-question test below is calibrated against the second failure: it accepts decisions that are clearly durable and rejects everything else. If you're new to ADRs, err on the strict side — under-recording is recoverable (you can add ADRs retroactively from chat exports), over-recording is not (once the directory becomes a wall of noise, the practice is dead inside a quarter).
The four-question decision tree
Run each question against the decision in front of you. Three or four yeses means write it. One or two yeses means leave it where it lives (PR body, design doc, chat). Zero means don't even think about it.
- Durable? Will this decision still be in force 18 months from now? If the answer is "yes, unless something drastic changes," that's a yes. If the answer is "we'll revisit next sprint" or "this only matters until we hit feature X," it's not durable enough — it's a tactical call, not a structural one.
- Cross-team? Does anyone outside the team that made the call need to know about it? Backend choice that only the backend team sees? No. Auth pattern that mobile, web, and integrations all have to follow? Yes. The test isn't whether other teams CAN read it — it's whether they NEED to in order to ship correctly.
- Contested? Was there a real alternative on the table that a reasonable engineer would have picked? If the choice was forced ("we use X because that's what the company already runs"), there's no contest, and the ADR has no useful rationale to record. If two senior engineers argued for an hour, even one that ended in friendly agreement, there was a contest and the trade-offs are worth preserving.
- Costly to reverse? If we change our mind in six months, does it cost a day or a quarter? Reversing a config flag is cheap; reversing a database engine is not. The cost of reversal is what makes the rationale matter — cheap reversals don't need ADR-level documentation because future-us can simply try the alternative if it stops working.
Twelve worked examples
| Decision | Durable | Cross-team | Contested | Costly to reverse | ADR? |
|---|---|---|---|---|---|
| Picking Postgres over MongoDB for the user store | ✓ | ✓ | ✓ | ✓ | Yes |
| Adopting BullMQ as the job queue | ✓ | ✓ | ✓ | ✓ | Yes |
| Moving auth from session cookies to JWTs | ✓ | ✓ | ✓ | ✓ | Yes |
| Choosing Stripe over Lemonsqueezy for billing | ✓ | ✓ | ✓ | ✓ | Yes |
| Adopting Tailwind v4 conventions across the frontend | ✓ | ✓ | ✓ | ✓ | Yes |
| Standardizing on tRPC for internal APIs | ✓ | ✓ | ~ | ✓ | Yes (3.5/4) |
| Renaming a single React component for clarity | ✗ | ✗ | ✗ | ✗ | No |
| Bumping a dependency one minor version | ✗ | ✗ | ✗ | ✗ | No |
| Adding a feature flag for a 2-week experiment | ✗ | ~ | ✗ | ✗ | No |
| Picking which color the new button should be | ~ | ✗ | ✗ | ✗ | No |
| Choosing the structure of one internal endpoint | ~ | ✗ | ✓ | ~ | Maybe (PR body, not ADR) |
| Settling on a vendored utility instead of a small npm package | ~ | ~ | ✓ | ~ | Maybe (design doc, not ADR) |
The "maybe" rows are where most teams over-record. Single-endpoint shape and vendored-vs-package are real trade-offs and worth writing down — but their natural home is the PR description or a design doc next to the code, not the ADR directory. ADRs are the smallest possible set; everything else stays close to the code that implements it.
How many ADRs is normal?
Calibrated against teams that actually keep the practice alive past the first six months — not against the theoretical maximum:
- Solo founder / pre-seed (1–4 engineers): 2–6 ADRs per quarter. Small surface area, fewer durable choices, but the audit trail compounds when the team grows.
- Series A (5–20 engineers): 4–10 ADRs per quarter. The sweet spot — enough durable decisions to fill the quarter, small enough that everyone reads each new entry within a week.
- Series B+ (20–50 engineers): 8–15 ADRs per quarter, organized by domain (one directory per service or product area). Above 15, split or downgrade — mixing tactical and structural in the same directory is what kills it.
- Enterprise (50+ engineers): Each domain treats itself as a 5–20 person team. Aggregate ADR count is meaningless; per-domain cadence matters.
If your team produces zero ADRs in a quarter, run the four-question test against the last 20 closed PRs. You'll usually find 1–3 that quietly should have been ADRs and weren't — onboarding reasoning that's now lost. Backfill them from the PR body and the chat the design happened in. (See extract-decisions-from-chatgpt for the chat-export route to backfilling.)
Common reasons teams write the wrong number of ADRs
Too many
- "Process for process' sake" — every PR over 200 lines triggers an ADR. After two months the directory has 80 entries and the new hire reads the first three then gives up. Fix: gate the trigger on the four-question test, not on PR size.
- Mistaking RFCs for ADRs — proposals get filed as ADRs before any decision is made. RFCs are forward-looking; ADRs document a choice that's already been made. Mixing them produces a directory of half-decided futures and confused readers.
- Treating ADRs as project status — writing one per sprint to "show what we shipped." That's what release notes are for; ADRs aren't a status report.
Too few
- "It's obvious why we picked it" — at the moment, yes. Eighteen months later, no. The clearest sign you should write the ADR is the urge to skip it because everyone already knows.
- Decisions disappear into chat — the trade-offs were debated thoroughly with ChatGPT or Claude, the choice got made, the code shipped, and the chat tab got closed. Nothing reaches the repo. The extractor is the recovery path here.
- Fear of the template — engineers think an ADR has to be three pages, so they don't write one for a decision that needs four sentences. Strict 250-word cap fixes this; if the rationale doesn't fit, the ADR is doing more than one job.
If you only remember one rule
Imagine a senior engineer joining your team in 18 months, reading the ADR directory front-to-back to ramp up. Every entry should leave them less confused than they were before they read it. If an ADR you're about to write would just confirm something they could already infer from the code, skip it — they don't need it. If the rationale would genuinely surprise them, that's the strongest possible signal to write it down.
The practice is for the people who weren't in the room.
How WhyChose helps
The hardest decisions to capture are the ones that crystallized in a ChatGPT or Claude conversation. The trade-offs were real, the alternatives got weighed, the choice got made — but the chat tab got closed and the rationale never reached the repo. WhyChose's open-source extractor reads your AI chat exports and surfaces every decision-shaped exchange (chosen option, alternatives, model, conversation link) so you can run the four-question test against ones the team forgot to record. The hosted product adds team sharing and a one-click "promote to ADR" that drops a Nygard-formatted file into doc/decisions/ with the original chat link preserved as the rationale.
The flow stays the same — durable decisions still get an ADR, tactical ones don't. WhyChose just ensures the durable ones don't escape into chat history and disappear.
Related questions
What's the simplest test for whether a decision needs an ADR?
Ask: in 18 months, will the next person who joins this team need to know why we picked this? Yes → write it. No → don't. The question filters by durability and onboarding cost — the two failure modes ADRs exist to prevent. A decision that won't matter in a quarter doesn't need ceremony; a decision someone will have to reverse-engineer in two years does.
How many ADRs should a 5–50 person team produce per quarter?
Realistic baseline from teams that actually maintain the practice: 4–10 per quarter. Below 4, the team is either young or under-recording. Above 10, the threshold is too low and the practice will collapse within two quarters because reading the directory becomes a chore. The common failure mode is not "we don't write enough" but "we write too many and stop reading any of them."
Should bug fixes ever get an ADR?
Almost never. A bug fix changes behavior to match an existing decision; it doesn't make a new one. The exception is a fix that REVERSES a prior decision because the original turned out to be wrong — in that case the new ADR supersedes the old one (with a clear Supersedes link), and the supersession is the news, not the bug. The git commit is enough for everything else.
What about decisions made entirely in a ChatGPT or Claude chat?
These are exactly the decisions that fail to become ADRs in practice — even when they meet all four criteria. The reasoning happens in a chat tab, the choice gets made, the code ships, and the rationale never reaches the repo. WhyChose's open-source extractor closes this gap: it reads your ChatGPT or Claude export and surfaces every decision-shaped exchange so the team can promote the durable ones into ADRs without rewriting the reasoning from memory.
Further reading
- ADR template in Markdown — copy-paste ready — once you've decided yes, this is the format.
- How to document architecture decisions (without your team revolting) — the 250-word cap and the three-and-one rule that keeps the practice alive.
- Architecture decision record example: Postgres vs MongoDB — the worked example for a textbook yes-on-all-four decision.
- ADR vs Design Decision Record — distinguishing the durable architecture call from the smaller design choice that often belongs in the PR body instead.
- Why your team's ADRs go stale after 60 days — long-form essay on the failure modes this page's threshold is calibrated against.
- The ADR GitHub Action — once you've decided which decisions warrant an ADR, this is the CI pipeline that keeps the resulting directory honest (lint + numbering + supersession + auto-index).
- The open-source extractor — the recovery path when durable decisions disappeared into chat tabs instead of the repo.