Making It Stick
Knowing the theory of ADRs and RFCs is straightforward. Making them a living practice in a real organization is the hard part. Here are patterns that successful teams use:
Pattern 1: The Pull Request Gate
Require an ADR for any pull request that introduces a new dependency, changes a data store, modifies the deployment pipeline, or alters a public API. The ADR is included in the same PR as the code change. Reviewers check both the code and the decision record. This is the single most effective adoption mechanism because it ties documentation to the workflow engineers already use.
Pattern 2: The Architecture Review Meeting
Hold a regular (biweekly or monthly) meeting where the team reviews open RFCs and recently accepted ADRs. This creates a forcing function for writing them and ensures cross-team visibility. Keep it short — 30 minutes, focused on decisions, not status updates. The agenda is simple: "What decisions did we make this sprint? What proposals are open for review?"
Pattern 3: The Decision Log Dashboard
Use a tool like log4brains to generate a searchable website from your ADR folder. New team members can browse the full decision history during onboarding. This is dramatically more useful than a "system architecture" document that's always out of date, because the ADR log is always current by definition — each new decision adds to it rather than requiring the whole document to be rewritten.
Pattern 4: The Lightweight Start
Don't introduce both ADRs and RFCs simultaneously. Start with ADRs only. They're simpler, lower-friction, and deliver immediate value. Once the team is comfortable recording decisions, introduce RFCs for the larger, cross-cutting proposals. Trying to implement both at once often results in neither taking hold.
Anti-patterns to avoid:
- ADR inflation: Writing ADRs for trivial decisions ("Use tabs vs. spaces") dilutes the signal. Reserve them for architecturally significant choices. A useful heuristic: if the decision would take more than a day to reverse, it probably warrants an ADR.
- RFC as gatekeeping: Using the RFC process to slow down or block changes rather than to improve them. The goal is better decisions, not more bureaucracy. If an RFC takes more than four weeks to resolve, the process has become the problem.
- Write-only documentation: Writing ADRs that nobody ever reads. If new team members aren't pointed to the ADR folder during onboarding, the practice will die. The ADR folder should be the first stop in the onboarding checklist, before the README.
- Consensus paralysis: Requiring unanimous agreement on RFCs. Aim for "disagree and commit" — once key concerns are addressed, move forward even if not everyone is enthusiastic. Document the dissenting views in the RFC so they're on record.
When asked "How do you handle disagreements about technical direction on a team?", reference the RFC process explicitly: "For significant decisions, we use an RFC process where the proposer writes up the problem, solution, and alternatives. The team reviews asynchronously, and we set a decision deadline. This separates the emotional heat of a meeting from the analytical rigor of written critique. Once we decide, we record the outcome as an ADR so the reasoning is preserved for future engineers." This demonstrates both process maturity and conflict resolution skills — two things senior engineering interviewers specifically probe for.
Key Point: ADRs and RFCs are cultural practices, not just document templates. They only work if leadership models the behavior (writing ADRs for their own decisions), if the team references them regularly ("as we noted in ADR-0015..."), and if onboarding includes a tour of the decision log. The documents are the artifact; the culture of deliberate decision-making is the actual goal. Organizations that treat ADRs as a compliance checkbox will get checkbox-quality ADRs. Organizations that treat them as a genuine communication tool will get genuine institutional memory.