Consider a composite of a failure pattern that’s becoming increasingly common on teams that have scaled AI-assisted development past a handful of enthusiasts.让我们来看看一种在团队中日益常见的失败模式，这些团队已经将 AI 辅助开发的应用规模从少数几个爱好者扩展到了整个团队。
A staff engineer named Priya opens a pull request. The PR is 340 lines and adds an endpoint that writes to the customer table directly, bypassing the internal customer service API. The code is clean. The tests pass. The AI coding agent that wrote it has been the team’s most productive contributor for six months. The reviewer, three months into the team, approves. The PR ships that afternoon.一位名叫 Priya 的资深工程师提交了一个合并请求（PR）。该 PR 包含 340 行代码，并增加了一个直接写入客户表（customer table）的端点，绕过了内部的客户服务 API。代码写得很整洁，测试也通过了。编写此代码的 AI 编程助手是该团队过去六个月中生产力最高的贡献者。入职三个月的评审人员批准了该 PR，当天下午代码就上线了。
Two weeks later, during an integration debug, someone notices that customer records written by that endpoint are missing audit-log entries. The audit hooks live in the customer service API. The team banned direct database access two years ago for exactly this reason and wrote an architectural decision record (a versioned markdown document, one of dozens the team has accumulated, that captured what was decided, why, and what was superseded) to memorialize the rule. The engineer who wrote the ADR has since left. Nobody on the current team remembered the decision. The document was sitting in a directory the current workflow never touches.两周后，在进行集成调试时，有人发现通过该端点写入的客户记录缺少审计日志条目。审计钩子（audit hooks）位于客户服务 API 中。团队两年前正是为了这个原因禁止了直接数据库访问，并为此编写了一份架构决策记录（ADR，一份带版本的 Markdown 文档，是团队积累的几十份文档之一，记录了决策内容、原因以及被取代的内容）来确立这一规则。编写该 ADR 的工程师已经离职，当前团队中没有人记得这项决策。该文档存放在一个当前工作流程从不涉及的目录中。
The endpoint gets rewritten. Audit gaps get backfilled. The team spends most of a sprint on cleanup. Nobody calls this a failure of AI-assisted development. The AI wrote functional code. It just wrote code that violated a decision the team had already made, in a document the AI had no view into.该端点被重写，审计漏洞被填补，团队花了一个冲刺周期的大部分时间进行清理。没有人称这是 AI 辅助开发的失败。AI 编写了功能正常的代码，只是它编写的代码违反了团队之前做出的决策，而该决策记录在 AI 无法访问的文档中。
This is a specific failure mode. It is not a hallucination since the output was grounded, syntactically valid, and idiomatic. It’s not a model-quality problem since a better model on that same prompt wouldn’t necessarily help if the decision remained absent from its context. It’s a memory problem. Not the model-internal sense of context window, but the organizational sense. The ADR was available in the repository. It was never surfaced to the agent, and the reviewer had not read it.这是一种特定的失败模式。它不是幻觉，因为输出是有据可依、语法正确且符合惯例的。这也不是模型质量问题，因为如果决策在模型的上下文中缺失，更好的模型也不一定能解决问题。这是一个记忆问题。不是模型内部的上下文窗口意义上的记忆，而是组织意义上的记忆。ADR 在仓库中是可用的，但从未展示给代理，且评审人员也没有阅读过它。
This piece is about naming what would need to exist for that PR to have been caught, or better, never written in the first place.本文旨在探讨如果想要捕获该 PR，或者更好的是，从一开始就避免编写出这样的代码，需要具备什么样的条件。
The rework signal返工信号
Priya’s PR illustrates one source of a broader rework problem. Faros AI, an engineering analytics platform, published a report in 2026 based on telemetry from more than 22,000 developers across 4,000+ teams. AI-code acceptance rates had risen from 20% to 60% between periods of low and high AI adoption, while code churn (i.e., lines deleted within days of being added) had increased 861% over the same interval.Priya 的 PR 说明了更广泛的返工问题的一个来源。工程分析平台 Faros AI 在 2026 年发布了一份报告，基于来自 4000 多个团队的 22000 多名开发人员的遥测数据。在 AI 采用率从低到高的期间，AI 代码接受率从 20% 上升到了 60%，而代码流失率（即在添加后的几天内被删除的代码行数）在同一时期内增加了 861%。
Faros is careful in how it frames the churn number. The increase may include not only rework but productive refactoring, previously unaffordable cleanup, or faster iterative improvement. But the number still exposes a gap between code entering the repository and code that survives there. A gap that has widened, at scale, alongside AI adoption. Anecdotally, engineers at teams running these tools describe returning to code they had already approved to fix issues that were not obvious at review time. Architectural drift, i.e., code that individually looks fine but collectively pulls the codebase away from where the team agreed it should go, is one plausible contributor.Faros 在表述流失率数据时非常谨慎。这一增长可能不仅包括返工，还包括富有成效的代码重构、以前无法进行的清理工作或更快的迭代改进。但这个数字仍然揭示了进入仓库的代码与最终保留在仓库中的代码之间的差距。随着 AI 的大规模应用，这一差距正在扩大。据传，使用这些工具的团队中的工程师描述说，他们不得不回到已经批准的代码中去修复在评审时并不明显的缺陷。架构漂移（即代码单独看起来没问题，但集体上使代码库偏离了团队预期的方向）是一个合理的促成因素。
I’ll call the discipline of preventing this failure mode architectural drift prevention: keeping generated code aligned with the architectural decisions a team has already made.我将预防这种失败模式的学科称为“架构漂移预防”：确保生成的代码与团队已经做出的架构决策保持一致。
The pattern-matching explanation for that gap has been that the AI isn’t good enough at writing code yet, and a better model will close it. Watch enough review cycles at a team running AI-assisted development for a year, though, and a different pattern emerges. The generated code isn’t obviously bad. It compiles. It passes tests. What it doesn’t do is respect decisions the team has recorded but the AI has never seen.对于这种差距，模式匹配的解释是 AI 编写代码的能力还不够强，更好的模型会缩小这一差距。然而，观察一个使用 AI 辅助开发一年的团队的评审周期，就会出现一种不同的模式。生成的代码并非明显很差，它能编译，也能通过测试。它所做不到的是尊重团队已经记录但 AI 从未见过的决策。
Why current tools sit at the wrong layer为什么当前的工具处于错误的层面
Teams commonly reach for several existing mechanisms to close this gap. Most of them are the wrong shape for the problem.团队通常会利用几种现有的机制来弥补这一差距。其中大多数对于解决这个问题来说形式并不对。
The closest attempts are files like Cursor Rules and CLAUDE.md, i.e., free-text markdown documents dropped into the project root so agents read them as standing instructions. These are the right instinct at the wrong resolution. Free text has no precedence rules, no versioning, no lifecycle. When one rule contradicts another, nothing arbitrates. When a rule is violated, nothing catches it. These are documents in the shape of configuration.最接近的尝试是像 Cursor Rules 和 CLAUDE.md 这样的文件，即放入项目根目录的自由文本 Markdown 文档，以便代理将其作为常设指令读取。这些直觉是对的，但分辨率错了。自由文本没有优先级规则，没有版本控制，也没有生命周期。当一条规则与另一条规则冲突时，没有任何机制进行仲裁。当规则被违反时，没有任何东西能捕获它。这些是以配置形式存在的文档。
Linters and code formatters operate a layer below. They enforce that a function has a return type annotation or that a variable name follows a convention. They can’t enforce that customer-data writes must go through the customer service API, because that’s not a syntactic property. It’s a semantic decision recorded in a document the linter has no reason to read.Linter 和代码格式化程序处于更低的层面。它们强制要求函数具有返回类型注解或变量名遵循某种约定。它们无法强制要求客户数据写入必须通过客户服务 API，因为这不是一个语法属性，而是一个记录在 Linter 根本没有理由去阅读的文档中的语义决策。
Dependency scanners, SCA tools, and lockfile audits close a related gap; they catch known vulnerable libraries, license violations, and outdated versions. They would’ve flagged nothing about Priya’s PR. Every dependency in it was current, had no known vulnerabilities, and was approved. The violation was a routing choice inside the team’s own architecture, not a library problem.依赖扫描器、SCA 工具和锁文件审计弥补了相关的差距；它们会捕获已知的易受攻击的库、许可证违规和过时的版本。它们不会对 Priya 的 PR 发出任何警告。其中的每一个依赖项都是最新的，没有已知的漏洞，并且经过了批准。违规行为是团队自身架构内部的路由选择，而不是库的问题。
LLM-assisted code review is the fashionable answer. A second AI reads the pull request and comments on it. This catches surface issues like a swallowed exception, an off-by-one bug. It doesn’t catch drift, however, because the second AI has the same problem as the first: no durable access to the team’s recorded decisions. Two probabilistic passes over the same blind spot are not one deterministic pass with sight.LLM 辅助代码评审是一个时髦的答案。第二个 AI 读取合并请求并进行评论。这可以捕获表面问题，如被吞掉的异常、差一错误（off-by-one bug）。然而，它无法捕获漂移，因为第二个 AI 与第一个 AI 面临同样的问题：无法持久访问团队记录的决策。对同一个盲点进行两次概率性的扫描，并不等于进行一次有视野的确定性扫描。
Human review is the last line, and it works when the reviewer knows the history and has enough time to inspect the change. Agentic development changes both conditions. Agents can produce multiple implementations, pull requests, and revisions in the time it takes a human reviewer to assess one. Code output scales; review attention does not. Asking humans to compensate by reviewing more and harder simply moves the constraint downstream.人工评审是最后一道防线，当评审人员了解历史并有足够的时间检查变更时，它是有效的。代理式开发改变了这两个条件。代理可以在人类评审员评估一个变更的时间内生成多个实现、合并请求和修订版本。代码输出规模在扩大，而评审注意力并没有。要求人类通过更频繁、更深入的评审来补偿，只会将瓶颈转移到下游。
None of these tools are bad. They’re just the wrong layer for the drift problem.这些工具本身都不坏，只是对于漂移问题来说，它们处于错误的层面。
What the missing layer would need to do缺失的层面需要做什么
The missing layer connects recorded engineering decisions to the tools that generate, review, and merge code. Its job is to make the team’s accumulated architectural decisions machine-readable, injectable, and enforceable. I’ll call this layer engineering governance, borrowing the term from adjacent categories like data governance and security governance, where it means the same thing: A structured way for an organization to make explicit and enforceable the rules it already implicitly follows.缺失的层面连接了记录在案的工程决策与生成、评审和合并代码的工具。其工作是使团队积累的架构决策变得机器可读、可注入且可强制执行。我将这一层面称为“工程治理”，借用了数据治理和安全治理等相邻领域的术语，在那里它的含义相同：一种组织将其实际隐性遵循的规则显式化和强制化的结构化方式。
At the shape level, the layer needs to do four things.在形态层面，该层需要做四件事。
- It needs to hold decisions in a structured corpus with precedence and lifecycle metadata so that a tool knows which ADR wins when two conflict, and which decisions are still active. 它需要将决策保存在一个具有优先级和生命周期元数据的结构化语料库中，以便工具知道当两个决策冲突时哪一个 ADR 胜出，以及哪些决策仍然有效。
- It needs to retrieve from that corpus reliably, so the same code produces the same set of relevant decisions each time. 它需要可靠地从该语料库中检索，以便相同的代码每次都能产生相同的一组相关决策。
- It needs to inject those decisions into the AI’s context before the agent writes code, so the output accounts for them rather than needing to be caught afterwards. 它需要在 AI 编写代码之前将这些决策注入到 AI 的上下文中，以便输出结果考虑到这些决策，而不是事后才去捕获。
- It needs to enforce them in continuous integration, blocking or flagging code that violates them, with the verdict traceable to a specific ADR, a specific term that matched, a specific rule.它需要在持续集成中强制执行这些决策，阻止或标记违反决策的代码，并能将判定结果追溯到特定的 ADR、匹配的特定术语或特定的规则。
The critical property that ties those four together is a discipline about where probabilistic reasoning is allowed. Probabilistic systems may retrieve or recommend. They shouldn’t independently determine an enforcement verdict. Every block or warning has to reconstruct from artifacts on disk. That’s the code, the ADR, the retrieval log, the rule text. Then, when a developer asks “why did this fail?” or an auditor asks “on what basis?” the answer isn’t “the AI said so.” That’s what makes the layer defensible in the situations where defensibility matters: regulated environments, compliance review, incident retrospectives, and the everyday conversation where an engineer has to justify a blocked merge to the person whose code was blocked.将这四点联系在一起的关键属性是关于在哪里允许概率推理的纪律。概率系统可以检索或推荐，但不应该独立决定强制执行的判定。每一个拦截或警告都必须能够从磁盘上的工件中重构出来。这就是代码、ADR、检索日志和规则文本。然后，当开发人员问“为什么会失败？”或审计员问“基于什么？”时，答案不是“AI 这么说的”。这就是使得该层面在需要可辩护性的情况下（如受监管的环境、合规性评审、事故回顾，以及工程师必须向代码被拦截的人解释原因的日常对话中）能够站得住脚的原因。
AI may help surface relevant decisions, but it shouldn’t be the final authority. The enforcement path must remain deterministic: every verdict should resolve to explicit rules, observable evidence in the code, and a result that another person can reproduce.AI 可能有助于浮现相关的决策，但不应成为最终权威。强制执行路径必须保持确定性：每个判定都应能解析为明确的规则、代码中可观察的证据，以及其他人可以复现的结果。
Defining the boundaries定义边界
Naming a category clearly requires naming what falls outside it. The engineering governance layer, done right, is not any of the following:清晰地命名一个类别需要明确什么不属于它。如果做得正确，工程治理层面绝不是以下内容：
- An agent. Nothing autonomous. Nothing iteratively deciding what to do next. The layer runs when called, produces a verdict, and stops.一个代理。没有任何自主权，没有任何迭代决定下一步做什么的行为。该层在被调用时运行，产生判定，然后停止。
- Memory in the retrieval-augmented-generation sense. Retrieval methods can vary and may be probabilistic; the enforcement verdict cannot. The corpus of decisions is the source of truth.检索增强生成（RAG）意义上的记忆。检索方法可以变化且可能是概率性的；强制执行的判定不能是。决策语料库是真相的来源。
- Code reviewed by AI. Reviewing generated code with a second model doesn’t address the underlying problem, which is that the first model had no access to the team’s decisions.由 AI 评审的代码。用第二个模型评审生成的代码并不能解决根本问题，因为第一个模型根本无法访问团队的决策。
- Vendor-locked. Production teams increasingly run Cursor, Claude Code, GitHub Copilot, and Codex in parallel, sometimes on the same repository. They may also use open-weight or self-hosted models for sensitive codebases and internal workflows. Engineering governance must remain independent of both the coding tool and the underlying model, so the same architectural decisions and deterministic enforcement apply across them all.供应商锁定的。生产团队越来越多地并行运行 Cursor、Claude Code、GitHub Copilot 和 Codex，有时是在同一个仓库上。他们也可能在敏感代码库和内部工作流程中使用开源权重或自托管模型。工程治理必须保持独立于编码工具和底层模型，以便相同的架构决策和确定性强制执行能够应用于所有这些工具。
The emerging engineering stack新兴的工程栈
The AI coding stack is assembling itself in the open, without anyone architecting it. Each of the major coding assistants is specializing on a different piece of the loop; editing, autonomous execution, review, planning. The layer this stack doesn’t yet have is engineering governance.AI 编码栈正在公开地自我组装，没有人进行架构设计。主要的编码助手都在专注于循环的不同部分：编辑、自主执行、评审、规划。这个栈目前缺失的层面就是工程治理。
The need isn’t limited to regulated industries. Any team that values reliable engineering, long-term product quality, and the trust of its customers needs to know that generated code respects the decisions the system depends on. In higher-risk environments, that requirement becomes formal and auditable. Elsewhere, it’s simply part of building software responsibly. In both cases, the enforcement path should be deterministic and traceable, with the rules, evidence, and verdict open to inspection rather than hidden inside another model or a proprietary black box.这种需求不仅限于受监管的行业。任何重视可靠工程、长期产品质量和客户信任的团队，都需要知道生成的代码尊重系统所依赖的决策。在风险较高的环境中，这一要求变得正式且可审计。在其他地方，这只是负责任地构建软件的一部分。在这两种情况下，强制执行路径都应该是确定性的且可追溯的，规则、证据和判定结果应公开透明，而不是隐藏在另一个模型或专有的黑盒中。
For engineering leaders reading this today给今天阅读本文的工程领导者
Priya’s PR is a pattern, not an incident. Three things worth doing this quarter, regardless of tooling choices.Priya 的 PR 是一种模式，而不是单一事件。无论工具选择如何，本季度有三件事值得做。
- Audit your architectural decision records. Are they current? Do they explicitly name the decisions they replace? If your team doesn’t write ADRs, this is the moment to start. The tooling that will exist in twelve months assumes structured architectural decisions as input.审计你的架构决策记录。它们是最新的吗？它们是否明确指出了所取代的决策？如果你的团队不编写 ADR，现在是开始的时候了。十二个月后将存在的工具将把结构化的架构决策作为输入。
- Choose the enforcement posture deliberately. The system can either warn the developer and let them continue or block the change until the issue is resolved. Both approaches can work, but the team should agree on which applies instead of leaving the decision to each developer or each pull request.审慎地选择强制执行姿态。系统既可以警告开发人员并让他们继续，也可以阻止变更直到问题解决。这两种方法都有效，但团队应该就适用哪种方法达成一致，而不是将决定权留给每个开发人员或每个合并请求。
- Don’t assume a more powerful model will solve this problem. Better models can improve the code they generate, but they still can’t follow architectural decisions they’ve not been given. Preventing architectural drift requires changing the surrounding system, not simply waiting for the next model.不要假设更强大的模型能解决这个问题。更好的模型可以改善它们生成的代码，但它们仍然无法遵循未提供给它们的架构决策。预防架构漂移需要改变周围的系统，而不是仅仅等待下一个模型。
The productivity gains from AI-assisted development are real and worth having. So is the architectural coherence teams spent years building. Engineering governance is the layer that lets you keep both.AI 辅助开发带来的生产力提升是真实的，也是值得拥有的。团队多年来建立的架构一致性同样如此。工程治理就是让你两者兼得的层面。
