Topic: how to document architecture decisions
How to Document Architecture Decisions (Without Your Team Revolting)
Every team starts an ADR practice. Most abandon it within 60 days. The template isn't the problem — the habit is. Here's the 3+1 rule that makes it stick.
TL;DR
One ADR per durable decision. 250 words max. Linked from the PR that implements it. Status-reviewed at quarter-end. That's the 3+1 rule. Anything more rigid and adoption collapses; anything less and the log goes stale.
Why teams abandon ADR practice
The usual story: someone reads Nygard's 2011 post, proposes ADRs, the team agrees, writes five ADRs in the first month and zero in month two. By month four, the doc/decisions/ folder is a museum. Three failure modes cover 90% of cases:
- Too-long template. The team adopted a 12-section template from an enterprise architecture consultancy. Writing one takes an hour. Nobody does it.
- Unclear bar. "Should this be an ADR?" becomes an argument. When in doubt, engineers skip the ADR. The bar needs to be mechanical.
- No link to the code. ADRs live in a folder nobody opens. Without PR links both ways, the log becomes write-only — which means it might as well not exist.
The 3+1 rule
Rule 1: One ADR per durable decision
Mechanical test: "Will a new hire in six months ask about this?" If yes, ADR. If no, PR comment is enough. Examples: yes → datastore choice, auth vendor, monorepo vs polyrepo, API versioning strategy. No → which index to add to which table, which lint rule to enable, which library version to pin. The bar is "durable," not "important in the moment."
Rule 2: 250 words max
Hard cap. This is the single most-violated rule and the single highest-leverage one. Long ADRs don't get read; unread ADRs aren't audit trails, they're journal entries. If you hit the cap, your scope is too wide — split into two ADRs, or you're really writing an RFC. See our Markdown template for a format that naturally hits this limit.
Rule 3: Linked from the PR that implements it
Two-way. The PR description says "Implements ADR 0042" with a link. The ADR's "Links" section says "Implemented in PR #1234." This is what makes the log usable — the reader sees the code, follows the link, gets the rationale. Without this, ADRs are just docs in a folder.
+1: Quarterly status review
Once a quarter (stick it on the CTO's calendar), review every Accepted ADR and ask: "Is this still true?" Mark the ones that aren't as Deprecated or Superseded by. 20 minutes. This is what keeps the log from silently rotting.
What to do when the habit lapses
Most teams have a 3-month gap in their ADR log — the period when the practice slipped but nobody noticed. Don't try to retroactively write 40 ADRs by memory; you'll get the details wrong. Instead, run an extraction pass over the period's ChatGPT and Claude conversations and over the Slack threads where decisions surfaced. The extract-decisions workflow works well for exactly this — quarterly back-fill from the chat history you already have.
How WhyChose helps
The hardest part of the 3+1 rule is writing the first draft. WhyChose turns that from a blank page into an edit job: upload your ChatGPT/Claude export, get back ADR-shaped drafts for every durable decision, edit and commit. Same format as our Nygard template, with the original chat linked for audit. The extractor is open-source if you want to self-host. Pro tier exports directly to Notion or a doc/decisions/ folder in your repo.
Related questions
Who owns the ADR log — engineers or architects?
Whoever ships the code owns the ADR. Giving a dedicated architect the job creates a choke-point and signals "documentation is someone else's problem." The writer is the implementer; reviewers are the people affected.
How many ADRs is normal for a year?
In our experience: 15–40 for a 5-person team in year one, 40–100 for a 20-person team. More than that and you're over-documenting (writing ADRs for non-durable decisions); fewer than that and the practice has lapsed.
Should we write ADRs for decisions we made before starting the practice?
Only the load-bearing ones — the 5–10 choices that still shape the system. Don't try to reconstruct every historical call; you'll get it wrong and demoralize the team. For everything else, extract from chat history retroactively (see above).
Further reading
- ADR template in Markdown — the template itself.
- The Nygard ADR template — the canonical 5-section format.
- ADR example: Postgres vs MongoDB — 3+1 applied in practice.
- When to write an ADR (and when you shouldn't) — the threshold question that decides whether you ever reach for the template.
- The ADR GitHub Action — the CI complement to the cultural side this page covers; CI catches mechanical failures, the practice habits here catch the cultural ones.
- How to update an ADR (without breaking the audit trail) — the operational discipline for what changes after Accepted; immutability is the practice, with three legitimate exceptions (status, supersession links, Notes section).
- ADR numbering scheme — padding, gaps, and collision recovery — the directory-level discipline that pairs with the practice habits here; mechanical CI enforcement of the never-renumber rule keeps human judgment from corrupting the audit trail.
- ADR storage format comparison — the storage-layer choice interacts with the cultural side this page covers; PR-review culture pairs with Markdown-in-repo (review surface = code review), wiki culture pairs with Notion or Confluence (review surface = page comments). Pick the layer that matches your existing review habits.
- TOGAF ADR template — for enterprise-architecture programs, the ADR practice has to fit into Phase H change management without overwhelming the Architecture Board cadence; the page documents the four common mistakes EA teams make when bolting an ADR practice onto TOGAF (treating every ADR as a Phase H minor change, putting every ADR in the Governance Log, skipping requirements traceability, numbering enterprise-wide).
- Architecture Board charter template — the cultural-process pairing for orgs above ~50 engineers; Boards work only when the underlying ADR practice is healthy, and the charter's input gates (ADR drafted in /doc/decisions/, two consulted parties named, cross-team boundaries explicit in Context) make the per-team practice this page describes a prerequisite rather than a parallel track.
- ADR review checklist — what to look for before merging — the quality gate this page's habits are designed to make easy to pass: a 12-item checklist across structure, reasoning quality, traceability, and longevity that reviewers can apply in five minutes to distinguish well-documented decisions from ceremony-shaped noise.
- ADR adoption guide — how to introduce ADRs to a resistant team — the initial-rollout companion to the ongoing-practice habits on this page: how to get a skeptical team to start writing ADRs using the retrospective-first approach, the minimum viable three-field format for skeptics, and the 60-day adoption threshold that distinguishes a visibility problem from a practice problem.
- Architecture decision record best practices — what actually works after year one — the consolidated operations reference: the five rules that determine whether an ADR practice survives year one, the status lifecycle legal-vs-illegal transitions, the review process CI cannot automate, supersession discipline, and the eight failure modes. The companion to this page's cultural habits, covering the mechanical and governance disciplines that keep the practice alive once habits are established.