80% 难题：为什么 AI 编程智能体陷入停滞以及如何突破

一个团队在采用 AI 编程智能体（AI coding agents）后，交付的拉取请求（PR）增加了 98%。这听起来像是一个成功的故事——直到你注意到评审时间增长了 91%，PR 的规模膨胀了 154%。代码交付的速度超过了任何人的验证能力。

这就是 80% 问题。AI 编程智能体非常擅长生成看起来似懂非懂（plausible-looking）的代码。当剩下的 20% 需要架构判断、边缘情况意识或任何比“编译通过了吗？”更复杂的反馈循环时，它们就会陷入停滞或悄然失败。在编程智能体上取得成功的团队，并不是那些提示词（prompt）写得最激进的团队，而是那些构建了更好的反馈循环、更短的上下文窗口（context windows）和更严谨的工作流的团队。

为什么编程环节会出问题

最常见的失败模式不是幻觉产生的 API 或语法错误，而是假设传播（assumption propagation）。智能体在早期误解了一个需求——例如，它假设身份验证令牌是用户范围（user-scoped）的，而实际上是组织范围（org-scoped）的——并在这个错误的前提下构建了一个复杂且内部逻辑自洽的解决方案。三次提交（commit）后，系统虽然“可以运行”，但在任何真实的负载下都会在生产环境中崩溃。除非你手动追踪逻辑，否则代码看起来完全合理。

CodeRabbit 对 470 个代码库的一项研究发现，AI 生成的代码产生的 Bug 总体上比人类编写的代码多 1.7 倍。逻辑和正确性错误多出 75%，I/O 操作中的性能问题大约高出 8 倍，安全漏洞则高出 1.5 到 2 倍。这些并不是随机的故障，而是当你将实现任务委托出去却不锚定可验证的成功标准时，会出现的、可预测的失败模式。

第二种失败模式是理解债（comprehension debt）。当代码“看起来正确”时，代码评审（review）就变成了走过场。开发者报告称，评审 AI 生成的逻辑比评审人类编写的代码需要多出 38% 的精力，然而只有 48% 的人会在提交前一贯地验证智能体生成的内容。如果你无法解释代码的作用，你就无法维护它。如果智能体编写代码的速度超过了你理解代码的速度，你就无法很好地维护它。

基础：CLAUDE.md（正确处理上下文文件）

每一个 AI 编程智能体的会话都是从零开始的。会话之间唯一的持久桥梁是上下文文件——在 Claude Code 中是 CLAUDE.md，在其他环境中可能是 AGENTS.md。大多数团队写错了这些文件：太长、太笼统，或者充斥着智能体通过阅读代码就能弄明白的内容。

在智能体的系统提示词、工具和你的自定义文件中，总共大约只有 150 到 200 条规则的实际限制。默认的系统提示词已经占用了大约 50 个名额。这留下了一个狭窄的预算，如果把预算花在标准语言规范或详尽的 API 文档上，就会浪费本应分配给那些智能体真正无法推断的项目特定约束的空间。

什么样的内容属于上下文文件：

• 非显而易见的构建和测试命令：运行测试套件的确切命令，包括任何所需的环境变量或服务依赖项。
• 打破常规的架构决策：如果你的项目使用的 monorepo 模式与标准工具的假设冲突，请记录下来。如果你有一个封装了第三方库的自定义 ORM 层，也要说明。
• 硬性约束：智能体绝对不能做的事情——例如写入特定文件夹、直接推送到 main 分支、修改自动生成的文件。
• 代码库礼仪：分支命名规范、PR 描述格式、commit 消息风格。

什么不属于：

• 代码库的逐文件描述（智能体可以自己读代码）
• 标准语言规范（智能体已经知道这些）
• Linter 可以确切执行的代码风格规则
• 任何频繁更改的内容（它们会过时）

HumanLayer 将其根上下文文件保持在 60 行以内。这是一种正确的直觉。如果一条规则在实践中没有被违反，那么它可能没有发挥任何作用。每行测试的标准是：删除这一行会导致智能体犯下特定的、具体的错误吗？如果没有，就删掉它。

对于复杂的项目，使用**渐进式披露（progressive disclosure）**模式：创建一个 agent_docs/ 文件夹，其中包含针对构建、测试、规范和架构的单独文件。在主上下文文件中引用它们，这样智能体只有在相关时才会读取它们，而不是在每个会话中都加载所有内容。

值得注意的一个细节是：上下文文件指令的遵循率大约为 70%。对于必须 100% 执行的规则，请使用钩子（hooks）——在特定事件上运行的确定的 shell 命令。上下文文件中的“不要推送到 main”是建议性的。而一个在目标分支为 main 时中止操作的 pre-push 钩子则是确定性的。

一个真正有效的工作流

一个真正有效的工作流遵循四个阶段，且顺序至关重要。

先探索，不编码。 在动任何文件之前，使用计划模式（或智能体中等效的只读探索模式）来理解代码库。阅读相关文件，追踪执行路径，识别现有模式。提问。不做任何更改。跳过这一步是假设传播的主要原因——智能体会根据其先验知识而不是你的实际代码来虚构一个系统模型。

明确计划。 在编写任何代码之前生成详细的实施计划。直接编辑计划——添加约束、纠正误解、划定更改范围。书面计划是一种强制机制（forcing function）：它能在模糊之处转化为代码之前将其暴露出来。对于涉及多个文件或不熟悉的子系统的更改，这一步是必选的。对于你熟悉的代码库中的单函数修复，可以跳过它。

根据计划实施，持续验证。 AI 辅助开发中杠杆率最高的操作是给智能体一种验证自己工作的方法。与其说“实现电子邮件验证”，不如说：“编写 validateEmail()，测试用例：[email protected] → true，invalid-email → false。实现后运行测试。”如果没有反馈循环，你就成了唯一的质量把关人，而你评审的速度会超过你思考的速度。

在自然的时间点提交。 频繁的提交（commit）可以作为存档点。如果实施过程出了偏差，回滚的代价很低。如果成功了，历史记录也清晰易读。始终让智能体为每个任务创建一个分支——这并不是因为分支能让智能体变聪明，而是因为它让恢复过程变得可预测。

交互模式 vs. 自主模式：何时使用？

这并非是非黑即白的抉择，但默认选择是很明确的。

对于不熟悉的代码库、架构决策、跨多文件的变更、高风险领域（安全、数据迁移、生产配置）以及任何规范尚不明确的任务，请使用交互模式。Agent 应该在决策点停下来并展示选项，而不是默默地做出选择。

对于范围明确、有清晰成功标准和自动化测试的任务，以及像修复 lint 错误或更新依赖项这样的批量操作，或是 CI/CD 流水线，请使用自主/非交互模式。在无头 (headless) 模式下，请使用 --allowedTools 明确限定 Agent 的权限——约束其行为比依靠其自我约束更安全。

对于大规模迁移，“扇出 (fan-out)” 模式效果很好：让 Agent 生成一份所有需要修改的文件清单，然后针对每个文件循环运行带有针对性提示词的任务。先在两三个文件上测试，根据出现的问题优化提示词，然后再进行规模化处理。

对于代码审查，针对任何重要的内容，采用并行会话的“作者/审查者”模式是值得这些额外开销的。一个全新的会话负责编写实现。第二个会话在完全不了解代码编写过程的情况下，审查其边界情况、安全问题以及与现有模式的一致性。审查者会话产生的反馈更好，正是因为它没有被编写代码的过程所误导。

管理长会话中的上下文

上下文窗口是有限的，且性能会随着窗口填满而下降。如果你不刻意管理留在上下文中的内容，一个调试会话就可能消耗数万个 token。

最重要的战术习惯是：在不相关的任务之间使用 /clear。纠错螺旋——即你在同一个会话中多次修复同一个问题——既昂贵又会适得其反。上下文会累积失败的尝试，Agent 会开始将这些失败纳入其推理中。在针对同一问题进行了两次失败的修正后，请清除会话并编写一个更精准的初始提示词。

对于调查密集的任务，将研究委托给子 Agent。与其在诊断 Bug 时将十个文件加载到主会话中，不如让子 Agent 阅读这些文件并返回摘要。探索成本保留在你的工作上下文之外，你可以将主会话用于实现。

对于大型功能，按任务阶段拆分会话。会话 1：Schema 设计。会话 2：API 端点（重新开始，开头简述最终确定的 Schema）。会话 3：前端集成（重新开始，在开头总结 API 契约）。全新的会话迫使你阐述已知信息，从而在规范变成 Bug 之前发现其中的漏洞。

Boris Cherny，Claude Code 的创建者，会同时运行 10–15 个并行会话——每个会话都在自己的 git 工作树 (worktree) 中，且彼此隔离。这些会话被当作分支对待。这并非适合每个人的建议，但其底层原则是：并行、隔离的工作比纠缠在一起的顺序工作更容易合并，成本也更低。

理解债问题

AI 辅助开发中隐藏最深的长期风险不是 Bug。而是代码库虽然可以运行，但团队中没人能解释它。

Addy Osmani 的研究发现，44% 的开发者手动编写的代码占比不足 10%。这是代码库构建方式的一个重大转变。问题在于，指导 Agent 的工程师是否保持了足够的架构理解来做出正确的决策——以及这些团队中的初级工程师是在培养真正的技能，还是仅仅在学习如何批准 AI 的输出。

Flask 和 Jinja2 的作者 Armin Ronacher 直截了当地指出：“通过 LLM 实现的自动化鼓励了思维的脱离。”生成的速度带来了持续前进的压力，使得审查变成了一种形式。避开这一陷阱的团队是那些将 AI 编程 Agent 视为工程判断力放大器、而非其替代品的团队。

务实的对策：

• 不要发布你无法解释的代码。如果你无法梳理逻辑并清晰阐述它为何能处理那些边界情况，那么它就还没准备好。
• 在投入使用 Agent 之前，先投入测试基础设施建设。测试是让 Agent 输出变得可信的反馈环。没有测试，你就是在盲目飞行。
• 让初级工程师批判性地阅读 Agent 生成的代码，而不只是批准它。学习发生在分析过程中，而不是产出结果中。
• 将架构决策留给人类。Agent 擅长执行；但在没有被明确给定评估标准的情况下，它们在权衡取舍方面并不可靠。

真正重要的转变

从 AI 编程 Agent 中获益最多的开发者，并不是那些编写最复杂提示词的人。而是那些投入于周边基础设施的人：紧密的反馈环、清晰的成功标准、刻意的上下文管理，以及对理解所交付内容的真实承诺。

AI 编程 Agent 提高了小团队构建能力的上限。它们不会提高质量的下限——这仍然取决于指导它们的人类。那些将 “AI 负责编程，我负责审查” 视为最终状态的团队，会发现自己维护的代码库规模更大、产出更快，但变更成本也越来越高。而那些将 Agent 视为定义明确工作的快速执行者，并以测试和人类架构判断为锚点的团队，其价值将随时间不断累积。

“80% 问题”是真实存在的。突破这一问题所需的东西，与那些始终将“优秀的工程”与“快速的工程”区分开来的要素是一致的：清晰度、反馈，以及在交付前放慢速度的自律。