There’s an MSR study that mined roughly 900 GitHub repos using ADRs and found about half contain only one to five records total. Not fifty. Not twenty. One to five. That’s not a documentation strategy, that’s a confession.
I’ve lived this pattern on every team I’ve joined. Someone champions ADRs with righteous enthusiasm. A template gets created. The first three decisions get documented beautifully, context, alternatives, consequences, the works. Then the repo goes quiet. Six months later, ADR-004 is still a draft with a typo in the title, and nobody remembers who was supposed to review it.
The question isn’t whether ADRs should work. It’s why they don’t, and what that says about your organization’s architecture maturity.
The Enthusiastic Start and the Inevitable Silence
The death of ADRs follows a predictable arc. The initial burst of energy comes from a genuine problem: decisions get made in hallway conversations, Slack threads, or worse, in someone’s head during a 2 AM debugging session. The rationale evaporates. Six months later, someone asks “why did we choose MongoDB over Postgres?” and the answer is a collective shrug.
ADRs were supposed to fix this. Capture the context, the forces, the trade-offs. Make the “why” as versioned and reviewable as the “what.”
But the research exposes a brutal reality: the practice collapses almost immediately in most teams. Half of all ADR repositories contain fewer than six records. That’s not a gradual decline, that’s an abrupt stop after the initial sprint.
Nobody Reads Them. Nobody Rewards Them.
The most common death trigger isn’t the template overhead. It’s the realization that the output doesn’t matter.
Several practitioners have pointed out the fundamental incentive problem. ADRs were often adopted as “not quite an RFC”, a compromise artifact that lacked the process teeth of a formal proposal. The result? They didn’t drive alignment because no review ritual backed them up. They didn’t preserve decision context because the code drifted away from the written decision within weeks. And they certainly didn’t help anyone’s career. No engineer ever got promoted for writing excellent ADRs.
The logic is inescapable: why invest effort in something that won’t work and won’t benefit you personally?
This is the core problem of lost decision context that ADRs were meant to solve but often fail to preserve. The artifact was designed as a historical record, but history only matters if someone reads it. And nobody does.
The Design Artifact vs. Historical Record Paradox
Here’s the uncomfortable twist: the teams that found ADRs useful were using them for something entirely different than intended.
The most productive ADR practices treat them not as historical records but as design artifacts, living documents that generate conversation, force exploration of alternatives, and bring more than just the architect’s voice into the design process. Moving ADRs through a PR process, with real reviewers and real discussion, is where the value lives.
This reframing changes everything. An ADR becomes a tool for decision-making, not decision-recording. The document is the medium through which the team argues about trade-offs, surfaces blind spots, and reaches consensus. The fact that it remains in the repo afterward is almost incidental.
This explains the “ephemeral” perspective many engineers hold. Design reviews are conversation catalysts. They’re almost never revisited, and that’s okay. The value was captured in the moment of creation, not in the archival.
But this reframing also exposes a trap. If ADRs are treated purely as design artifacts, they evaporate as system documentation. And that’s exactly what’s happening in orgs where decisions drift away from the documented rationale within months.
The Scale Problem: How Many ADRs Is Too Many?
Let’s do some math. If your team makes three architecture decisions per week, that’s roughly 150 decisions per year. Do you really want 150 ADRs in a central repo that nobody reads?
The selection problem is real. Some decisions, like choosing a programming language, remain relevant for years and deserve permanent documentation. Others, like merging two microservices, are operational decisions with a shelf life measured in months. And many are on-the-fly calls within a project’s scope that need justification and communication but don’t need to outlive the project.
Without clear criteria for what deserves an ADR, teams face a binary choice: document everything (and drown in maintenance) or document nothing (and lose all context). The middle ground requires judgment, and judgment requires architectural maturity.
Zebastein, a practitioner wrestling with this exact problem, puts it bluntly: “I am not going to write 150 ADRs stored in a central repo that won’t be read. It is time consuming to write and there is little engagement to read them.”
The Tooling Gap: Markdown Files Aren’t a System
The tooling situation makes everything worse. Most teams store ADRs as markdown files in git or wikis. That works for the first few decisions. But as the catalog grows, the cracks appear:
- No way to link ADRs to the right audience (management vs. architects vs. developers)
- No effective categorization or tagging scheme
- No search capability across decisions
- No way to identify which decisions are still active vs. superseded
- No integration with the workflow where decisions actually happen
The contrast with living documentation that evolves with the system is stark. A static markdown file in a repo is a gravestone, not a living document.
What would better tooling look like? Practitioners have suggested generating ADRs from meeting minutes, supporting tags and categories, linking related decisions, and making everything searchable. The tech exists, but the adoption hasn’t followed.
AI Is Both the Killer and the Resurrection
Here’s where it gets spicy. AI-assisted development is simultaneously making ADRs more irrelevant and more necessary.
On one hand, AI agents are bypassing traditional architecture governance entirely. The pull request lands at 3 AM, written by Claude or Copilot, and nobody’s asking “did this follow our architecture principles?” Because AI agents don’t care about your architecture, they’re generating code that drifts further from documented decisions with every iteration.
We’re watching LLM-generated code accelerate design drift and undermine documented architecture decisions in real-time. The “architectural review” becomes a rubber stamp because nobody can review AI-generated code at the speed it’s produced.
Some teams have found a counterintuitive use: using AI to generate ADRs themselves. The skill registry at Tessl has a create-adr agent skill that generates structured Architecture Decision Records on demand, handling format selection (MADR, Nygard, or Y-Statement), assigning sequential numbers, and validating mandatory fields. The promise is that AI can eliminate the “template overhead” objection by making ADR creation nearly effortless.
But this raises a uncomfortable question: if nobody reads ADRs, does AI-generated documentation make things better or just produce more unread artifacts faster? AI-generated ADRs might be the savior or the snake oil of documentation decay.
The honest answer: AI can reduce the cost of creating ADRs, but it doesn’t solve the incentive problem. Nobody was skipping ADRs because writing them was hard. They were skipping them because they saw no value in reading them.
What Actually Keeps ADRs Alive?
When ADR practices survive beyond a year, something unusual is happening. The patterns that work:
1. The ADR is part of the decision workflow, not an afterthought. If an ADR is required before significant code merges, if the PR fails without it, it becomes load-bearing. This is why the PR-process approach works: the review ritual creates the readership.
2. There’s someone accountable for the practice. Not a committee. One person who notices when the ADR pipeline goes quiet and asks why.
3. The “why not” matters as much as the “what.” The best ADRs document the alternatives that were rejected and why. This is what makes them valuable years later when someone proposes migrating off Postgres to “something simpler.”
4. ADRs are allowed to die. A decision record that’s no longer relevant should be formally deprecated or superseded, not left to rot. The architectural entropy that consumes codebases also consumes documentation.
5. The team actually cares. This is the uncomfortable truth beneath all the process advice. ADR practices survive in teams that value decision transparency and have the psychological safety to document uncertainty and trade-offs. In teams where decisions are made by edict or politics, ADRs become a performative exercise, and everyone knows it.
The Maturity Question
Here’s what the death of ADRs actually reveals: your organization’s architecture maturity.
Teams that can sustain ADRs have already solved the harder problem, they’ve created a culture where decisions are explicit, revisable, and accountable. The ADR is just the visible artifact of that culture.
Teams where ADRs die within months haven’t failed at documentation. They’ve failed at decision-making. The ADR was a band-aid on a deeper wound: decisions made by inertia, authority, or whoever argued loudest in the last meeting.
This is why replacing intuition-based decisions with traceable, documented reasoning is so difficult. It requires admitting that the current process is broken.
What Should You Actually Do?
If your ADR practice is dead or dying, here’s the pragmatic path forward:
- Stop resurrecting the full ADR template. If nobody’s reading 200-word documents, they’re not going to read 500-word documents. Start with a Y-Statement, one paragraph capturing context, decision, and trade-off.
- Move ADRs into your PR workflow. A decision without review is just a diary entry. Make ADRs part of the change process, not a separate documentation task.
- Kill your ADR backlog. Delete the stale drafts. Archive the completed ones. Start fresh with clear criteria for what deserves documentation.
- Make ADRs relevant to AI workflows. If your team uses AI coding assistants, the ADR is now an input to your prompts, a way to tell the agent what constraints to respect. This is the new reality of AI-assisted architecture where documentation becomes part of the context window, not a historical footnote.
- Measure readership, not creation. The number of ADRs created is vanity. The number actually referenced in discussions, PRs, or future decisions is substance. If the readership is zero, the practice is theater.
The Funeral Is Also a Birth
The death of ADRs as commonly practiced isn’t a tragedy. It’s an evolution.
The static markdown file sitting in a repo, unread and unloved, deserves to die. It was never going to preserve institutional knowledge, not because the format was wrong, but because the society around it wasn’t ready.
What replaces it is messier and more alive: decision-making as a continuous conversation, with artifacts that support the conversation rather than attempting to archive it. Whether that’s a PR-process ADR, an AI-generated decision log, or something we haven’t invented yet depends on your team’s culture.
The question isn’t “how do we get people to write ADRs?” It’s “how do we get people to make better decisions, and what documentation supports that?”
Architecture decision records were always a means, never an end. The end is decisions that future engineers can understand, challenge, and improve upon. If your ADRs aren’t serving that purpose, they’re not just failing, they’re actively harmful, because they create the illusion of documentation where none exists.
That’s the real death to mourn: not the practice, but the belief that writing things down is the same as understanding them.