构建 Claude Code 的经验教训：提示缓存至关重要 | Claude

📌 One-Sentence Summary

本文详细阐述了在优化 Claude Code 提示缓存过程中得出的关键且常反直觉的经验教训，强调围绕前缀匹配缓存来设计智能体的整体架构对于性能和成本至关重要。

📝 Summary

这篇来自 Claude 博客的文章解释了提示缓存如何成为使 Claude Code 这类长时间运行的智能体产品变得可行的基础技术。其核心原理是提示缓存基于前缀匹配运作，这意味着对请求开头的任何更改都会使整个缓存失效。作者分享了在规模化构建 Claude Code 过程中学到的几个关键且反直觉的经验教训。这些教训包括：将提示词结构设计为静态内容在前、动态内容在后；使用消息（如系统提醒）而非修改系统提示词来避免缓存未命中；在会话中途绝不更换模型或工具，因为这会导致缓存失效；以及围绕缓存约束来设计诸如“计划模式”等功能，即在请求中保留所有工具，并使用工具来模拟状态转换。文章还详细介绍了一种用于压缩（总结对话历史）的“缓存安全分叉”技术，该技术通过复用完全相同的系统提示词和工具定义来维持缓存命中。核心要点是，提示缓存并非事后才考虑的因素，而是一个应塑造整个智能体架构的首要设计约束。

💡 Main Points

1. 提示缓存是前缀匹配；对前缀的任何更改都会使整个缓存失效。 API 会缓存从请求开始到每个 cache_control 断点之前的所有内容。因此，内容的顺序至关重要。静态内容（系统提示词、工具）必须放在前面，动态内容（对话消息）放在最后，以最大化跨会话的共享缓存命中率。
2. 使用消息进行更新，而不是修改系统提示词，以保留缓存。 使用时间戳或文件更改等动态信息更新系统提示词会导致缓存未命中。更好的方法是通过下一条用户消息或工具结果中的系统提醒标签来传递这些信息，这样可以保持缓存前缀不变。
3. 切勿在会话中途添加或删除工具；应使用工具来模拟状态转换。 更改工具集会使整个对话的缓存失效。不要为不同模式（例如计划模式）更换工具，而应在请求中保留所有工具，并使用诸如 EnterPlanMode 之类的工具来改变智能体的行为。这可以保留缓存前缀，并允许智能体自主进入不同模式。
4. 对于压缩等辅助计算，应使用具有相同前缀的“缓存安全分叉”。 当需要总结对话以释放上下文时，使用不同的系统提示词进行单独的 API 调用将产生完整的、未缓存的输入成本。解决方案是复用完全相同的系统提示词、工具和对话历史，仅将压缩提示词作为新消息附加，以维持缓存命中。

💬 Key Quotes

• 像 Claude Code 这样的长时间运行的智能体产品之所以可行，是因为提示缓存使我们能够复用先前往返的计算结果，从而显著降低延迟和成本。
• 提示缓存通过前缀匹配工作——API 会缓存从请求开始到每个 cache_control 断点之前的所有内容。
• 在对话中途更改工具集是人们破坏提示缓存最常见的方式之一。
• 我们会对缓存中断进行警报，并将其视为事故处理。几个百分点的缓存未命中率就可能极大地影响成本和延迟。
• 提示缓存是前缀匹配。前缀中任何位置的任何更改都会使其之后的所有内容失效。请围绕这一约束来设计你的整个系统。

📊 Article Meta

Read Full Article