深入解析Claude Code构建经验：提示缓存为何是一切根本

转发：构建 Claude Code 的经验：Prompt Caching 是一切的基石

在软件工程领域，有一句经典的话：“缓存支配一切”。这条法则在 AI Agent 的开发中同样适用，甚至更为关键。

类似 Claude Code 这种需要持续运行数十分钟甚至更久的智能体产品，其可行性基础正是 Prompt Caching（提示词缓存）。这项技术让我们能够复用前几轮请求中的计算结果，从而大幅降低响应延迟与 API 调用成本。

那么，Prompt Caching 到底是什么？它是如何运作的？在实际工程中又该如何落地？

在 Claude Code 的研发过程中，我们几乎是围绕着 Prompt Caching 来设计整套技术架构的。高缓存命中率不仅意味着成本的有效控制，还能让我们为用户提供更宽松的速率限制。因此，我们为 Prompt 缓存命中率设置了专门的告警监控；一旦指标低于阈值，甚至会按照事故等级来处理。

以下经验，正是我们在大规模优化 Prompt Caching 过程中总结出来的。坦诚地说，其中不少结论在当时都非常反直觉。

规划缓存提示

图片 1

Prompt Caching 的核心机制是“前缀匹配”。API 会从请求的开头部分开始缓存，一直缓存到每一个 cache_control 断点为止。

这意味着，内容在提示词中的排列顺序至关重要。你需要尽可能让不同的请求共享相同的前缀。

最佳策略是：将静态内容放在前面，动态内容放在后面。具体到 Claude Code，大致可以划分为以下几个层级：

1. 静态的 system prompt 和 tools（全局缓存） 2. CLAUDE.md（项目内缓存） 3. Session context（会话内缓存） 4. Conversation messages（对话消息）

通过这样的排序，我们就能最大化不同会话之间共享缓存命中的概率。

但这个顺序有时会脆弱得超乎想象。我们之前就曾因为各种原因破坏过它，比如在静态 system prompt 中放入了过于精确的时间戳、以非确定性的方式打乱工具定义顺序、或者修改了工具参数（例如 AgentTool 能调用的 agent 列表）等。

使用消息进行更新

有时候，提示词中的信息会过时，比如时间更新了，或者用户修改了文件。你可能会本能地直接更新提示词，但这会导致缓存未命中，对用户而言成本可能相当高。

所以，不妨换个思路：能否把这些变化通过下一轮的消息传递进去？在 Claude Code 里，我们会在下一条用户消息或工具结果中嵌入一个 标签，将更新后的信息（例如“现在已经是周三了”）传给模型。这样就能尽量保住已有的缓存数据。

不要在会话中途更改模型

Prompt Cache 是按模型隔离的，这一点使得缓存成本的计算方式变得非常反直觉。

假设你已经和 Opus 对话到了 100k tokens 规模，此时只想询问一个简单问题。如果切换成 Haiku，实际上可能比继续使用 Opus 回答成本更高，因为系统需要为 Haiku 重新构建整个 Prompt Cache。

如果确实需要切换模型，最佳做法是使用子 Agent。让 Opus 先为另一个模型准备一条 handoff 消息，说明需要完成什么任务。在 Claude Code 中经常能看到这种做法，比如 Explore agents 就会使用 Haiku。

切勿在会话期间添加或删除工具

在对话进行到一半时修改工具集，是破坏 Prompt Caching 最常见的“罪魁祸首”之一。你可能觉得“只给模型当前需要的工具”才是最优解，但工具作为缓存前缀的一部分，任何新增或移除操作都会导致整段对话的缓存失效。

Plan Mode — 围绕缓存设计功能

Plan mode 是一个很好的例子，说明了功能设计应如何围绕缓存约束展开。最直观的做法是：当用户进入 plan mode 时，将工具集替换成只读工具。但这样做会直接破坏缓存。

我们的做法正好相反：始终在请求中保留全部工具，同时把 EnterPlanMode 和 ExitPlanMode 本身也设计成工具。当用户打开 plan mode 时，Agent 会收到一条系统消息，告知它当前处于 plan mode，以及此时的规则（例如探索代码库、不要编辑文件、计划完成后调用 ExitPlanMode）。工具定义本身保持不变。

这样还有一个额外好处：因为 EnterPlanMode 本身就是模型可以主动调用的工具，所以当它发现任务比较复杂时，可以自主进入 plan mode，而不会导致任何缓存断裂。

Tool Search — 延迟加载而非移除

同样的原则也适用于 Tool Search 功能。Claude Code 可能会加载几十个 MCP tools，如果每次都塞进请求里，成本会很高；但如果在对话中途移除它们，又会破坏缓存。

我们的解决方案是：defer_loading。我们不移除工具，而是发送轻量级的 stub，只包含工具名，并带上 defer_loading: true 标记。模型在需要时，可以通过 ToolSearch 工具去“发现”它们。只有当模型真正选中某个工具时，我们才加载完整的工具 schema。

这样做的好处是，缓存前缀始终保持稳定：同样的 stubs 总是以同样的顺序存在。

幸运的是，你现在也可以通过我们的 API 直接使用 tool search 工具来简化这个流程。

图片 2

分叉上下文 — 压缩

当上下文窗口用满时，就会触发 Compaction（压缩）。我们会把到目前为止的对话做一次总结，然后带着这个摘要开启一个新会话。

有趣的是，Compaction 在 Prompt Caching 方面存在很多边界情况，而且往往并不直观。

最典型的情况是：当我们做 Compaction 时，需要把整段对话重新发给模型，让它生成摘要。如果这是一次独立的 API 调用，并且使用了不同的 system prompt，也没有任何工具定义——虽然这是最简单的实现方式，但它与主对话的缓存前缀就完全对不上了。

这意味着，用户需要为这些输入 tokens 支付全价，成本会被大幅拉高。

The Solution — 缓存安全的分叉

因此，在执行 Compaction 时，我们会使用与父对话完全一致的 system prompt、user context、system context 以及工具定义。我们把父对话的 conversation messages 放在前面，然后把 compaction prompt 作为一条新的用户消息追加到最后。

从 API 的角度看，这个请求与父对话最后一次请求几乎一模一样：同样的前缀、同样的工具、同样的历史。因此，缓存前缀可以被直接复用，新增的 tokens 只剩 compaction prompt 本身。

当然，这也意味着我们需要额外保留一个“compaction buffer”，确保上下文窗口有足够空间容纳 compact 消息和摘要输出所需的 tokens。

Compaction 确实很棘手。不过好消息是，你不需要再亲自踩一遍这些坑了。基于我们在 Claude Code 里的经验，我们已经把 compaction 直接内建进了 API，让你可以直接将这些模式应用到自己的应用中。

经验教训

1. Prompt Caching 本质上是前缀匹配。前缀中任何位置的变动，都会导致其后的所有内容失效。因此，整个系统都应围绕这个约束来设计。只要顺序排对了，大部分缓存收益几乎是“白送”的。 2. 尽量用 messages 来更新信息，而不是修改 system prompt。比如进入 plan mode 或修改日期，更好的方式通常是在对话过程中将这些信息插入到 messages 里。 3. 不要在对话中途切换工具或模型。应该用工具来表达状态变化（如进入 plan mode），而不是直接修改工具集。对于工具，尽量采用延迟加载，而不是移除。 4. 像监控系统正常运行时间一样监控缓存命中率。我们会对 cache break 设置告警，并将其视为事故来对待。哪怕只是几个百分点的命中率下降，也会显著影响成本和延迟。 5. 所有分叉操作都应共享父对话的前缀。如果你需要运行一个侧向计算（如 compaction、summarization 或 skill execution），就应该使用与父对话一致的 cache-safe 参数，这样才能命中父对话前缀的缓存。

Claude Code 从诞生之初就是围绕 Prompt Caching 构建的。如果你也在打造自己的 AI Agent，那么，你最好也这么做。