二十年来，文档一直是良好初衷的坟墓。你在第一个 Sprint 期间编写 README，那时架构整洁，你的热情高涨。但没人读它。到了第三个 Sprint，它就开始在构建命令上误导人，到了第六个 Sprint，它描述的是一个早已被删除的服务。文档是每个人都同意缴纳但实际上没人在缴的税 —— 一种没有反馈循环的道德准则。写了烂文档，什么也不会发生。不写文档，同样什么也不会发生，因为高级工程师把架构都记在脑子里。
然后我们将编程 Agent 指向我们的代码仓库，反馈循环一夜之间降临。README 现在是你拥有的杠杆率最高的文件 —— 这并不是因为有人做了关于文档规范的励志演讲，而是因为该文件的质量现在直观地决定了你的 Agent 是交付正确的代码，还是会信誓旦旦地对一个已不存在的架构产生幻觉。
这就是文档的复兴，而它与我们过去编写的文档几乎毫无关系。
你的平台团队通过开发者采纳度来衡量成功。内部 API 的月活跃工程师数量。新服务的首次调用时间（Time-to-first-call）。季度 DX 调研中的净推荐值 (NPS)。每一个指标都假设请求的另一端是一个人类——一个阅读入门指南、复制 curl 示例、并在错误消息毫无帮助时在 Slack 中抱怨的人。
这种假设正悄然变得不再成立。你内部 API 增长最快的消费者不是人，而是一个智能体 (Agent)：一个正在解决工单的编码助手，一个在夜间核对发票的工作流，或者一个为了回答一个问题而调用六个服务的支持机器人。这些调用者不会浏览你的文档——它们会将你的工具模式 (tool schemas) 摄取到上下文窗口中。当错误提示模糊不清时，它们不会提交 bug——它们会默默地重试、消耗 token，然后放弃。而且它们的数量即将超过人类。
你周二下午花时间删除了一个已经废弃的工具模块。你清理了导入，运行了类型检查器，看着 CI 变绿，然后合并了 PR。周三上午，一个新的 Agent 会话查看同样的代码，认定代码库“缺失”了一个小型助手函数，于是又把那个废弃的模块写了回来——名字相同，形状相同，只是风格略有不同。昨天批准删除的评审者现在不得不回想为什么要删掉它，找到当时证明其合理性的对话，并再次解释一遍。Agent 并没有出现故障。它只是完全按照其上下文的要求在行事。
这是编码 Agent 的结构性可靠性问题，没有人通过提示词工程（Prompt Engineering）来解决：Agent 的上下文起始于代码库的当前状态，而不是该状态为何如此的历史。你移除的文件没有留下 Agent 可见的痕迹。你迁移掉的依赖项只是 npm 上的另一个包。你刻意删除的不稳定测试（Flaky test）是一个等待被“修复”的覆盖率缺口。缺席——即你做出的决策留下的负空间——是不可见的。
当你第一次尝试像调试服务那样调试 Agent 时，你会发现以往的肌肉记忆完全派不上用场。你设置了一个假设的断点——虽然 IDE 中没有面板可以放置它，但你在脑海中想象了一个——就在 planner 选错工具的那一步。你使用相同的输入重新运行。这一次，planner 选择了正确的工具。你再次运行。它又选了一个你从未见过的第三种工具。Bug 是真实存在的，你的同事今天早上复现了两次，而你用了十五年的调试器突然间变成了博物馆里的陈列品。
这里失效的心智模型并不是“使用调试器”，而是背后更深层的假设：即一个程序在给定相同输入的情况下，会产生相同的执行过程。现代调试器中的每一项功能——断点、单步跳过 (step-over)、观测表达式 (watch expressions)、条件断点、热重载——都是建立在这种确定性之上的。你暂停执行是因为暂停是有意义的。你向前单步执行是因为下一步是可预知的。你检查一个变量是因为它的值是一个事实，而不是从某种分布中随机抽取的结果。
你的代码评审正在优化错误的目标。当 AI 智能体（agent）贡献了你大部分的代码提交（commits）时，评审局部正确性——这个函数的功能是否如其所述？——就像是通过检查笔迹来给数学考试评分一样。机器已经通过了你的代码检查工具（linter），运行了你的测试套件，并按照规范格式化了输出。它所引入的 Bug 并不是行内（line-by-line）评审所能捕捉到的那种 Bug。
一项针对 GitHub Pull Request 的大规模研究发现，AI 协同编写的 PR 包含的缺陷是纯人工 PR 的 1.7 倍——其中包含多出 75% 的逻辑和正确性问题、2.74 倍的安全漏洞以及 3 倍的可读性问题。这并不是因为代码看起来有问题，而是因为它在错误的地方做了错误的事情，且对系统的其他部分持有错误的假设。这些恰恰是为捕捉拼写错误和风格违规而优化的传统代码评审所无法发现的故障模式。
AI 平台团队最常见的失败模式不是技术问题，而是组织问题：中央平台团队成了每个产品团队将 AI 能力推上生产的必经关卡。请求队列不断增长，交付周期从几天膨胀到几周。产品团队愈发沮丧，开始拼凑非官方的绕道方案——硬编码 API 密钥、私下接入 LLM、用个人信用卡注册供应商账户。等平台团队察觉时，组织里已有一半的 AI 工作游离在任何治理体系之外。
问题不在于平台团队关心治理，而在于他们把治理实现成了审批流程，而非基础设施。
你的数据治理审计可能已经发现了它们：用个人信用卡支付的 OpenAI 和 Anthropic API 密钥，通过个人账户接入 Claude 的 Slack 机器人，通过企业 VPN 代理请求的本地 Ollama 实例。没有人通知平台工程团队，没有人请示 IT 部门。工程师们只是……自己动手做了。
这就是影子 AI 问题。无论你是否已经发现，它早已潜伏在你的组织内部。在知识工作环境中，大约一半的员工表示自己在使用雇主未授权的 AI 工具。在软件工程师群体中——他们既有能力搭建非官方集成，又面临提升生产力的压力——这一比例几乎肯定更高。
一家中型 SaaS 公司的资深工程师在上个季度花了整整两天时间去排查一个部署 bug，结果发现竟然是智能体的错。该智能体读取了一份最后更新于 2023 年的运行手册（Runbook），忠实地执行了第三步，并运行了一个在当前部署工具中已不再存在的命令。这份运行手册在 Wiki 中依然渲染良好——甚至截图也依然清晰可见——但它已经悄然变得对那些无法察觉环境已过时的读者充满敌意。人类作者完全没意识到，这份文档现在已经成了每个新员工的 AI 助手的关键输入。
这就是过去 18 个月里大多数工程团队中发生的悄然转变：内部 Wiki 累积了第二批受众。同样的 Confluence 页面、同样的架构图、同样的“我们如何部署”的 Gist，现在正由两个截然不同的消费者阅读——工程师本人和工程师使用的 AI 助手。这两类读者在完全不同的约束条件下消费同样的文字，并且当文档在编写时仅考虑了第一类读者时，会产生系统性的不同故障模式。
一位资深工程师在周一加入你的团队。到了周五，他们已经交付了一个涉及 11 个文件的 TypeScript 重构，并在通过评审时仅有两个小细节（nits）需要修改。两周后，这位工程师打开了路由智能体（routing agent）的系统提示词——240 行指令、三个编号的示例块、四个“绝不允许”子句，以及底部一段读起来像道歉的段落——然后盯着它看了一个小时。他们无法告诉你如果删除第 87–94 行会发生什么。六个月前写下这些内容的工程师也无法告诉你。
这是没人会写在入职文档里的鸿沟。一个重度依赖提示词的代码库看起来像是个代码库：它存在于同一个仓库中，运行相同的 CI，并在相同的 PR 中接受评审。但它的语义却存在于别处：存在于一个团队中没人构建的模型观察到的行为中，针对的是一个没人能完全枚举的输入分布，其失败模式表现为添加一句话的 PR，而不是错误报告。传统的代码阅读工具——类型、签名、测试、命名——几乎不起作用。一个试图“阅读代码”的新员工无法了解为什么每一行都在那里，而一个只交给他们 Notion 文档和 Slack 频道的团队，实际上是在默认将入职培训“外包”给提示词的最初作者。
在一项受控随机对照试验中，使用 AI 编程助手的开发者预测他们的速度会提高 24%。而实际上，他们慢了 19%**。关键在于：他们仍然认为自己变快了。这种认知鸿沟——即生产力的“感觉”与实际交付能力背道而驰——是一种失效模式的早期预警信号，这种模式通常在数月而非数小时内显现。
行业已实现近乎普及的 AI 采用。93% 的开发者使用 AI 编程工具。生产力增长却停滞在 10% 左右。这些数字之间的差距并非工具问题，而是一个不断累积的债务问题，大多数团队在扭转成本变得极其昂贵之前，往往察觉不到它的存在。
AI 生产力研究中有一个几乎无人提及的数字：39 个百分点。一项针对有经验开发者的研究中，参与者预测 AI 工具会让他们快 24%。完成任务后，他们仍然认为自己快了 20%。实际测量结果：他们慢了 19%。感知差距是 39 个百分点——而且每次迭代、每次代码审查、每个交付的功能都在累积。
这就是认知负载倒置。AI 工具擅长卸载廉价的认知工作——编写语法正确的代码、起草模板、建议函数名——同时产生了一类更难的认知工作：对不确定输出的持续评估。你并没有消除认知努力，而是将简单的一半自动化了，然后把困难的一半留给了自己。
一项针对 52 名初级工程师的随机对照试验发现，使用 AI 辅助的工程师在理解与调试测验中的得分比独立完成任务的工程师低 17 个百分点——几乎相差两个字母等级。调试能力——恰恰是 AI 应该增强的技能——呈现出最大的差距。而这仅仅发生在一次学习课程之后。将此推演至一年的日常 AI 辅助使用，你就能理解，为何几家公司的资深工程师悄悄反映，团队推理复杂问题的方式已悄然改变。
AI 工具带来的技能萎缩问题是真实存在的，可以量化的，且对中级工程师的冲击最为显著。以下是研究所揭示的规律，以及你可以采取的应对措施。
我是 Tian Pan，一名工程师型创始人，专注于智能体工程——构建自主 AI 系统并扩展工程团队。我撰写关于系统设计、技术领导力和 AI 智能体实战的实用指南。曾在 Uber、Brex 和 IoTeX 担任早期工程师。
