The Reason Most Architecture Decision Records Get Written and Never Read Is Architectural, Not Cultural
Architecture Decision Records are praised universally and practised sporadically. The orthodox explanation is culture and discipline. The deeper argument is that ADRs are static documents pretending to be living artefacts — and that category error is the real problem.
There is a particular kind of failure in software engineering that is especially frustrating because it happens to good teams with good intentions. Architecture Decision Records — ADRs — are one of them. The idea is genuinely sound: capture the context, the options considered, and the reasoning behind a significant architectural choice, so that future engineers aren’t condemned to make the same mistakes or reverse decisions without understanding why they were made.
In practice, however, most teams follow a recognisable trajectory. ADRs are adopted with enthusiasm, written carefully for several months, and then quietly abandoned — either because the process feels burdensome, or because the records accumulate without anyone consulting them. Eventually the repository becomes archaeological, and new decisions get made without reference to it at all.
The conventional explanation is cultural: teams are busy, documentation requires discipline, and there’s no enforcement mechanism. That explanation is not wrong, but it is incomplete. The deeper problem is architectural.
1. The Well-Intentioned Failure Pattern
To understand why ADRs fail, it helps to look honestly at how they typically decay. The lifecycle is strikingly consistent across organisations, regardless of team size or engineering maturity.
An ADR written in 2021 to justify a technology choice is not merely irrelevant in 2025 — it is actively misleading to anyone who finds it and reads it at face value. Stale documentation is worse than no documentation because it creates false confidence.
2. The Category Error at the Heart of ADRs
Here is the structural diagnosis: ADRs are point-in-time documents being asked to perform a living artefact function. That is a category error, and it is baked into the format itself.
A point-in-time document records a snapshot: what was known, what was decided, what context existed at the moment of writing. A living artefact, by contrast, reflects the current state of the system it describes and is kept accurate by the natural forces of the system’s evolution — tests fail when behaviour changes, type errors surface when interfaces shift, deployment pipelines break when dependencies move.
The fundamental difference is this: a living artefact has an enforcement mechanism. A static document does not. Consequently, when the system evolves and the document no longer matches, nothing breaks. There is no signal. The divergence is invisible until someone reads the document and acts on outdated information.
“Decision records are documents pretending to be living artefacts. The decision to treat them as equivalent is itself an architectural mistake — one that compounds with every passing month.”
This is not a criticism of the ADR concept per se. Nygard’s original framing was specifically about recording the context that leads to a decision, not about maintaining a live specification. The problem arises when organisations adopt ADRs as their primary mechanism for architectural knowledge continuity — a role they were never designed to fill on their own.
ADR adoption curve vs. active maintenance rate over time (composite practitioner data)
3. Conway’s Law and the Org-Chart Problem
Conway’s Law — the observation that organisations design systems which mirror their communication structures — is directly relevant here, and not just as a curiosity. It tells us something important about the rate of architectural change and therefore about the viability of static documentation.
The key insight is that org charts evolve faster than ADRs. Teams merge, split, get reorganised, or simply rotate their membership. The communication pathways that generated a particular architectural decision change within months. Meanwhile, the ADR sits in a repository, authored by people who may have left the company entirely, and implicitly attributed to a team structure that no longer exists.
Furthermore, the Inverse Conway Manoeuvre — deliberately shaping teams to drive desired architectural outcomes — makes this even more acute. When teams are restructured to align with a target architecture, the old ADRs reflect the reasoning of the old team structure. A decision that made perfect sense given a particular team’s ownership boundaries becomes confusing or wrong once those boundaries move.
| Rate of Change | Artefact | Typical Drift Window | Impact on ADR Accuracy |
|---|---|---|---|
| Fast (weeks) | Team membership, on-call rotas | 2–8 weeks | Immediate author context lost |
| Medium (months) | Team ownership boundaries, squad structure | 3–9 months | ADR context shifts significantly |
| Slow (quarters) | Vendor relationships, technology strategy | 6–18 months | Stated rationale may no longer apply |
| Very slow (years) | Domain model, core data entities | 18 months+ | ADR reasoning more likely to hold |
| Technology lifecycle | Framework versions, library support | 12–36 months | High risk of active misdirection |
The implication is sobering: only decisions about the most stable aspects of a system — core domain models, fundamental data entities — have any realistic chance of remaining accurate in an ADR without active maintenance. Everything else is on a decay clock from the moment it is written.
4. The Maintenance Burden Falls on the Wrong Person
Even teams that understand this problem often respond with the same answer: “We need better discipline about keeping ADRs updated.” This misses the structural issue entirely, because it assumes that the person responsible for updating an ADR has sufficient context to know when it has become inaccurate.
In practice, the engineer most likely to touch a codebase in year three is a new joiner. They have the least context about the original decision, the constraints that existed when it was made, and whether those constraints still apply. Yet they are the ones most likely to encounter the ADR and face the choice of accepting it at face value or investing significant investigation time in questioning it.
Meanwhile, the engineer with the best context — the original decision-maker — is often no longer on the team. The maintenance cost therefore falls consistently on the person with the least information, which is precisely backwards. Consequently, stale ADRs persist not because of laziness, but because the people who encounter them cannot confidently update them, and the people who could update them never see them.
ADR maintenance cost is paid by the person with the least context about whether the record is still accurate. This is not a cultural failure — it is a structural guarantee of decay built into the format itself.
5. What Living Architectural Knowledge Actually Looks Like
So if ADRs are insufficient, what actually works? The answer is not to abandon structured decision-making, but to couple architectural knowledge to artefacts that have their own enforcement mechanisms — things that break when they diverge from the system, rather than silently persisting in an inaccurate state.
5.1 Fitness Functions
The concept of fitness functions, introduced by Neal Ford, Rebecca Parsons, and Patrick Kua in Building Evolutionary Architectures, describes automated checks that verify architectural properties on every build or deployment. Rather than documenting that “we chose a microservices boundary here because we want independent deployability,” a fitness function asserts it directly:
# Example: ArchUnit test (Java) asserting no cross-domain coupling
# This runs in CI and FAILS if the boundary is violated
# The decision is now enforced, not merely documented
@ArchTest
static final ArchRule noCrossModuleCoupling =
noClasses()
.that().resideInAPackage("..payments..")
.should().dependOnClassesThat()
.resideInAPackage("..orders..")
.because("Payments and Orders are separate bounded contexts. "
+ "See ADR-0031 for coupling constraints.");
Notice what this achieves: the constraint is now executable. It breaks the build if violated. Furthermore, the error message references the ADR — not as the primary record-keeper, but as supplementary context for anyone who wants deeper background. The ADR’s role shrinks from sole authority to useful footnote.
5.2 Embedded Decision Comments
A simpler but surprisingly effective technique is to embed decision rationale directly in the code, adjacent to the thing it describes. This approach, documented in Ford and Richards’ Software Architecture: The Hard Parts, follows the principle that documentation closest to the code is documentation most likely to be updated when the code changes.
# In the service that handles payment retries: ## DECISION: Synchronous retry with 3-attempt cap (2023-08-12) ## Context: Async retry via queue was evaluated but rejected because our ## payment provider SLA requires idempotency keys to expire within 60s. ## Async retries exceeded this window in load testing (see load-test/2023-08/). ## Revisit if: provider SLA changes, or p99 retry latency exceeds 800ms. ## Owner at time of decision: @payment-platform-team MAX_RETRY_ATTEMPTS = 3 RETRY_BACKOFF_MS = [100, 300, 500]
The critical addition here is the “Revisit if” clause. Rather than leaving the decision open-ended, it specifies the conditions under which it should be reconsidered. This transforms the comment from a historical record into an active trigger — one that any engineer touching this code can evaluate immediately.
5.3 Architectural Tests with Expiry
A third technique, less commonly discussed, is to attach expiry dates to architectural decisions at the test level. If a decision was made under a specific constraint — a particular performance budget, a specific vendor dependency, a known limitation of a library — that constraint can be encoded as a test that intentionally fails after a set date, forcing a re-evaluation.
# Python example: decision review trigger test
# This test PASSES until the review date, then FAILS to prompt re-evaluation
import datetime
import pytest
def test_review_redis_session_store_decision():
"""
ADR-0047: Redis chosen for session store over DB-backed sessions.
Reason: DB sessions caused p99 latency >200ms under load (2024-01-15).
Review by: 2025-06-01 — check if new DB read replicas resolve this.
"""
review_date = datetime.date(2025, 6, 1)
today = datetime.date.today()
assert today < review_date, (
f"ADR-0047 review overdue ({today}). Re-evaluate Redis vs DB sessions. "
f"See docs/decisions/ADR-0047.md for context."
)
This is a small but structurally important idea. It means that the passage of time — the very thing that makes ADRs stale — becomes a signal rather than a silent decay mechanism.
Decision persistence: static documents vs. enforcement-coupled approaches (time-to-divergence from system reality)
6. The Practical Shift: Coupling Decisions to Systems
The underlying principle tying all three alternatives together is the same: architectural knowledge should be coupled to the system it describes, not stored separately from it. When documentation lives in a separate repository, or a separate wiki, or even a separate directory, it can drift silently. When it is embedded in code, executed in CI, or expressed as a failing test, it cannot.
This does not mean abandoning the ADR format entirely. ADRs remain valuable as narrative records — for capturing the full context of a decision, for providing background that code comments cannot hold, and for creating a historical log that post-mortems can draw on. The mistake is treating them as the primary mechanism for architectural knowledge, rather than as a supplement to enforcement-coupled artefacts.
| Approach | Best For | Enforcement Mechanism | Decay Risk |
|---|---|---|---|
| Standalone ADR | Full narrative context, post-mortems, historical record | None — voluntary | High |
| Embedded decision comment | Tactical choices, inline rationale with “revisit if” clause | Proximity to code (partial) | Medium |
| Fitness function / ArchUnit | Structural constraints, bounded context boundaries | CI failure on violation | Very Low |
| Expiry-triggered test | Time-bounded decisions, constraint-dependent choices | Test failure after review date | Very Low |
| ADR + linked fitness function | High-stakes decisions requiring both narrative and enforcement | Dual: CI + voluntary update | Low |
It is also worth acknowledging what this shift requires from engineering teams: a willingness to write architectural intent in executable form, and the discipline to link narrative records to their enforcement counterparts. Neither of these is trivial. However, crucially, neither relies on the assumption that future engineers will voluntarily maintain static documents — an assumption that the evidence, consistently, tells us is unreliable.
Ultimately, the question worth asking of any architectural decision is not “have we written an ADR?” but rather “will a future engineer know this decision exists, understand why it was made, and be warned if it is violated?” Only one of those questions has a reliable answer when the decision is coupled to the system that embodies it.
7. What We Have Learned
- ADRs fail primarily because they are static, point-in-time documents asked to perform a living-artefact function — a category error baked into the format itself, not a consequence of cultural laziness.
- Conway’s Law means org charts evolve faster than ADRs: team boundaries, ownership, and communication pathways that generated a decision change within months, rendering the record’s context obsolete.
- The maintenance burden falls structurally on the person with the least context — new joiners — while the engineers with genuine knowledge have already moved on. This guarantees decay regardless of team discipline.
- Stale ADRs are not merely unhelpful — they actively mislead engineers who read them and act on outdated reasoning as if it were current fact.
- Fitness functions (via ArchUnit or equivalent) couple structural constraints to CI pipelines, making violations impossible to ignore and removing the need for voluntary maintenance.
- Embedded decision comments with explicit “revisit if” clauses transform historical notes into active triggers, evaluated naturally by whoever next touches the relevant code.
- Expiry-triggered tests use the passage of time as a signal rather than a silent decay mechanism, forcing re-evaluation when the conditions that justified a decision have had time to change.
- ADRs remain valuable as supplementary narrative — for full context, post-mortems, and historical record — but should be linked to enforcement-coupled artefacts rather than standing alone as the primary knowledge carrier.
