Theo Valmis 分析 AI 编码代理的架构决策何时真正适用

O'Reilly Radar· Theo Valmis·2026-10-13 19:02· 2 小时前AI 评分50

架构决策何时真正适用

AI 导读

Theo Valmis 在 O'Reilly Radar 撰文指出，AI 编码代理的架构治理需要区分相关性与权威性、引导与强制两类界限。

正文

在我上一篇 Radar 文章“AI 生成代码的架构护栏”中，我提出 AI 编码代理需要一个层，能够将架构决策保存在结构化语料库中，检索出相关决策，在代理编写代码之前将其放入代理的上下文中，并通过可复现的检查来强制执行明确的约束。对该模型进行测试后，暴露出我此前混为一谈的两个区别。

因为某个决策相关而检索到它，并不意味着该决策适用于正在被修改的产物。
一个确实适用的决策，并不自动适合进行确定性强制执行。

第一个区别是相关性与权威性之间的区别；第二个是引导与强制之间的区别。

下面是一个受控代码库如何让这一区别变得清晰的故事。该项目在其当前阶段使用本地 JSON 支持的持久化，而一项生效的架构决策排除了该命令行应用程序使用 PostgreSQL、ORM 和数据库迁移。任务要求编码代理修改该应用程序的存储模块，因此该决策不仅仅与一般意义上的持久化相关；它对代码库中被修改的那部分具有权威性。该记录被成功检索到，并在工作开始前放入了代理的上下文中。

代理仍然提出了 PostgreSQL，以及一个 ORM 和一条迁移路径。按照我最初的四种能力模型，这乍看像是检索失败。但并非如此。该决策被找到了，是当前有效的，并且在正确的时机到达。缺失的是一个适用性信号，用来告诉系统：该决策管辖的是正在被编辑的存储模块，而不是作为又一份相关文档供模型与附近代码及其他上下文进行权衡。

检索负责发现；适用性负责管辖

检索帮助我们确定哪些架构决策可能与某项任务相关。这是一个搜索问题，团队拥有越来越强大的解决方式：索引化代码库、互联文档、公开的决策记录和服务目录、语义搜索以及项目记忆。这些技术帮助代理在编写代码之前看到有用的材料。但它们本身并不能回答另一个问题：这些决策中，哪一个对代理面前的变更具有权威性？

假设一个代码库包含两项持久化决策。一项要求分析服务使用 PostgreSQL；另一项要求命令行工具使用本地文件存储。如果代理正在编辑命令行工具的存储模块，那么对于关于持久化的查询，两项决策可能都排名很高，但只有本地存储决策适用于该产物。确定哪项决策管辖该变更，需要范围、生命周期、优先级，以及一份清晰的记录，说明哪些决策取代了更早的决策。我在上一篇文章中主张优先级和生命周期；范围同样值得关注，因为范围正是告诉系统某项决策在何处具有权威性的东西。

一个相关的问题是，架构信息通常分散在多种文档中。人类知道，一份旧的设计笔记、一份 README、一份已接受的架构决策记录，以及一份当前的平台标准，即使四者讨论的是同一主题，也未必具有同等的权威性。除非系统保留这种区分，否则模型并不知道这一点。当这些来源被扁平化到同一个上下文窗口中时，它们之间的层级关系可能会消失。我把这称为权威扁平化：信息仍然可用，但关于哪些信息具有约束力的信号变弱了。当设计问题确实尚未有定论时，这很有用；而当团队已经回答了该问题时，这就存在风险。

关于架构决策违规的研究指向了类似的边界。Su 及其同事在 2026 年的一项研究考察了 109 个开源代码仓库中的 980 份 ADR。当决策是明确的、且可从代码中推断出来时，模型表现很强，但当合规性取决于部署配置或组织知识时，模型的准确性就会下降。该研究评估的是代码编写完成后的违规情况，而非生成之前的指导，但潜在的局限性是相似的：当适用性或权威性仍然隐含时，模型可以检索到正确的文档，却仍然做出错误的架构选择。

范围发生了什么变化

我在一个小型对照实验中测试了这一区分，实验使用了七个编码任务，在两种条件下重复进行，使用相同的编码智能体和模型配置。在一种条件下，智能体在没有相关架构指导的情况下工作；在另一种条件下，在它开始修改代码之前就提供了架构决策。独立评审员评估了两种条件下的首次尝试，考察架构合规性以及所请求的工作是否实际完成。指导改变了行为：在架构敏感任务上，首次尝试的合规率从 15 次运行中的 6 次提高到 15 次中的 10 次，而任务成功完成率基本没有变化。

更有趣的结果是受指导条件下出现的一次失败。在几个身份验证任务中，智能体收到了一项与周围问题确实相关的存储相关架构决策，然后实施了任务从未要求的额外持久化工作。该决策本身没有问题，检索也发挥了作用。相关性被呈现出来，却没有附带关于权威性的足够信息。这个实验明确了两个限制：一项决策可以具有相关性，却不约束正在被修改的制品；而且即使是一项具有约束力的决策，也不授权智能体扩大任务范围。适用性告诉系统一项决策可能在何处约束工作；它并不是凭空发明更多工作的许可。

阻止比引导更容易

第二个区分迫使我修改了原始模型中的另一部分。上一篇文章强调了确定性执行：当团队已经做出明确决策，并且可以从可观察证据中识别出违规时，阻止性判定应来自可复现的规则，而不是模型的判断。我仍然认为这是阻止的正确标准。重要的限定条件是，只有一部分架构决策能够在不假装判断已变成确定性的情况下满足这一标准。

“不要在这个组件中引入 SQLAlchemy”作为一条规则相对容易表达、容易检查，也容易阻止。“正确使用现有的持久化抽象”则不同。它的含义大多是架构性的，而非语法性的：正确的实现取决于意图使用哪个抽象、它在系统这一部分中如何被使用，以及周围已经生效的约束是什么。第一句话描述的是一种可以合理成为确定性控制的禁令。第二句话描述的是一条被认可的实现路径，除非团队能够把相关证据和边界精确化，否则更适合作为指导。

此前关于预生成指导的实验也指向同一方向。添加更多与架构相关的上下文并不能可靠地改善行为，因为缺失的往往不是又一条禁令，而是对可接受的实现路径更清晰的描述。一个完全围绕阻止构建的护栏层会非常擅长说不。有用的架构治理必须同时完成两项工作：在证据足够精确时阻止已知的违规，并为仍然需要解释的更大一类决策提供正向的架构方向。

当判断变成权威

这并不会削弱模型的作用；它把概率性推理放在有用的地方。模型擅长解释：阅读含糊的指导、浮现可能与某项变更相关的决策、解释边界违规的后果，以及提出如何让变更重新符合预期设计。确定性逻辑更适合团队已经确定、并且能够用检查可以复现的方式表述的决策。错误在于要求任一机制同时完成这两项工作。

一旦系统说某项提议的变更违反了架构规则，标准就变了。工程师应该能够问：适用的是哪项决策，为什么它适用于代码库的这一部分，是什么证据触发了该结果，以及另一位开发者运行同样的检查是否会得到相同答案。这并不要求架构的每一部分都变成正式策略。它要求围绕允许不确定性的地方划出清晰边界：模型可以帮助发现和解释架构上下文，但阻止性决策最终不应归结为“模型觉得这看起来不对”。

人类日常就在架构模糊性中工作。我们权衡不完整的证据、局部上下文和相互竞争的取舍，往往使用启发式而非正式规则。模型也可以帮助完成这种解释性工作，但结果仍然是概率性的。问题始于把模糊的判断当作阻止性规则。确定性执行要求边界足够精确，以至于相同的证据产生相同的裁决。

当一个团队同时使用多个编码工具时，这一区分更加重要。一位开发者可能使用 Claude Code，另一位使用 Codex，还有一位使用 Cursor，同时自动化代理执行后台维护。模型和检索机制可能不同，但团队的架构不应随工具而改变。一组共享的决策可以作为权威来源置于这些环境之下，而每个工具以自己的方式消费指导，可执行的那部分子集则被一致地检查。

我会对原始模型补充什么

我现在会在两处修改最初的四种能力模型。

检索应当浮现候选决策，而适用性则结合范围、生命周期与优先级，决定其中哪些决策真正约束当前的产物或行动。随后，指导与强制执行应保持为两种不同的结果：有些适用的决策足够精确，可以支持确定性控制，而另一些则应影响实现，而不必成为二元规则。

这种分离让智能体在架构真正开放之处自由推理，同时在团队已做出决策之处保留权威。它也避免了一种常见的过度纠正。一旦团队看到某些架构可以自动强制执行，就会忍不住把所有东西都形式化。大量架构仍然是判断。“保持领域边界狭窄”或“在不需要即时一致性时优先采用异步集成”可以是有价值的指导，却不是适合自动阻断的安全材料。系统行使的权威级别应取决于决策的精确度以及可用于评估它的证据。

多年来，架构治理主要依靠人工流程：有人撰写决策记录，架构师审查重要变更，经验丰富的工程师把部分历史记在脑中，代码审查则捕捉一些漏网之鱼。AI 编码智能体改变了这一流程的经济性，因为实现的速度现在可能快于架构意图被重新解释和人工重新审查的速度。给智能体更多上下文是必要的，但并不充分。更难的工作是保留以下四者之间的区别：可能有用的信息、实际适用的决策、应当塑造实现的指导，以及精确到足以阻止某个实现的约束。

目标不是约束智能体做出的每一个选择。而是阻止团队已经做出的决策悄悄变回建议。这需要的不仅仅是检索到正确的文档。系统必须知道该决策是否仍然有效、它在何处拥有权威，以及团队意图让它拥有何种权威。

来源：O'Reilly Radar · oreilly.com