大多数团队对待 CLAUDE.md 的方式和对待 README 一样：写一次，然后忘掉它的存在，最后疑惑为什么什么都不好使。但 CLAUDE.md 不是文档。它是你的代码库和每一个接触它的 AI agent 之间的 API 契约。写对了，每一次 AI 辅助的提交都遵循你的架构。写错了——或者更糟，让它腐化——你实际上是在每次会话中让你的 agent 变得更笨。
AGENTbench 研究在 12 个代码库中测试了 138 个真实编码任务，发现自动生成的上下文文件实际上降低了 agent 的成功率，甚至不如完全没有上下文文件。三个月积累的指令，其中一半描述的代码库已经面目全非，不会指导 agent——它们会误导 agent。
你的智能体在开发环境中运行得完美无缺。它能回答测试查询、调用正确的工具、产出干净的输出。然后它上了生产环境，在一个十二步工作流的第七步出了问题。日志显示最终输出是一堆垃圾，但你完全不知道为什么。
你开始加打印语句。你在编排代码中到处散布 logger.debug() 调用。你盯着成千上万行输出，然后意识到你在用单进程的工具调试一个分布式系统。这就是大多数团队在 AI 智能体上犯的根本错误——他们把智能体当作程序来对待，但智能体的行为更像分布式系统。
当今生产环境中最有效的 AI 智能体看起来与框架演示完全不同。它们不是拥有十七种节点类型的有向无环图，也不是通过消息总线协调的多智能体集群。它们是一个提示词、一个工具列表和一个 while 循环——它们比框架重型的对手交付更快、故障更少、维护成本更低。
这不是为了标新立异。这是一个又一个团队在花费数周时间进行框架迁移、抽象调试和 DSL 考古之后得出的结论。这种模式如此一致，值得给它一个名字：后框架时代。
你的智能体返回了 200 状态码。响应流畅、语法完美，但完全错误。欢迎来到智能体调试的世界——在这里，系统永远不会崩溃，永远不会抛出异常，而失败的方式与成功看起来毫无区别。
传统调试假设 Bug 会表现为错误。堆栈跟踪指向出问题的那一行，失败的断言告诉你哪里出了错。但智能体在做出错误决策时并不会崩溃。它们会自信地执行错误的计划，用看似合理的参数调用错误的工具，然后交付一个建立在幻觉基础上的精美答案。Bug 不在你的代码里——它在你的智能体的推理中，而你的调试器根本不知道推理是什么样的。
每个 DevOps 团队都有一套凭据轮换政策。大多数团队已经针对其服务、CI 流水线和数据库实现了自动化。但当你部署一个持有跨五个不同集成的 API 密钥的自主 AI Agent 时，那套轮换政策就变成了一个地雷。Agent 正在执行任务中——分拣 Bug、更新工单、发送 Slack 通知——突然它的 GitHub 令牌过期了。进程看起来很健康。日志显示没有崩溃。但无声无息地，一切都不再起作用了。
这是无人从 DevOps 映射到 AI 的凭据轮换问题。传统的轮换假设工作负载是可预测的、由人管理的，并且具有清晰的边界。自主 Agent 打破了每一个这样的假设。
在 2025 年，工程组织的运维琐事上升到了 30% —— 这是五年来的首次增长 —— 尽管在 AI 工具上的投入创下了纪录。原因并非 AI 失败了。原因在于团队部署 AI Agent 时，并没有采用像对待人类值班工程师那样严格的标准：没有 Runbook，没有升级路径，没有影响范围（Blast-radius）限制。Agent 可以对日志进行推理，但没有人告诉它它被允许做什么。
“能够诊断的 AI”与“能够安全缓解故障的 AI”之间的差距，并不是模型能力问题。这是一个系统工程问题。解决这个问题需要 SRE 团队已经应用在人类操作员身上的同样纪律：结构化的 Runbook、分层权限和强制性的升级点。
一个基于流行开源技术栈构建的多 Agent 研究工具陷入了递归循环，运行了 11 天才被发现。账单：47,000 美元。两个 Agent 一直在不停地互相对话，消耗着 token，而团队却以为系统在正常工作。这就是 Agent 流水线没有背压时会发生的事情。
问题是结构性的。当编排 Agent 将任务分解为子任务并生成子 Agent 来处理每一个任务，而这些子 Agent 又可以自行生成更多子 Agent 或在多个工具调用之间扇出时，你就会得到指数级的工作生成。流水线产生工作的速度超过了它能执行、完成甚至核算的速度。这与响应式系统、流式架构和网络协议几十年前解决的问题完全相同——同样的解决方案同样适用。
大多数部署 AI Agent 的团队在实现了提示词缓存 (Prompt Caching)，或许再加上语义缓存之后，就认为大功告成了。但他们实际上错失了 40-60% 的潜在节省空间。原因并非在于懒惰 —— 而是 Agent 工作负载产生的缓存问题在简单的请求-响应式 LLM 调用中并不存在，其解决方案需要从传统 Web 缓存从未涉及的层级进行思考。
单个 Agent 任务可能涉及一个 4,000 Token 的系统提示词、三个分别返回不同结构数据的工具调用、一个在结构上与昨天完全相同的多步计划，以及一个需要在对话中持久化但绝不能跨用户共享的会话上下文。其中每一项都代表了不同的缓存机会，具有不同的 TTL (生存时间) 要求、不同的失效触发机制，以及在缓存失效时不同的故障模式。
你的 Agent 在预发布环境中运行完美。它调用正确的工具，推理多步骤计划，并返回精心打磨的结果。然后生产环境来了：地理编码 API 在 7 步计划的第 3 步超时，LLM 在句子中间返回不完整的响应，而你的 Agent 自信地编造数据来填补空白。直到客户发现，没有人注意到。
LLM API 调用在生产环境中有 1-5% 的失败率——速率限制、超时、服务器错误。对于每个任务进行 10-20 次工具调用的多步骤 Agent，这意味着相当比例的任务至少会遇到一次故障。问题不在于你的 Agent 是否会遇到故障，而在于你是否曾经测试过它遇到故障时会发生什么。
传统的标准 LLM 在没有迭代检索的情况下，在多步网络研究基准测试中的得分低于 10%。深度研究代理（Deep research agents）——即在循环中进行搜索、阅读、综合和重新查询的系统 —— 得分则超过 50%。这种五倍的提升解释了为什么每个严肃的 AI 产品团队都在构建此类工具。但这无法解释为什么大多数实现要么在追逐无关的细枝末节时耗费 $15 的账单，要么在两次肤浅的搜索后就宣布胜利。
核心问题不在于构建循环，而在于知道循环何时应该停止。事实证明，这是一个出人意料的深度系统设计挑战，涉及收敛检测（convergence detection）、成本经济学、来源可靠性和多代理协作。
你的 Agent 上周二在生产环境出了故障。一个客户报告了错误的回答。你调出日志，看到最终输出，也许还有几条中间的 print 语句——然后你就卡住了。你无法重新运行 Agent 来重现同样的故障，因为模型不会产生相同的 token，你的工具调用的 API 现在返回了不同的数据，嵌入在提示词中的时间戳也已经变了。Bug 消失了，你只能盯着间接证据发呆。
这就是 AI Agent 的根本调试问题：传统软件是确定性的，所以你可以通过重建输入来复现 bug。Agent 系统不是。每次运行都是模型采样、实时 API 响应和时间依赖状态的独特组合。没有专门的工具，事后调试就变成了取证猜测。
确定性重放通过在执行过程中记录每个非确定性来源，并在重放时替换这些记录来解决这个问题——把你无法复现的 Agent 运行变成你可以像调试器一样逐步跟踪的东西。
你的 Agent 在预发布环境中通过了每一项测试。然后它进入了生产环境，发送了 4,000 封电子邮件，向一名客户收取了两次费用，并删除了一条本不该触碰的记录。预发布测试没有错 —— 它们只是测试了错误的东西。预发布环境让 Agent 看起来很安全，因为所有它可能破坏的东西都以错误的方式被伪造了：Mock 得足以不崩溃，但也真实得足以让你误以为测试是有意义的。
这就是“模拟保真度陷阱”。这与普通的软件测试失败不同。对于确定性函数，镜像生产环境 Schema 和 API 的预发布环境通常就足够了。对于 Agent 来说，行为产生于推理、工具输出以及跨多步轨迹的累积状态之间的相互作用。如果在这些维度中的任何一个上与生产环境存在偏差，预发布环境都会产生对其实际行为过度自信的 Agent。
我是 Tian Pan，一名工程师型创始人，专注于智能体工程——构建自主 AI 系统并扩展工程团队。我撰写关于系统设计、技术领导力和 AI 智能体实战的实用指南。曾在 Uber、Brex 和 IoTeX 担任早期工程师。
