Every technical disaster I’ve witnessed started the same way: someone made a reasonable-sounding decision, didn’t write down why, and six months later nobody could remember the constraints that led to it. The team either cargo-culted around a decision they didn’t understand or reversed it without grasping the original trade-offs — stepping on the same landmine from a different angle.
Architecture Decision Records fix this. Not because they’re fancy or process-heavy — because they’re a forcing function for clear thinking. Writing down “why” is harder than it sounds, and the act of doing it catches bad reasoning before it ships.
“The best architectures, requirements, and designs emerge from self-organizing teams — but only if those teams write things down.” — Martin Fowler
Why Teams Skip ADRs (and Pay for It Later)
The objections are always the same: “We move too fast for documentation.” “Everyone was in the meeting — we all know why.” “We’ll remember.”
You won’t. I’ve been on teams with dozens of engineers where a decision made in Q1 was questioned in Q3 by people who joined in Q2. Without an ADR, the answer is always “I think it was because…” followed by an archaeology expedition through Slack threads and PR descriptions.
On smaller teams the stakes are even higher. When you’re a team of 10 engineers, every architectural choice carries disproportionate weight. Choose the wrong database, the wrong deployment model — and you’re living with it for years because you don’t have the headcount to redo it.
A good ADR takes 30 minutes to write and saves dozens of hours of future debate. The best ones are under 500 words. This isn’t bureaucracy — it’s leverage.
The Simple ADR Template
I’ve tried several formats — Michael Nygard’s original, MADR, the Y-statement format. I’ve converged on a structure that’s lightweight enough to actually get written. Here it is as a reference, not a wall of markdown:
| Section | What Goes Here | Length |
|---|
| Title | ADR-001: Short descriptive name | 1 line |
| Date & Status | Date, plus one of: Proposed, Accepted, Superseded, Deprecated | 1 line |
| Context | What problem are we solving? What forces are at play — technical, organizational, timeline? | 2-4 sentences |
| Options Considered | 2-3 options with pros, cons, and estimated effort for each | A few bullets per option |
| Decision | Which option we chose and why — the reasoning, not just the name | 2-3 sentences |
| Consequences | Positive outcomes, negative trade-offs, and known risks | Bullet list |
| Review Date | When we should revisit this decision | 1 line |
The Two-Way Door Framework
Jeff Bezos popularized this concept, and it’s the most useful mental model I’ve found for deciding how much process a decision deserves.
| One-Way Door | Two-Way Door |
|---|
| Definition | Difficult or impossible to reverse | Easy to reverse with low cost |
| Examples | Primary database, programming language, cloud provider lock-in | CSS library, test framework, linting config |
| Process | ADR, thorough analysis, stakeholder buy-in | Quick decision by the person closest to the work |
| Time to decide | Days to weeks | Hours |
| Failure mode | Under-analyzing → expensive mistakes | Over-analyzing → wasted time on trivial choices |
If the reversal cost is measured in weeks or months, or if the blast radius spans your entire platform, it’s a one-way door. Write the ADR. If it’s a single service and reversible in hours — just decide and move.
Real Trade-Off Examples
ADRs shine when you’re comparing concrete options. Here’s how a comparison table does the heavy lifting:
Example: Choosing an internal API approach
| Criteria | GraphQL | tRPC | REST |
|---|
| Type safety | Codegen required (extra build step) | End-to-end, zero codegen | Manual types or codegen |
| Client complexity | Apollo/urql, cache management | Simple function calls | fetch + types |
| Public API suitability | Excellent | Poor (TypeScript-only) | Excellent |
| Team familiarity | Moderate | Low (newer technology) | High |
| Verdict for internal API | Overhead without payoff | Best fit if TS end-to-end | Best fit if multi-language |
How to Present Trade-offs to Leadership
Engineers often struggle to communicate technical decisions upward. The mistake is leading with technology names. Nobody above you in the org chart cares whether you use Kafka or SQS. They care about cost, timeline, risk, and capability.
| Instead of… | Say… |
|---|
| ”We should use Kafka" | "Option A handles 10,000 tx/min, costs $800/month, 2 weeks to build" |
| "We need to refactor the auth module" | "Every new feature takes 3x longer because of the auth architecture" |
| "Let’s adopt NestJS" | "This framework enforces patterns that prevent the architecture drift we’re seeing as we hire” |
Include a confidence level with your recommendation: “I recommend Option B with high confidence. The risk is X, and we can mitigate it by Y.” This gives leadership a clear signal and an honest assessment — both of which build trust.
When to Revisit a Decision
An ADR isn’t a tombstone — it’s a living document. Revisit when:
- The context changed. You assumed 100 req/s; you’re at 1,000. The ADR was for a different scale.
- The team changed. You assumed 3 senior engineers; you now have 12 mixed-level. Complexity tolerance shifted.
- The technology matured. The “too risky” option from 2 years ago might be stable now.
- You hit a predicted consequence. Every ADR lists negative trade-offs. When those become painful, it’s time to reassess.
When the review date arrives, scan the ADR and ask: “Are the assumptions still valid?” If yes, push the review date out. If no, write a new ADR that supersedes the old one.
Making ADRs Stick
ADRs only work if the team actually writes them:
- Store them in the repo — a
docs/adr/ directory, searchable, reviewed in PRs. Not in a wiki that nobody visits.
- Make them part of the PR process — any PR that introduces a dependency, changes infrastructure, or alters architecture should include or reference an ADR.
- Keep them short — if it takes more than an hour to write, the decision is more complex than you realized (which is itself useful information).
- Reference them in code review — when someone asks “why do we do it this way?”, link to the ADR. Over time, the team internalizes that answers live in a known location.
The best engineering decisions aren’t the ones where you pick the “right” technology. They’re the ones where you understand the trade-offs, document them clearly, and give your future self the context to know when the decision should change. 