AI 编程工具为何总用废弃 API：根源分析与解决思路

你的编程 Agent 一直使用已废弃的 API，原因有两个，且没有一个可以通过更严厉的 prompt 来修复。首先，它的训练数据冻结在过去：每个模型都有一个知识截止日期，所以你们团队在三月份宣布的废弃在模型脑中根本不存在。其次，它的检索无法区分当前和过时。你的代码库中仍有大量旧模式的调用点，你的 wiki 仍在文档中记录它，2023 年的一个示例文件仍在精美地演示它。Agent 拿到第一个看起来合理的匹配项就走，而第一个合理的匹配通常是旧的，因为在地球上的几乎每个代码库中，旧代码的数量都超过新代码。

简而言之：你的 Agent 不是固执，而是生来就过时了。它的训练早于你的废弃决定，而且其检索机制中没有任何东西会把一个三年前的示例文件排在上个月的迁移 PR 之前。只要有东西按时效性和权威性对来源进行排序，它就会一直使用它看到最多的模式。

为什么 Agent 总是使用已废弃的代码？

因为旧的 API 在模型见过的所有内容中占据主导地位。Anthropic 为每个 Claude 模型发布训练数据截止日期，并与"可靠知识截止日期"区分开来——即知识最可信的日期（Anthropic model docs）。OpenAI 为 GPT 模型做了同样的事情（OpenAI model docs）。任何在这些日期之后被废弃的内容对权重来说是不可见的，而且差距比看起来更大：一个今年夏天发布的模型可能会对某个在你读完其发布帖之前就已经变更过的库自信地给出错误答案。

频率使情况更糟。一个存在了五年的 API 背后有五年的教程、Stack Overflow 回答和博客文章；它的替代品只有几个月。Stack Overflow 自己对开发者 AI 信任差距的分析将"几年前就已废弃的方法"列为开发者报告的最常见失败模式之一，与根本不存在的 API 并列（Stack Overflow, 2026）。当模型发出废弃代码时，它正在做的是其训练分布教它做的事情。

Agent 如何决定信任哪个 API 版本？

它不决定，它满足于搜索。当你 Agent 需要调用你的账单服务时，它搜索，找到一个能编译的，然后就继续。Wiki 说一套，代码说另一套，一个旧的示例文件说第三套，循环中没有任何东西将它们相互排名。这就是搜索满足（satisfaction of search）的表现：Agent 在第一个看起来合理的答案处停止，而不是最好的那个。请求一个新的 webhook 处理器，它会按照它首先找到的现有处理器来建模。如果那是废弃的代码，你现在就多了一份副本。

这就是为什么相同 prompt 在相同模型上产生不同代码，取决于哪些文件恰好进入上下文。废弃决定是存在的，但它存在于一条 Slack 消息和一个合并的 PR 中，正是你的编程 Agent 看不到的地方。

为什么更大的上下文窗口解决不了问题？

把所有东西塞进一百万 token 的窗口反而使排名问题更严重，而不是更好。Anthropic 自己的文档对此直言不讳：更多上下文并不自动意味着更好，因为准确性和召回率随着 token 数量增长而下降，他们将此命名为上下文腐化（context rot）（Anthropic context docs）。我们之前写过关于这在 Claude Code 会话中实际如何表现的文章。

独立数据支持这一点。Zylos Research 2026 年对长上下文评估的调查发现，模型通常在声称的上下文限制的 30-40% 之前就变得不可靠，并将 2025 年企业 AI 失败的原因归因于多步推理期间的上下文漂移或记忆丧失（Zylos, 2026）。如果你把旧文档、新文档和迁移指南粘贴到一个巨大的 prompt 中，你并没有告诉 Agent 哪个会赢。你只是给了它更多看起来合理的匹配来满足。窗口是工作记忆，不是真实来源，上游仍然有东西需要决定什么值得占用那个空间。

发布废弃代码的实际成本是什么？

它会累积。GitClear 2026 年对 6.23 亿次代码变更的分析发现，自 2023 年以来重复块增加了 81%，而移动代码（其作为重构的代理指标）下降到变更行的 3.8%（GitClear, 2026）。每次 Agent 将废弃模式复制到新文件时，它就为下一个 Agent 多添加了一个过时的调用点供其查找和模仿。在一个 Agent 编写 commit 占比不断增长团队中将其放大，废弃 API 就不再是清理工作，而成为承重结构。Sonar 的 Tom Howlett 描述了同样的动态：Agent 添加代码但很少删除它，所以废弃函数与它们的替代品堆积在一起（InfoWorld, 2026）。

注意这不是能力问题。斯坦福 2026 年 AI 指数报告显示，SWE-bench Verified 性能在一年内从 60% 上升到近 100%（Stanford HAI, 2026）。模型能写代码。它们只是无法判断你实际想要哪个 API。

规则文件和废弃注释能解决这个问题吗？

部分可以，而且坦白说，值得拥有。在 CLAUDE.md 中写一行"使用 PaymentClientV2，永不使用 PaymentClient"在你写下的当天是有效的。@deprecated 注解也有帮助，当 Agent 读取带注解的文件时。但三个限制很快就会出现。第一，规则文件会腐化：当规则过时，什么都不会中断，所以漂移会保持不可见，直到 Agent 采取行动。第二，它们不能扩展。在一个仓库中保持 CLAUDE.md、AGENTS.md 和 .cursorrules 同步是困难的，在五十个仓库中则是绝望的。第三，没有人更新它们，因为废弃决定发生在 PR 审查或 Slack 线程中，而将其写入规则文件是无人奖励的手动工作。

这就是规则文件与上下文引擎权衡背后的诚实评估。Qodo 对 609 名开发者的调查发现，65% 的人表示 AI 在关键任务期间遗漏了相关上下文（InfoWorld, 2026）。一个手动编辑的文件从来无法独自弥合这个差距。

真正有效的方法：对真实来源进行排序

修复需要一个知道时效性和权威性的上下文层，这样 Agent 就不会再把 2023 年的示例文件和上个月的迁移 PR 当作同等的见证。这就是 Unblocked 做的事情：它综合你的 PR、Slack 决定和迁移历史，生成决策级上下文，这样 Agent 看到的不是三个冲突的匹配，而是"此 API 于三月废弃，改用 X"，并附上推理过程。这是你的 Agent 可以查询的制度性记忆，而不是某个必须记住要编辑的文件。

以下是一个团队如何接入它的：

每个 Agent 项目文件中的第一条指令是：在做任何更改之前，先收集上下文。这从 Jira、Confluence 和 Slack 通过 Unblocked 拉取——因为我们大多数知识实际上生活在那里，在线程讨论中。我在发布当天就设置好了，现在我甚至不再想它。我只是得到相关信息。

— Andrei Antanovich，软件工程师，Waste Logics

Unblocked 不生成代码。它是上下文引擎，为你的 Agent 提供当前答案而不是最常见的答案，无论你运行哪个 Agent。

常见问题

为什么我的 Agent 在我纠正之后仍然重复同样的错误？

你的纠正存在于一个会话的上下文中，当会话结束时它就蒸发了。模型的权重仍然偏好旧模式，而误导它的过时来源都还在那里。除非纠正落在某个持久的、会下次被检索的地方，否则每个新会话都从相同的冻结先验开始。这就是为什么解决这个问题 的团队在检索层而不是 prompt 层修复它。

更新的模型会停止建议废弃的 API 吗？

它移动了截止日期，而不是问题。一个更新的模型知道其训练日期之前的公开废弃信息，但你的内部废弃永远不会出现在任何训练集中。发布后的第二天，模型再次冻结，而你的代码库继续前进。按新鲜度排序的检索才能缩小差距，而不是发布日历。

我应该删除旧代码以防止 Agent 找到它吗？

删除真正死掉的示例和过时的 wiki 页面有很大帮助；它们是纯粹的噪音。但你不能在仍有调用者存在时在迁移中途删除废弃的 API。Agent 造成最大损害的时候恰恰就是那个时候，而一个标记"已废弃，迁移进行中，使用 X"的上下文层正是在那时候发挥作用。

本周可以尝试的 20 分钟版本

选择你的 Agent 最常绊倒的那个废弃，为它运行这个：grep 旧的调用点，检查一个做"搜索，然后模仿"的 Agent 会找到什么。阅读当前指导实际上在哪里；如果它在 Slack 线程和合并的 PR 中，没有规则文件提到它，这意味着没有 Agent 能够遵守它。然后做两件廉价的事情：删除或隔离最过时的示例文件，并在你的规则文件中添加一行命名替代品。这能为你争取几周时间。对于持久修复，让收集上下文成为每个 Agent 会话的第一步，就像 Andrei 的团队那样，使用一个按时效性和权威性对你的真实来源进行排序的上下文层。你的 Agent 从来不是不知道如何写代码。它不知道你的五个答案中哪个是当前的，这是一个你现在实际上可以解决的问题。