TL;DR (about a 15-minute read)
In May 2026, I was reworking a Claude Code plugin that delivers a shared way of working to several develo...
For further actions, you may consider blocking this person and/or reporting abuse
Splitting it into existence, reading and following keeps the claim honest, since the hook only owes the first. With 30 of 107 Accepted or Amended ADRs emitted, the index itself becomes the thing that goes stale: the later decisions are the ones that fall off. Is the cap fixed at 30, or does it scale with how many decisions touch the files in play?
That is a sharp point. I agree that existence, reading, and following are separate guarantees; the hook can directly guarantee only that relevant ADRs are surfaced. In the implementation described here, 30 is a fixed safety cap, but the list is not simply truncated by age. Candidates are ranked using path matches to the changed files, tags, and dependencies, and the highest-ranked ADRs are injected. Important ADRs can still be missed, so as the ADR set grows, I think this should evolve from a fixed count to relevance selection within a token budget, with on-demand follow-up retrieval when needed.
Fair correction, I had assumed it cut by age. Ranking by path match, tags and dependencies is a much better cap. The budget version sounds right, and on demand retrieval matters most for the decisions that rank low because they touch no changed file but still constrain the change, like a rule about an interface the edit calls into.
Exactly. Direct relevance to changed files alone can miss ADRs that define contracts or boundary conditions for the interfaces being called. In the next step, I think retrieval needs to expand from the diff through callees, public APIs, and dependencies, then re-evaluate even low-ranked candidates as potentially constraining ADRs. On-demand retrieval looks less like a fallback and more like the core mechanism for handling these indirect constraints.
That framing makes sense to me. One caution on expanding from the diff: walking callees and dependencies can pull in most of the ADR set on a busy module, so the budget fills before the indirect ones get a look. Tagging each ADR with the interfaces it constrains would let the walk stop at those boundaries instead of following every edge.
Thanks. Using interfaces as boundaries for traversal sounds like a useful way to avoid exhausting the budget by following too many dependencies.
But as the ADR set grows, I’m finding that relevance filtering alone isn’t enough. A highly relevant ADR may already have been superseded, and the AI may bypass the index and read an old ADR directly.
So I think the index needs to capture not only which interfaces an ADR constrains, but also whether the decision is still in effect and what supersedes it. I also want to enforce a retrieval path where routine work draws on current constraints, while historical ADRs are retrieved when investigating the reasoning behind past decisions. I don’t think written instructions alone are reliable enough to ensure that.
Your boundary-tagging suggestion seems useful for designing that retrieval path. And we would still need checks to ensure that “not in the index” is never treated as “no constraint exists.”
Nice write-up. One thing I'd add from building something similar: the rejected alternatives in an ADR matter as much as the decision. Agents rarely ignore the chosen approach outright. They drift back to the option you already ruled out, so injecting "we tried X, dropped it because Y" tends to stick better than the decision alone. Curious how you pick which ADRs to inject per prompt, path matching or something semantic? I built a Mac app around the same problem, Deiko, which files each brief into its task so a new chat sees what was tried and decided. deiko.app
Thank you. I strongly agree that rejected alternatives and their rationale need to be included. When I provide only the decision, the model often re-proposes a plausible option that was already considered and ruled out. In my ADR summaries, I keep the chosen approach, rejected alternatives, and rejection reasons at the same level of detail.
For selection, I use two stages: first I narrow candidates by the files being changed and the ADR scope (directories, components, and tags); then I rank them by semantic similarity between the task text and ADR summaries. I also give extra weight to recency and unresolved constraints. I’ve found that injecting a few top-ranked ADRs with concise rejection reasons is more reliable than injecting every ADR. I also really like Deiko’s task-level approach to preserving what was tried and decided. Thanks for sharing it.
The part about "delivering existence" vs "reading bodies" is exactly where I've seen teams stop and declare it done. We had something similar where a list of available tools was injected at session start and the agent still kept picking the wrong ones, which took a while to debug because the list was definitely in the context. I'd never thought about the cap dropping by number order meaning newer decisions fall off first, but that's a real problem since the newest ADRs are usually the ones most likely to conflict with a fresh suggestion. Thanks for being clear about what the hook can't guarantee.
Exactly. Information merely being present in the context is different from the model actually consulting and using it correctly in its decision. Your tool-list case also shows why verifying presence alone is not enough; we need to verify that the descriptions, priorities, and constraints needed at selection time are reaching the model. ADRs are similar: once a cap is reached, retention should not be based on simple ordering, but on freshness, conflict potential, and relevance. I’ll keep improving this with the understanding that a hook prepares the conditions—it does not guarantee compliance itself.