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.