一个来自 AI 编程智能体的 40 个文件的重构任务摆到了你的桌面。你打开 PR，滚动查看差异（diff），每一个代码块（hunk）看起来都没问题。命名重构很一致，导入很整洁，测试在隔离状态下也能编译。你合并了代码。40 分钟后，主分支的 CI 变红了，因为同级包（sibling package）中的两个调用点仍然向一个现在需要四个参数的函数传递三个参数，而原本能捕获这一错误的类型检查器从未包含在智能体的内环（inner loop）中。
这是当今智能体编写的重构中最常见的失败模式，而且它与单个修改的质量几乎无关。每一个文件单独审查时，看起来都像是一个细心的人类写的。Bug 存在于“接缝”处——即来自不同文件的修改必须保持一致的边界。文件级的审查隐藏了接缝级的正确性，而大多数审查工作流都是围绕文件设计的。
大多数 AI 编码演示展示的是智能体从零构建一个 Todo 应用，或者干净地实现一个全新的 API。而你的代码库，却是一个有着十五年历史的单体应用：充满未文档化的隐性契约、三个团队都依赖但没人完全搞清楚的废弃依赖，以及一个从单一类起步、如今已蔓延到四十个文件的服务层。演示与现实之间的差距，不仅仅是规模问题——更是结构性问题。在把代码库的"钥匙"交给智能体之前，理解这一点，能让你避开一类既隐蔽又代价高昂的失败。
AI 编码智能体确实能帮助处理遗留系统，但只在特定任务边界内才有效。超出这些边界，它们不是显眼地失败——而是生成外观可信、语法正确、语义却有误的变更，这些变更能通过代码审查，最终在生产环境中暴露出来。
这种规律在 2023 年和 2024 年采用编程智能体的团队中几乎普遍存在。第一个月，效率翻倍。第三个月，管理层把生产力指标拿出来，作为 AI 投资回报的证据。到了第十二个月，工程团队有一半的代码库已无法向新员工解释清楚，重构成本高得令人望而却步，工程师花在调试 AI 生成代码上的时间，比他们手写这些代码所需的时间还要多。
这不是一个关于 AI 代码暗中存在缺陷的故事。这是一个关于 AI 生成代码的质量特征如何系统性地瓦解团队已有的组织实践的故事——以及这些实践在技术债务复利失控之前需要如何改变。
这是一个静默发生的失败模式：你要求编程智能体更新身份验证服务的令牌刷新端点。智能体生成了看起来很干净的代码——自信、注释详尽且类型安全。然而，它调用了一个三层目录之上的共享库中，在三个月前就被重命名的函数签名。由于 Mock 仍然使用旧的签名，该端点的测试通过了。直到代码进入预发布环境并拉取真实的库时，错误才浮出水面。
这在抽象意义上并不是“幻觉”。模型知道那个方法——它存在于训练数据中的某个地方，或曾在上下文中简短出现过。问题在于架构：智能体从未获得过它所调用的接口的当前版本。
你的 AI 编码智能体刚刚生成了一个拉取请求。代码看起来没问题，编译通过，测试也过了。你合并了它。两天后，预发布环境的 CI 流水线开始抛出 AttributeError: module 'openai' has no attribute 'ChatCompletion'。智能体使用了一年前已被废弃、并在最新主版本中彻底移除的 API 模式。
这就是废弃 API 陷阱，它坑害团队的频率远比那些聚焦 AI 代码质量的会议分享所描述的要高得多。一项对七个前沿 LLM 进行评估、覆盖 145 个 API 映射的实证研究发现，大多数模型在主流 Python 库上的 API 使用合理性（AUP）低于 30%。当被明确给出废弃上下文时，所有被测模型的废弃 API 使用率高达 70–90%。这个问题是结构性的，与特定模型或特定库无关。
大多数采用 AI 编程智能体的团队，都会把第一周花在争论使用哪个模型上。他们用人为设计的例子对 Opus、Sonnet 和 GPT-4o 进行基准测试，痴迷于排行榜，最终选出一个。然后他们花接下来三个月纳闷，为什么智能体一直在重建错误的抽象、忽视他们的测试策略，以及反复询问该用哪个包管理器。
问题不在模型。问题在上下文文件。
每款 AI 编程工具——Claude Code、Cursor、GitHub Copilot、Windsurf——都会在每次会话开始时读取一个项目专属的 Markdown 文件。这些文件有不同的名字：CLAUDE.md、.cursor/rules/、.github/copilot-instructions.md、AGENTS.md。但它们的目的相同：告诉智能体那些无法通过阅读代码推断出来的信息。这个文件的质量如今比背后的模型更可靠地预测输出质量。然而大多数团队只写一次、写得很糟，然后再也不碰。
大多数采用 AI 编程工具的团队都会遇到同样的瓶颈。第一个月看起来像是成功案例：PR 吞吐量上升，Sprint 速率在攀升，工程经理正在制作幻灯片准备向领导层汇报。到了第三个月，事情悄然发生了变化。事故率开始回升。资深工程师在代码审查上花费了更多时间。一个简单的 Bug 修复现在需要理解一段团队中根本没人写过的代码。生产力的提升已经消失殆尽 —— 但衡量体系从未捕捉到这一点。
问题在于，大多数团队最先关注的指标 —— 生成的代码行数、合并的 PR 数量、消耗的故事点数 —— 对于 AI 辅助开发来说是错误的衡量单位。它们衡量的是产出代码的成本，而不是持有代码的成本。AI 让产出几乎变得免费，却让持有成本保持不变。
当最尖端的模型在 SWE-bench Verified 上获得 80% 的评分时，这听起来像是问题已经解决了。五分之四的真实 GitHub issue 都能被自动处理。直接交付给你的团队吧。但事实是：同一个模型在 SWE-bench Pro（一个专门设计用于防止数据污染、包含来自私有代码库的长程任务的基准测试）上的得分仅为 23%。此外，一项针对经验丰富开发者的严谨对照研究发现，使用 AI 编程工具反而让他们慢了 19%，而不是变快了。
这些数字并不矛盾。它们反映了基准测试衡量的内容与生产环境软件工程实际需求之间的差距。如果你正在构建或打算采用智能体编程（agentic coding）工具，那么这个差距就是最值得关注的事情。
你的 AI 编程助手不记得昨天发生了什么。每个会话都是冷启动的 —— 它不知道你使用的是 yarn 而不是 npm，不知道你禁用 any 类型，也不知道 src/generated/ 目录是神圣不可侵犯的，永远不应该手动编辑。因此，它会使用错误的包管理器生成代码，在你禁止的地方引入 any，偶尔还会覆盖掉那些需要你花一小时才能恢复的生成文件。你纠正了它。明天它又犯同样的错误。你再次纠正它。
这不是模型质量问题。这是一个配置问题 —— 解决方案就是一个纯 Markdown 文件。
CLAUDE.md、AGENTS.md 及其针对特定工具的同类文件，是 AI 编程助手在每个会话开始前阅读的简报。它们编码了助手原本需要重新发现或被纠正的内容：运行哪些命令、避免哪些模式、团队的工作流如何构建，以及哪些目录是禁区。它们相当于一份详尽的工程入职文档，被压缩成了一种优化过的、适合机器阅读的形式。
一个团队在采用 AI 编程智能体（AI coding agents）后，交付的拉取请求（PR）增加了 98%。这听起来像是一个成功的故事——直到你注意到评审时间增长了 91%，PR 的规模膨胀了 154%。代码交付的速度超过了任何人的验证能力。
这就是 80% 问题。AI 编程智能体非常擅长生成看起来似懂非懂（plausible-looking）的代码。当剩下的 20% 需要架构判断、边缘情况意识或任何比“编译通过了吗？”更复杂的反馈循环时，它们就会陷入停滞或悄然失败。在编程智能体上取得成功的团队，并不是那些提示词（prompt）写得最激进的团队，而是那些构建了更好的反馈循环、更短的上下文窗口（context windows）和更严谨的工作流的团队。
我是 Tian Pan，一名工程师型创始人，专注于智能体工程——构建自主 AI 系统并扩展工程团队。我撰写关于系统设计、技术领导力和 AI 智能体实战的实用指南。曾在 Uber、Brex 和 IoTeX 担任早期工程师。
