WhyChose

Topic: adr adoption guide

ADR Adoption Guide — How to Introduce Architecture Decision Records to a Resistant Team

Most ADR adoption attempts fail within 60 days. Not because the practice is wrong, but because the rollout approach is wrong: a team meeting about why ADRs are good, followed by an instruction to "start using the template," followed by silence, followed by two ADRs written by the one person who cared, followed by nothing. The teams that actually sustain the practice don't start with a proposal. They start with a single retrospective ADR about a decision the team is already tired of explaining — and let the value speak before asking anyone to change their habits.

TL;DR

Don't propose ADRs at a team meeting. Write one retrospective ADR about a real recent decision, submit it as a PR, and let the team read it. If the reaction is "I wish we'd had this six months ago," you have buy-in. Start with a minimal format (three fields, not five), use the ADR GitHub Action as scaffolding not enforcement, and apply the review checklist to keep quality high without creating friction. The 60-day threshold: if nobody has looked up an existing ADR in 60 days after writing three of them, the directory needs better visibility — not more ADRs.

Why teams resist ADRs — the real objections behind the stated ones

The stated objection is almost always "overhead." The actual objections underneath are usually one of three things, and each has a different fix:

"We already do this in Confluence" → actually: tribal knowledge, not decision records

A Confluence page titled "Architecture Overview" is not an ADR. It documents the current state of the system; it doesn't document the moment of decision, the alternatives that were rejected, and the trade-offs that were accepted. The test: can a new engineer find the answer to "why did we pick Postgres over MongoDB?" in your Confluence, with the reasoning that was current at the time the decision was made? If the honest answer is "they'd find an overview page that mentions we use Postgres, but not why," your Confluence doesn't replace ADRs — it documents outcomes without preserving the reasoning that produced them.

"We move too fast" → actually: the documentation-on-fire fallacy

The framing is backwards. Teams that "move too fast for ADRs" are accumulating architectural debt that will cost more time later than the ADR would have taken to write. The counter-evidence is direct: how much time did you spend last month explaining a decision to a new team member or a new stakeholder? That explanation time — repeated monthly because nothing is written down — exceeds the time it would have taken to write one ADR when the decision was made. The practice isn't overhead; it's paying now to avoid paying more later.

"Nobody will read them anyway" → actually: a visibility problem, not a value problem

ADRs that live in a directory nobody knows exists don't get read. The fix is wiring the directory into the team's existing flow: link ADRs from the PR description of the implementation they document ("see ADR-0042 for why we chose this"), pin the directory in your team Slack channel, add the path to the new-hire onboarding doc. An ADR is read when someone has a question and knows where to look. Getting them to look is a discoverability problem, not an evidence that the practice is useless.

Start with a retrospective ADR — not a proposal

The most effective ADR rollouts follow the same pattern: someone writes one retrospective ADR for a decision that already confused a new teammate, or that the tech lead had to explain in a meeting last month, and submits it as a PR without a team-wide proposal about "adopting the ADR practice."

The retrospective ADR has two advantages over a prospective proposal:

  1. It demonstrates value immediately. Instead of arguing that ADRs would have been useful, you show a specific case where this ADR would have saved time. The reaction "I wish we'd had this six months ago" is the buy-in moment. You can't manufacture that with a process pitch; you can trigger it with a concrete example.
  2. It removes the cold-start paralysis. The hardest part of writing any ADR is knowing what to write for the first one. A retrospective ADR has a natural subject: the decision someone asked you to explain last week. The reasoning exists; you're reconstructing it, not inventing it. The prospective ADR requires anticipating what future engineers will want to know — which is harder to do well under time pressure.

Choosing the right first ADR: Pick the decision that caused the most confusion or re-explanation in the last three months. Good candidates: the database selection, the authentication approach, the choice of mono-repo vs. multi-repo, a dependency that confused a new hire, a pricing call that came up in a board meeting. Not good candidates: an implementation detail (which connection pool library to use), a reversible UI choice, anything that will change in a quarter.

The when-to-write-an-adr decision tree can help you pick the right candidate: four questions (durable, cross-team, contested, costly to reverse) that sort decisions into yes/no/maybe. Start with a "yes" on all four.

The two-champion requirement

Sustainable ADR adoption almost always requires two champions at different levels of the hierarchy:

If you're a staff engineer or senior IC pushing this without tech-lead buy-in, you're not blocked — but you need a different strategy. Rather than asking the tech lead to mandate ADRs, ask them to link to one when they explain a decision in a team sync. "I wrote up the reasoning as an ADR, here's the link" is a lower-friction ask than "we should adopt the ADR practice." Once the tech lead has linked to an ADR twice in a meeting and seen the value of not re-explaining the same decision to different people, the mandate case makes itself.

Minimum viable format for skeptical teams

The Nygard template's five sections (Title, Status, Context, Decision, Consequences) are the right target for a mature practice. But requiring five complete sections for a team's first ten ADRs creates a quality bar that kills the habit before it forms.

The minimum viable ADR for adoption purposes has three parts:

  1. A decision statement title — "We chose Postgres for the user database" not "Database selection." The title should pass the test: can a new engineer scan the ADR directory and understand every decision made without opening a single file? If yes, the titles are decision statements.
  2. A why paragraph — two to four sentences covering: what constraint or problem triggered the decision, what alternatives were seriously considered, and the one-sentence reason each was rejected. This doesn't have to be comprehensive; it has to be honest. "We considered MongoDB but rejected it because our schema is well-defined and we wanted stronger ACID guarantees for the dual-write pattern we're using" is enough.
  3. A consequences paragraph — the most important part, and the most often skipped. At least one upside and at least one downside. The review checklist's single most important item is that the Consequences section has at least one negative consequence — an ADR that lists only benefits wasn't written honestly, and a Consequences section that only says positive things provides false assurance to future engineers who trust it.

Once the team is writing ADRs consistently with the three-field minimum, add Status (the lifecycle state — Proposed, Accepted, Superseded, Deprecated) and then the full Context section. The MADR variant is a good stepping-stone between minimal and Nygard-complete: structured YAML frontmatter for machine readability, with narrative prose for the human-readable body.

Using CI as adoption scaffolding, not enforcement

The ADR GitHub Action workflow is commonly framed as enforcement — a way to prevent low-quality ADRs from merging. That framing is wrong for early-stage adoption and right for mature practices.

In the first 90 days of adoption, the job of CI is to help engineers write ADRs that look right without having to remember the template. The GitHub Action's three immediate benefits for new adopters:

Hold off on enabling the reasoning-quality lint jobs (which check for alternatives count, consequences content, and active voice in the Decision section) until the team has written at least 10 ADRs. Failing those checks for a team that's still learning the practice creates friction at exactly the wrong moment — when the team is deciding whether the habit is worth maintaining. The human review layer in the review checklist handles reasoning quality; CI handles structure.

The 60-day adoption threshold

The best early indicator that ADR adoption is working is not how many ADRs the team has written — it's whether anyone has looked up an existing ADR to answer a question. If you've written three retrospective ADRs and nobody has linked to one, cited one, or mentioned one in a PR review in 60 days, the problem is visibility, not content.

Visibility fixes:

If 60 days pass and no ADR has been consulted, that's not evidence the practice is useless. It's evidence that the decisions you picked for the first ADRs were not the decisions that were actively creating confusion — go back to the retrospective-first step and pick different ones.

When someone blocks on ceremony

After the first few ADRs are written and merged, you will encounter the engineer who refuses to write one for a significant decision. The stated reason is usually "I don't have time" or "this is obvious, we don't need to document it." The implicit ask is that you stop requiring them to write it.

Two responses that don't create conflict:

  1. Offer to write the first draft from the PR description. Most decision reasoning is already in the PR description, Slack thread, or design doc associated with the implementation PR. Offer to take those and turn them into an ADR draft; all the engineer has to do is review and approve. This removes the "I don't have time" objection and demonstrates that the ADR is 20 minutes of synthesis, not a two-hour writing assignment.
  2. Ask the one question that the ADR answers. "If a new engineer joins in six months and asks why we built it this way, where do they find the answer?" If the honest answer is "they'd have to ask someone on Slack and hope that person remembers," the absence of an ADR has already accepted a future cost. Frame it as: "I'm not asking you to write documentation — I'm asking you to write down the one sentence you'd say if someone woke you up at 3am and asked why we chose this."

Avoid mandating ADRs for every significant decision in the first six months. Mandate them for the decisions where not having an ADR already caused a problem — new hire confusion, a technical interview question nobody could answer, a board question that took 20 minutes to reconstruct. The mandate sticks when it's backed by a specific incident, not a general principle about good engineering practice.

How WhyChose fits in

The hardest part of writing a retrospective ADR is reconstructing the reasoning. The decision was made in a ChatGPT or Claude conversation three months ago where you weighed the trade-offs, rejected two alternatives with specific reasoning, and landed on the current approach. That conversation captured the entire ADR — the context, the alternatives, the decision, the consequences — but it's buried in a chat archive somewhere, and starting from memory produces an ADR that says "we chose this because it seemed right" rather than one that says "we rejected MongoDB because our schema is stable and we wanted ACID guarantees for the dual-write pattern we were designing."

The WhyChose extractor reads your ChatGPT or Claude export and surfaces the decision-shaped conversations: threads where alternatives were named, trade-offs were discussed, and a conclusion was reached. A retrospective ADR drafted from an extractor output typically passes the review checklist's reasoning-quality items on the first review — because the reasoning was done in the conversation and the extractor makes it legible rather than requiring you to reconstruct it from memory.

Get early access

Related questions

How do I convince my tech lead to try ADRs when they think it's overhead?

Don't propose ADRs as a practice — write one retrospective ADR for a decision the tech lead has personally had to explain more than once this quarter. Submit it as a PR. Most tech leads who resist ADRs as overhead respond differently when they see a concrete one about a real decision that already cost the team time. The barrier is that ADRs feel like speculative work; a retrospective ADR for a decision the team has already paid the explanation cost for is demonstrably not speculative.

Should we write ADRs for decisions that have already been made?

Yes — selectively. Retrospective ADRs for the 5–10 decisions that still shape your system are more valuable than prospective ADRs for 50 future decisions. Pick decisions where the reasoning is actively causing confusion or re-explanation, not decisions where the history is already obvious. For foundational retrospective ADRs, the WhyChose extractor can recover the original reasoning from the AI chat where the decision was first worked through — typically more accurate than memory six months later.

How many ADRs should a team of 8–10 engineers write per month?

Months 1–2: 2–4 retrospective ADRs total (not per month). The goal is demonstrating value and establishing the habit. Month 3 onward: roughly 1–3 per month for an active 8–10-person team. More than 5–6 per month suggests over-documenting reversible decisions; fewer than 1 per month means the practice has lapsed. The sustainable long-term range is 8–20 ADRs per year for a 5–10-person team.

What's the minimum viable ADR for a team that finds the Nygard template too formal?

Three fields: a decision statement title ("We chose Postgres for the user database"), a why paragraph covering what was rejected and why, and a consequences paragraph with at least one downside. The perfect five-section Nygard ADR that never gets written is worse than the three-field ADR that actually captures the decision. Add fields as the habit forms; the minimum viable ADR is the one that captures the decision, one real rejection rationale, and one honest trade-off.

Further reading