An ADR is only as good as what actually reads it

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.