记录找到了，是现行的，也在写代码之前进了上下文。Agent 还是提出了 PostgreSQL、ORM 和一条迁移路径。
那个仓库有一条生效的架构决策，排除的正好是这三样。任务要求改存储模块，检索命中了决策，时机也对。按上一篇文章的四能力模型，这应该是一次成功案例。
Theo Valmis 在 O’Reilly Radar 的新文章里给出了解释：检索本身没有出错。缺的是一层 applicability signal，告诉系统这条决策管辖正在编辑的存储模块，而不是又一份供模型与附近代码权衡的相关文档。
我认同这个诊断，但想再往前推一步。适用性很难写成决策文档里的一个字段。它更像是决策与一次具体变更之间的关系，需要算出来。算的时候要看这次 diff 碰了哪个产物、决策是否现行、团队授予它多强的权威。少算一项，决策就会以两种方式失效：该管的没管住，或者不该管的被当成了扩权许可。
检索成功，为什么还是没生效
Section titled “检索成功，为什么还是没生效”先把检索和管辖分开。
检索回答的是“哪些材料可能和这个任务有关”。索引仓库、连上文档、暴露 ADR 和服务目录、语义搜索、项目记忆，都在做这件事。它们让 agent 在写代码前看到有用的东西。这个能力这段时间进步很快，也容易让人误以为问题已经解决。
管辖回答的是另一个问题：这些材料里，哪一条对眼前这次修改有约束力。
原文举了一个很干净的对照。仓库里有两条持久化决策，一条要求分析服务用 PostgreSQL，一条要求命令行工具用本地文件。现在改的是命令行工具的存储模块。两条决策在“持久化”这个查询下都可能排得很前，但只有本地文件那条管得着。
判断谁管得着，需要三样东西：作用范围、生命周期、优先级。上一篇文章已经讲了后两样，这篇补的是范围。范围决定一条决策在哪里有权威。
麻烦在于，架构信息从来不是以决策的形式整齐存放的。旧设计笔记、README、已经接受的 ADR、当前平台标准，可能讨论同一个问题。人知道这四者的权威不一样，模型不知道，除非系统把这个区别保留下来。把它们一起塞进上下文，信息还在，层级没了。Valmis 把这叫 authority flattening，权威扁平化。
这个说法很容易被读成“上下文不够大”。其实相反。设计问题真的开放时，扁平化是好事，更多材料意味着更多视角。团队已经回答过这个问题时，扁平化是坏事，因为旧笔记和已生效的 ADR 又回到了同一起跑线。
Valmis 自己做了 7 个编码任务的对照实验。同一个 agent、同一套模型配置，一组不给架构指导，一组在改代码前给。独立评审看第一轮合规率：架构敏感任务从 6/15 提升到 10/15，任务完成率基本没变。
这组数字说明指导有用，也说明指导不够。它没有回答“为什么决策在场，行为还是偏了”。答案要到后面那次认证任务里找。
Su 等人在 2026 年做的一项研究，从另一侧碰到了同一堵墙。他们分析 109 个 GitHub 仓库里的 980 条 ADR，让多个模型判断代码是否违反架构决策。对显式、能从代码里推断的决策，模型的一致性和准确率都不错；一旦合规依赖部署配置或组织知识，准确率就掉下来。
这项研究评估的是代码写完之后检测违规，不是生成之前提供指导，引用时得保留这个区别。但它和 Valmis 的实验指向同一个方向：模型可以拿到正确的文档，仍然做出错误的架构选择，只要“这条文档对我有没有约束力”还是隐式的。
管辖权属于变更，不属于决策
Section titled “管辖权属于变更，不属于决策”把范围写进 ADR，是必要的第一步。很多团队连这一步都没有。但只有范围字段还不够。
一个路径 glob 能说明一条决策可能在哪里生效，不能说明它对这次修改是否生效。任务描述说“认证”或“存储”，那只是话题相关。决定管辖的是这次变更碰了哪里：改了哪些文件，动了哪条依赖边，碰没碰部署配置，修改的是接口还是实现。
举个具体的。一条决策写着“存储层不得直接依赖 ORM”。这次 diff 只改了认证模块里的一个 token 校验函数，没有碰存储层。检索系统看到任务描述里有“持久化用户会话”，可能把这条决策排得很前。它相关，但它不管辖这次修改。把它当约束注入，轻则浪费上下文，重则让 agent 在认证模块里做一次没有必要的存储层重构。
反过来，这次 diff 改的是 src/storage/ 下的仓库实现，任务描述却只写“修复登录失败”。话题上完全没提存储，决策仍然管辖。只看任务文本，这次就会漏掉。
所以适用性最好对着变更集算，而不是对着 prompt 算。做法不复杂：把每条决策的范围解析成一组仓库内产物，和本次 diff 触碰的产物求交集，再用生命周期和优先级筛掉被取代的决策。交集为空，它就是背景材料；交集非空，它才进入管辖集。
这也解释了为什么“把所有 ADR 塞进 CLAUDE.md”通常会失望。它提高了召回，却没有提高权威信号。材料越多，模型越难分辨哪一条是团队已经拍板的，哪一条只是某个季度的设计草稿。上下文变长之后，哪条算数反而更难分辨。
适用不是扩权
Section titled “适用不是扩权”原文里还有一次失败，读的时候很容易被前面的 PostgreSQL 盖过去。
在若干认证任务里，agent 拿到了一条存储决策。这条决策和周边问题确实相关，检索没有错，决策本身也没有错。agent 随后实现了任务从未要求的额外持久化工作。
Valmis 的总结是：适用性告诉系统一条决策可以在哪里约束工作，它不是发明更多工作的许可。
我想把这个边界说得更硬一点：管辖是一条双边约束。一条决策既规定“这里必须听我的”，也规定“除此之外不归我授权”。绝大多数 ADR 只写前一半。它们写适用范围、约束条件、决策理由，很少写“这条决策不构成对相邻模块的施工许可”。
后一半缺失时，agent 很容易把“这条决策相关”读成“这个方向可以顺手多做一点”。代码能编译，测试能过，任务看起来也完成了，只是范围悄悄扩大了一圈。这类失败不会在 CI 里报警，因为没有任何一条规则被违反。问题出在授权被误读，约束并没有被突破。
工程上可以做一件很小的事：注入决策时，连同它的非目标一起注入。比如“这条存储决策适用于 src/storage/，它不授权在认证流程里新增持久化”。一句话，成本很低，但它把“相关”和“可以多做”切开了。
更形式化地说，适用性过滤约束，不生成任务。允许的变更集取任务意图与决策约束的交集，别把它扩成任务意图与决策领域的并集。这个区别在人类评审里靠经验维持，在 agent 工作流里必须写成数据。
阻断权只发给仓库看得见的决策
Section titled “阻断权只发给仓库看得见的决策”原文第二个区分是 guidance 和 enforcement。一条决策可以适用，但不一定适合做确定性强制。
“不要在这个组件引入 SQLAlchemy”容易表达，容易检查，也容易阻断。它描述的是一个禁令，检查器只要看依赖和 import 就能给出裁决。“正确使用现有持久化抽象”完全不同。它的含义主要是架构性的：哪个抽象、在这个系统部位怎么用、周边还有哪些约束在生效。把它写成规则，写出来的多半是规则的影子，不是规则本身。
我想把这里的判据再收紧一点：只有 closed-world 的决策才配拿到阻断权。
Closed-world 的意思是，违规可以从仓库里看得见的工件判定：代码、配置、依赖清单、锁文件、规则文本。换一个人、换一个工具、换一台机器，跑同样的检查，得到同样的结果。Open-world 的决策依赖仓库之外的状态：部署环境怎么配的、值班的人知道什么、组织上谁同意过。这类决策可以指导实现，但不能在 CI 里冒充确定性裁决。
Su 等的研究正好标出了这条边界。模型准确率掉下去的地方，就是部署配置和组织知识。问题不在模型的聪明程度，而在证据根本不在仓库里。用一个概率判断去补这个缺口，再把判断包装成阻断，等于把不确定性藏进了裁决。
所以权威应该分级，而且升级要有条件：
- 信息：可能相关，供参考。
- 适用决策：范围与本次变更相交，现行且优先级最高。
- 指导：适用，但违规无法从仓库工件稳定判定。它塑造实现方向，不产生阻断。
- 阻断约束：适用，且违规可由 closed-world 谓词复现。它才拥有说不的权力。
很多架构决策会停在第三级。停在第三级并不意味着这套系统失败。原文有一句话很重要：完全围绕阻断建的治理层，会非常擅长说不。它没展开的是，一个只会说不的系统，团队迟早会绕开。禁令从来不缺。缺的是对“被认可的落地路径”的清楚描述。
模型在这里仍然有用，而且用处很大。它擅长读模糊的指导、找出可能相关的决策、解释越界的后果、提出回到设计意图的改法。它不适合做的，是最终裁决。系统一旦说某次修改违规，工程师应该能问：哪条决策、为什么适用于这部分代码、什么证据触发、换个人跑是否同样结果。如果答案最后落在“模型觉得不太对”，那还不是权威，只是意见。
这和我昨天在《把信任建在模型外面》里读到的安全思路落在同一条线上。安全上，不要让模型成为最后一道防线；架构治理上，也不要让模型成为最终裁决者。区别只是前者守的是攻击面，后者守的是团队已经做过的决定。
管辖元数据自己也会过期
Section titled “管辖元数据自己也会过期”原文没有展开的一层，是适用范围本身的腐烂。
一条决策写着“适用于 src/persistence/”。过一阵子目录改名，服务拆开，模块合并。决策文本还在，生命周期还是 active，优先级也没变，但它指向的路径已经不存在。这条决策从“管着这块代码”滑到“管着一块不存在的代码”。
这种失效不会以违规的形式出现。它不会在 code review 里冒出来，也不会让任何测试变红。它只是让一条本来有约束力的决策，安静地退回成一条历史记录。
所以适用范围需要自己的检查，像链接检查一样：
- 每个范围条目必须能解析到仓库里真实存在的产物。路径没了，检查失败。
- 每条 active 决策至少要被一个检查引用，或者被显式标记为 guidance-only。没有任何检查、也没有任何指导落点的决策，只是一份存档。
- 决策被取代时，旧决策的范围要一起下线。只改 status，不改范围，旧范围还会继续匹配。
这套检查并不复杂，难的是有人认领它。ADR 通常由写决策的人维护，范围却随着代码结构变化。写决策的人走了，范围就没人管。上一篇文章里那个 Priya 的案例，ADR 的作者离职后整条决策从工作流里消失，是同一个问题的另一种表现。
我自己维护的这个仓库，有一层很朴素的治理：根目录的 AGENTS.md 被定义成 repository-wide AI Agent governance 的唯一共享权威源，src/content/ 下有路径级的 AGENTS.md，Skills 分了自建、托管、vendored 三种生命周期，发布前跑 npm run verify。这已经是一个小型权威阶梯：文档负责指导，脚本负责强制。
但路径级文档只有范围，没有机器可读的优先级。两处规则冲突时，没有东西仲裁。verify 能挡住格式、链接、构建和性能预算，挡不住“这条内容不该放在这个分类”这类判断。这个仓库并不特殊。它只是把原文的两个区分摆在了明面上：范围写了，管辖未必算得清；检查有了，权威未必到得了那一级。
我在《Agent 越能写代码，架构越不能乱》里把 harness 说成墙，也说成路标。读完这篇，我想给路标补一句话：路标得写清楚自己管哪段路，以及什么时候作废。否则墙还在，路已经改道了。
Valmis 的文章没有给出完整的实现方案，它给的是一个更准确的失败分类。这比又一套架构治理工具更有用。大多数团队缺的是分清三种东西：一份可能有用的资料，一条适用于这次修改的决策，一条精确到足以拦住提交的约束。
这三者的区别，最终会落到三个问题上。这条决策现在还有效吗？它对这次变更的哪一部分有管辖权？团队当初想让它有多硬的权威？
三个问题都有答案，上下文里的那份文档才算生效。答不上来，塞进去的只是又一份参考资料。Agent 会读它，会引用它，也可能在下一行代码里绕开它。
- When Architecture Decisions Actually Apply，Theo Valmis，O’Reilly Radar，2026 年 10 月 13 日
- Architectural Guardrails for AI-Generated Code，Theo Valmis，O’Reilly Radar，2026 年 8 月 31 日
- Evaluating Large Language Models for Detecting Architectural Decision Violations，Ruoyu Su 等，2026 年
- Theo Valmis 作者页