2025 年的一项对照实验让有经验的开发者使用了 AI 编码工具，并测量他们是否变得更快。开发者们预测效率会提升 24%。研究结束后，他们报告自己大约快了 20%。而客观测量显示，他们实际上慢了 19% 。
这并不是一个关于 AI 过度炒作的故事。这是一个关于隐性知识的故事——那种存在于每个成熟代码库中、仅靠阅读代码无法恢复的、无文档记录的"为什么"。AI 智能体在全新系统中生产效率出奇地高，正是因为那里几乎没有隐性知识可以违反。它们在成熟代码库中退步，原因完全相同。
隐性知识在代码库中的真实含义
迈克尔·波兰尼的观察——"我们能知道的比我们能说出来的更多"——在软件工程中有着显而易见的应用。一位在她维护了三年的系统中工作的资深工程师，掌握着永远不会出现在任何文档中的知识：
这个缓存层假设单写者语义（single-writer semantics）的不变量，这就是为什么模块中任何地方都没有比较并交换（compare-and-swap）锁（添加它们在语法上是"正确的"，但会引入幽灵争用）。
auth 中间件被构建为三层而非两层的原因，这是 2022 年一次涉及跨会话边界令牌重放事件后的刻意决定。
这个看似冗余的二级索引之所以存在，是因为 2021 年的一次 ORM 迁移损坏了主键空间，删除它会悄悄破坏三份季度报告。
这些事实都不会出现在代码注释中。它们存在于旧的 pull request 讨论串中、早已归档的 Slack 对话中、某人在 2022 年写下但从未从任何地方链接过的 Notion 页面中，以及当时在场的工程师脑海中。
当 AI 智能体读取这个代码库时，它看到的是模式。它看不到决策。它无法区分代码之所以如此结构是出于约束，还是出于偶然。它默认使用统计上最常见的解法——这在全新代码中通常是正确的，而在这里通常是错误的。
失败模式是系统性的，而非随机的
AI 编码智能体在成熟代码库中以可识别的方式失败。这些不是一次性的 bug，而是将统计模式匹配应用于具有隐式约束的代码库所产生的可预测后果。
能编译的约束违反。 AI 建议通常在语法上是正确的，能通过类型检查，却违反了一个从未被编码进类型系统的不变量——因为团队不知道他们需要这样做。代码上线了，不变量被打破了，失败模式在数月后的生产中才显现出来。
回退到常见模式的默认行为。 当面对一个不寻常的架构——一个围绕非显而易见约束构建的架构——AI 会默认使用其训练数据中最常见的等效模式。运行事件溯源系统的团队会发现 AI 建议引入了可变状态。有严格幂等性要求的团队会发现 AI 建议引入了副作用。
复制粘贴放大。 GitClear 对 2.11 亿行代码的分析发现，2024 年是 AI 辅助代码库中复制粘贴行首次超过重构行的一年。AI 智能体在不理解这些模式是刻意为之还是偶然形成的情况下，就对其进行复制。随着 AI 大规模复制，偶然性模式被奉为典范。
违反反直觉约束。 对约束代码生成的实证研究发现，与常见训练数据模式相匹配的约束能达到 99% 以上的合规率；而与常见模式相悖的约束失败率在 10% 到 100% 之间。像"始终在边界处验证用户输入"这样的约束很常见，AI 会遵循。而"永远不要在应用层验证，因为我们的负载均衡器已经过滤掉了无效输入"这样的约束很不寻常，AI 会违反它——因为它所见过的每一个训练样本都在应用层进行验证。
实际后果是：你无法通过添加更多注释或在针对单个建议的提示词中表达得更清楚来解决这个问题。问题是结构性的：支配约束相关决策的知识不在代码库中。
18 个月的瓶颈 采用 AI 编码工具的团队通常会报告一个可预测的轨迹：第一到三个月带来真实的效率提升，第四到九个月随着集成复杂性的出现进入平台期，第十六到十八个月则出现更糟糕的情况：团队不再能完全理解自己的系统。
这不是巧合。这是研究者所称"理解债务"（comprehension debt）的累积——代码能运行，但维护它的人却不理解它。人类编写的技术债务是因为开发者走捷径而积累的；AI 生成的技术债务是因为 AI 在每个决策点都嵌入了未声明的假设而积累的。到第二年，不受管理的 AI 生成代码的维护成本可能达到基线的四倍。
这一机制是可识别的。AI 生成的代码往往比同一代码库中人类编写的代码具有更高的圈复杂度、更多的过度 I/O、更多的复制粘贴模式，以及更弱的并发管理。Ox Security 对 300 多个代码库的分析发现，80% 到 100% 的 AI 生成代码中存在十种反复出现的反模式。这些不是随机的——它们是针对"能编译且通过测试的代码"而非"符合此代码库隐式契约的代码"进行优化的产物。
有帮助的知识捕获模式 实际问题不是是否使用 AI 编码工具，而是你是否已经将足够多的隐性知识显式化，以使这些工具能在你的代码库中安全运行。
架构决策记录（ADR）。 ADR 记录四件事：上下文（存在什么问题）、决策（选择了什么）、结果（接受了哪些权衡）以及被否决的替代方案（每个方案被否决的原因）。最后一个元素——"为何不选"——对 AI 智能体来说最为重要。一个知道你评估过分布式缓存并因为领域需要"读自己所写"一致性而否决了它的 AI，就不会建议使用分布式缓存。
实施细节很重要。ADR 应存储在代码库中，进行版本控制，并被视为只追加的。当一个决策被取代时，你写一个引用旧 ADR 的新 ADR，而不是编辑旧的。决策的历史是知识的一部分。
约束注册表。 ADR 捕获某个时间点的单个决策；约束注册表是一份关于当前有效架构边界的动态文档：什么是禁止的，什么是强制的，以及原因。"原因"至关重要——没有它，未来的维护者（无论是人还是 AI）都无法评估约束是否仍然适用于新情况。经过枚举和推理的约束，可以在 AI 智能体生成建议之前作为上下文提供给它们。
"为何不选"文档。 成熟代码库中最未被充分利用的文档模式，是对被否决替代方案的显式记录。每位资深工程师都在脑中保存着一份她见过在这个特定系统中失败的解决方案列表。当她离开时，这份列表也随之消失。将其外化——哪怕只是 DECISIONS.md 文件中非正式的要点列表——所传递的有用知识，远超任何数量的内联文档。
不变量暴露。 目前仅存在于开发者直觉中的某些不变量，可以被编码进代码库本身：基于属性的测试、CI 中的不变量检查、在特定结构属性被违反时失败的架构适应性函数。每一个可被机器检查的不变量，都是 AI 智能体无法悄悄违反的不变量。
这对使用 AI 构建的团队意味着什么 那些从 AI 编码工具中获得真实、持续的生产力提升的团队——而非先是兴奋，然后是债务不断累积——通常做了两件事。
首先，他们将知识捕获视为基础设施，而非文档开销。ADR 不是为后人而写的，而是为了让下一个接触这个子系统的 AI 智能体拥有所需的上下文，以避免违反人类工程师会立即识别的约束。受众一部分是未来的人类，一部分是 AI。
其次，他们为 AI 辅助代码审查制定了明确的标准，这些标准超越了"这段代码是否做到了它所说的？"，延伸到"这段代码是否尊重了支配这个模块的隐式契约？"。第二个问题要求审查者已经将这些契约显式化到足以进行评估的程度。仅能捕获语法错误和常见 bug 模式的 AI 代码审查，对于成熟代码库来说是不够的。
2025 年研究中的生产力悖论根本不是悖论。成熟代码库中的有经验开发者在使用 AI 工具时速度变慢，是因为他们把时间花在捕捉 AI 无法预料的约束违反上。解决方案不是放弃 AI 工具，而是做好使约束可预料的工作——将隐性知识转化为 AI 智能体和未来工程师都能使用的显式制品。
全新代码始终是 AI 工具展示其上限的地方。成熟代码库则是它们展示其下限的地方。两者之间的距离，恰好衡量了你的代码库在人们脑中而非代码库中承载了多少机构知识。
余下内容仅对会员开放。 会员可读完整内容 —— 每一个公开发布的观点背后，那些框架、决策与推理的全貌。
— 完整文章，包含未公开存档的部分 — 可落地的工作框架，附带权衡与决策依据 — 新文章抢先看，先于公开发布 登录以继续阅读→ 随时取消 · 一次订阅，畅读全部
