---
title: An ADR is only as good as what actually reads it
description: A decision record that only lives as prose is something an agent has to be told to go open. The ones that survive are the ones also wired into a table, a script, or a test the agent's normal workflow already touches.
date: 2026-09-22
area: development
tags:
  - architecture
  - patterns
  - claude-code
draft: false
---

Two of my own projects, with no shared codebase and no shared team, independently landed on the
same shape for architecture decision records: the ADR folder is not the mechanism that makes a
decision stick. Something downstream of the ADR, a table a script reads, a test that runs on every
CI job, is. Writing a decision down in `docs/adr/` and telling an agent to check it before touching
a file is necessary and not sufficient. An agent, like a person, only reliably checks what its
normal workflow already puts in front of it.

## The tier map is the decision, not a summary of it

One project is a QA plugin whose maintainers are not programmers. An early ADR splits every file in
the repo into three change tiers, and states the design choice that actually matters in one
sentence: the tiers are "documentation in `docs/runbooks/README.md` and simultaneously data, the
`TIERS` table in `scripts/verify_change.py`, so the boundary is machine-checkable rather than a
paragraph people are trusted to have read." That's not a wiki page describing a policy. It's a
Python dictionary the verification script actually imports, and the same dictionary the maintainer
runbooks render as a table. A maintainer, or Claude running a maintainer skill on their behalf, gets
the tier classification for free from the tool they were already going to run. Nobody has to
remember the ADR exists, because the ADR's conclusion is sitting in the code path they're already
executing. Even the fallback is a recorded decision made mechanical: a file the map doesn't
recognize is treated as red on purpose, so an unclassified path defaults to "ask a human" instead of
silently defaulting to "assume it's fine."

## A rule enforced by a failing build outlives a rule someone has to recall

A second project has an ADR banning a pattern outright: no agent may call another agent directly:
one orchestrator delegates to sub-agents, and sub-agents don't chain to each other. That's a
sentence a future contributor, or a coding agent working from stale muscle memory, can simply
forget exists. So the migration that established the rule shipped an automated test that fails the
build if it detects any import of the old hand-rolled agent framework anywhere in the coordinator.
The test doesn't check that new code is good. It checks that the banned pattern is gone, and stays
gone, every time CI runs. Nobody has to have read the ADR for the rule to hold. The build simply
turns red, and the failure message is the pointer back to the decision.

## Why "tell Claude to check the ADRs" isn't the fix

Pointing an agent's instructions at `docs/adr/`, a line in `CLAUDE.md` saying "check the ADRs before
touching X," works only as well as an agent's discipline about following an instruction that
nothing enforces. That's the same failure mode as expecting a human maintainer to remember a wiki
page exists. Neither example above relied on an instruction to go read the ADR folder. The
decision's consequence showed up in the exact file the agent was about to edit, or the exact command
that already runs on every change.

None of this is an argument against writing the prose down. The same tiered-QA project's founding
ADR rejected two alternatives for a reason worth keeping: a ticket tracker, because "acceptance
criteria are not rationale," and a single running decisions document, because a shared file produces
merge conflicts and "no way to mark one decision superseded without editing around others." The
prose is where the reasoning survives, the part a table or a test can never carry on its own. What
the table and the test add is that the current answer is inescapable without anyone, human or agent,
having read that reasoning first.

The question worth asking of any ADR before it ships isn't whether it explains the decision well.
It's whether anything in the codebase actually breaks, or reads differently, the moment the decision
quietly stops being true. If the honest answer is "only if someone happens to open the file," the
decision isn't finished being made. It's just been written down.