Architecture Decision Records: Document Why, Not What
Architecture Patterns -- Part 30 of 30
I want to tell you about the worst week of my career.
I had just joined a fintech startup as a senior architect. The codebase was two years old. The founding engineers had mostly moved on. The system was held together with duct tape and tribal knowledge, and my job was to figure out why anything was the way it was -- and then make it better.
The first thing I noticed was a custom authentication layer sitting in front of every single service. Not a standard JWT implementation. Not an off-the-shelf solution. Something proprietary, hand-rolled, and completely undocumented. I spent three days reverse-engineering it before a Slack message from a contractor who had left eight months earlier finally explained it: the original team had evaluated three auth providers, hit a specific rate-limiting issue on the free tier with one of them, had a bad experience with the support team of another, and built their own in a weekend sprint. A decision made in about four hours on a Friday afternoon was costing me four hundred hours of archaeology.
That week taught me something I have been teaching ever since: the most dangerous thing in software is not the code you wrote -- it is the context you forgot to write down.
What an ADR Actually Is
An Architecture Decision Record is a short, structured document that captures a significant architectural decision -- not the implementation details, but the why. Why this option over the others. What problem was being solved. What the team accepted as trade-offs.
The concept was popularized by Michael Nygard and has been gaining serious traction. According to a March 2025 AWS architecture blog post, development teams spend 20 to 30 percent of their time coordinating with other teams -- time that compounds dramatically when architectural context has been lost. AWS's own teams have implemented over 200 ADRs across multiple projects and treat the practice as a foundational engineering discipline.
A Microsoft Azure engineering post from October 2025 puts it plainly: "Without a shared framework, context fades and teams re-debate old choices." An ADR is your team's engineering memory. It is not a design document. It is not a runbook. It is the permanent record of a consequential choice.
The Template
Store your ADRs as Markdown files in a /docs/adrs/ directory in your repository, numbered sequentially. Here is the template I use:
# ADR-001: [Decision Title]
## Status
[Proposed | Accepted | Deprecated | Superseded by ADR-XXX]
## Context
What is the problem or situation that forced this decision?
What constraints, requirements, or forces are at play?
## Decision
What did we decide to do? Be specific.
## Consequences
What happens because of this decision?
**Positive:**
- ...
**Negative:**
- ...
## Alternatives Considered
What else did we evaluate, and why did we rule it out?
That is it. Five sections. Ten minutes to write. Possibly years of context saved.
A Real Example: Choosing Supabase
Here is an actual ADR from a project I worked on last year. This is the kind of decision that gets made in a one-hour call and then silently shapes every subsequent technical choice the team makes.
# ADR-001: Use Supabase Instead of Firebase for the Backend
## Status
Accepted
## Context
We are a two-person team building a B2B SaaS product with a vibe-coding-first
approach. We need authentication, a relational database, and real-time
subscriptions. We have a hard constraint: the founder has a SQL background and
refuses to use a NoSQL primary store. We have a soft constraint: we want to
avoid deep vendor lock-in where possible. We are building on Next.js and
deploying to Vercel.
## Decision
Use Supabase as our primary backend platform.
Supabase gives us PostgreSQL as the database (meeting the SQL requirement),
built-in Row Level Security for authorization logic that lives in the database
layer, real-time subscriptions via Postgres replication, and an open-source
codebase that can be self-hosted if needed.
## Consequences
**Positive:**
- Full SQL with JOINs, transactions, and JSONB -- no impedance mismatch
- Row Level Security means authorization logic is in one place, not scattered
across API routes
- Self-hostable if we outgrow the managed tier or hit compliance requirements
- Open source; we can inspect and extend the client libraries
**Negative:**
- Smaller ecosystem than Firebase -- fewer third-party tutorials and integrations
- Real-time at scale is less battle-tested than Firebase's Firestore
- The Supabase dashboard and DX, while improving, is not as polished
- Smaller community means slower answers to edge-case questions
## Alternatives Considered
**Firebase (Google)**
Pros: Massive ecosystem, excellent documentation, Firestore real-time is rock-solid.
Cons: NoSQL data model is a non-starter given the SQL constraint. Deep vendor
lock-in with Google. No self-hosting option.
**Convex**
Pros: Excellent developer experience, TypeScript-native, built-in real-time.
Cons: Newer and less proven at scale. Proprietary query model. No self-hosting.
Too much risk for a production product at this stage.
Notice what this ADR does that a README cannot: it explains the constraints that made Supabase the right answer for this team at this moment. Six months later, when a new engineer asks "why aren't we using Firebase? There are so many more tutorials," the answer is one file away.
When to Write One (and When Not To)
The question I get most often: "Do I really need an ADR for everything?"
No. Write an ADR when future-you, or a new teammate, would look at the code and reasonably wonder why that choice was made. I call this the Future You Test. Will this decision confuse someone -- including yourself -- in six months?
Write an ADR for:
- Choosing a framework, database, or auth provider
- Selecting a hosting or deployment strategy
- Adopting or rejecting a major architectural pattern (monolith vs. services, REST vs. GraphQL)
- Adding a significant dependency that shapes how the system evolves
- Making a deliberate trade-off between competing concerns (consistency vs. availability, cost vs. performance)
- Changing a previous decision -- especially if the old reason no longer holds
Do not write an ADR for:
- CSS or styling library choices (unless you have a specific, non-obvious reason)
- Minor utility library additions
- Small refactors that do not change the architectural shape of the system
- Decisions that are trivially reversible
According to Spotify Engineering, "the cost of undocumented decisions is hard to measure, but the effects usually include duplicated efforts -- other engineers try to solve the same problems -- or competing solutions." The Startupbricks 2025 ADR guide estimates teams save five to ten hours per month simply by eliminating recurring debates about choices that were already made and forgotten.
ADRs and Your AI Coding Partner
This is worth a separate mention for the audience reading this series. In 2025, most of you are building with an AI coding assistant. ADRs make your AI partner dramatically more useful.
When you drop your /docs/adrs/ directory into context, your AI assistant understands your constraints before it makes suggestions. It knows you chose Supabase because of RLS, so it will not recommend Firebase Auth. It knows you are on a monolith-first approach, so it will not start scaffolding microservices. Documented decisions become codified context, and codified context produces better code generation.
Ask your AI to draft ADRs for you. Give it the constraints, the options you considered, and the choice you made -- and let it write the first draft. Review it, correct it, save it. The process of even dictating the context to an AI forces you to articulate the reasoning out loud, which often surfaces assumptions you did not know you were making.
Your Decision Checklist
Before closing any significant architectural discussion, run through this:
- Have I named the decision clearly enough that a stranger could understand it from the title alone?
- Have I written down the constraints that made this the right answer (not just the fact that we chose it)?
- Have I listed at least two alternatives and explained why we rejected them?
- Have I documented at least one negative consequence? (If you cannot think of any, you have not thought hard enough.)
- Have I saved this to
/docs/adrs/with a sequential number? - Will I still understand why we made this choice in twelve months?
If all six are true, you have written a good ADR. If not, you have written a decision that will cost you later.
Closing the Series
Thirty days ago, we started with the fundamentals: how to think about system design, how to choose the right data layer, how to structure APIs that can evolve. Since then, we have covered REST vs. GraphQL, monoliths vs. microservices, caching strategies, event-driven design, feature flags, cost optimization, and migration patterns. We have gone from first principles to production-grade patterns used by teams shipping software at scale.
But every article in this series was ultimately about one thing: making better choices. Choosing the right tool for the right problem. Understanding trade-offs well enough to make the call and defend it. Knowing when to reach for a pattern and when to reach for something simpler.
The meta-skill that makes all of it stick is writing down why you made the choices you did.
Code captures what you built. ADRs capture why you built it that way. Both are required for the next engineer -- which is often you, six months later, staring at your own code wondering what on earth you were thinking.
Start with ADR-001. Keep them short. Keep them honest. Keep them next to the code.
It has been a privilege building through this series with you. Now go build something worth documenting.
Ask The Guild
This week's community prompt: Share your first ADR. What was the decision? What alternative did you almost choose, and what made you go the other way? Drop it in the Discord -- the best ones become teaching examples for the next cohort.