Thariq推文【Lessons from Building Claude Code: Prompt Caching Is Everything】精读

Prompt Caching 不是优化项而是 Agent 系统设计的起点最近读到一篇很有启发的文章Lessons from Building Claude Code: Prompt Caching Is Everything。它讨论的不是一个局部技巧而是一个很容易被忽略的系统级事实对于长会话、长上下文、频繁往返的 Agent 产品来说Prompt Caching 往往不是“锦上添花”的优化而是决定成本、延迟和产品形态的基础设施。如果一句话概括这篇文章的核心观点那就是Prompt cache 命中率会反过来塑造你的 prompt 结构、工具设计、模型切换策略甚至影响功能应该怎样实现。这篇文章主要讲了什么文章围绕 Claude Code 的工程经验分享了一个核心结论Prompt caching 的本质是前缀复用prefix match。也就是说只有当请求前面那一大段内容保持稳定时缓存才能命中。一旦前缀中某个位置发生变化后续内容的缓存收益就会被破坏。这直接带来一个非常反直觉的设计原则你不能把缓存当成底层能力接一下就完事了而应该从系统设计阶段就围绕“如何保持前缀稳定”来做架构。agent prompt架构如下文章具体展开了几个关键经验Prompt 的内容顺序极其重要应该把稳定内容放前面把动态内容放后面。不要轻易改 system prompt很多变化更适合通过消息注入。不要在会话中途切换模型否则缓存会失效。不要在会话中途增加或删除工具否则会破坏缓存前缀。像压缩上下文、做总结、启动子任务这类“分叉操作”也应该尽量复用原会话的前缀。这些经验看起来像实现细节但其实都在说明一件事Agent 的很多功能设计不应该只看“语义上对不对”还要看“缓存上稳不稳”。为什么 Prompt Caching 这么重要传统对话产品里一次请求的 prompt 相对较短即使有一些重复浪费也未必特别夸张。但 Agent 类产品不一样。Agent 往往会有这些特点system prompt 很长工具定义很多会话历史很长每一步都要多轮调用模型一个任务可能持续几十轮甚至上百轮在这种情况下如果每一轮都把大量重复 token 重新算一遍成本和延迟都会迅速膨胀。缓存命中得越好单次交互越便宜响应越快产品能给用户的额度和体验也越“慷慨”。Claude Code 团队甚至会监控 prompt cache hit rate并在命中率明显下降时当成事故处理。这说明在真实产品里缓存命中率已经不是可有可无的指标而是直接影响业务表现的核心指标。第一条经验Prompt 结构要为缓存而排布文章里最重要的工程原则之一就是静态内容放前面动态内容放后面。Claude Code 的大致组织方式是全局稳定的 system prompt 和 tools项目级上下文例如Claude.md会话级上下文当前对话消息这样安排的目的是让尽可能多的请求共享同一段前缀。这背后的启发非常强我们平时设计 prompt往往先考虑“模型好不好理解”但做 Agent 时还要增加一个维度叫“不同请求之间能不能最大化共享前缀”。文章还提到一些很容易忽略的缓存杀手例如在静态 system prompt 里放精确时间戳工具定义顺序不稳定工具参数在不同轮次中悄悄变化这些改动看上去很小但因为它们出现在前缀区域会让缓存命中率断崖式下降。第二条经验能用消息更新就不要改 System Prompt这是文章里一个特别实用的建议。很多时候系统里的信息会变化比如当前时间变了用户修改了文件系统状态切换了直觉上我们很容易去更新 system prompt。但问题是一旦你改了 prompt 前面的稳定部分就等于主动放弃了缓存。Claude Code 的做法是尽量把这些变化通过下一轮消息补进去而不是直接修改原本稳定的提示词。例如用类似系统提醒的消息告诉模型“现在是星期三”或者“某个文件刚刚被修改了”。这背后的思路非常值得借鉴让 system prompt 承担“长期稳定的规则”让 message 承担“临时变化的状态”。这不仅更利于缓存也能让提示词职责更清晰。第三条经验不要在会话中途切模型很多人会觉得复杂问题用大模型简单问题切到便宜小模型更省钱。但文章指出在长上下文场景里这件事常常恰恰相反。因为 prompt cache 是和具体模型绑定的。如果一个会话已经在某个模型上积累了大量缓存这时候切到另一个模型意味着你要重新构建整段上下文对成本的打击可能比继续用原模型更大。也就是说从单次调用看小模型更便宜但从整段会话看切模型可能更贵。这是一种很典型的“局部最优不等于全局最优”。文章给出的更好方案是如果确实需要换模型就通过子代理或子任务来做把主会话保持在原模型上让另一个模型去处理局部任务。这个建议非常像操作系统里的进程隔离思路不是把主上下文打碎重来而是把局部工作外包出去。第四条经验不要在会话中途增删工具这一条对做 MCP、函数调用、工作流 Agent 的人尤其重要。很多人会本能地觉得当前轮次需要什么工具我就给模型什么工具不需要的工具就先移掉这样更干净。但从缓存角度看这种做法代价很高。因为工具定义通常也在 prompt 前缀里只要你增删工具整个缓存前缀就变了。Claude Code 的解决方式很巧妙不要真的切换工具集而是把“状态切换”也建模成工具或消息。比如它们的 Plan Mode不是进入计划模式就换一套只读工具而是工具仍然保持不变通过EnterPlanMode/ExitPlanMode这样的工具表达状态切换再用系统消息告诉模型当前处于计划模式应该只做探索不做修改这样既保住了缓存也让状态机更一致。文章还提到另一个思路对于大量工具不要动态移除而是通过延迟加载、工具搜索、轻量 stub 等方式让“工具列表的骨架”保持稳定只有真正用到时再补充细节。这说明一个重要原则为了缓存稳定很多动态能力应该设计成“延迟展开”而不是“动态重写前缀”。第五条经验上下文压缩和总结也要做成 Cache-Safe文章中我觉得最有洞察力的一部分是它谈到了 compaction也就是上下文窗口不够用时对历史对话做总结压缩。直觉上这件事很简单另起一个请求把历史喂给模型让它总结一下再带着总结继续。但这里隐藏了一个大坑如果这个“总结请求”用的是另一套 system prompt、另一套工具或者干脆没有工具那么它和原会话的缓存前缀就完全对不上。这样一来你会为整段历史再次付费成本非常高。Claude Code 的做法是保持和父会话几乎一致的前缀复用相同的 system prompt、上下文和工具定义把“请帮我压缩总结”作为新的用户消息追加到末尾这样从 API 视角看它还是那条老会话的自然延续于是前缀缓存可以继续命中。这个经验非常有启发因为它其实不只适用于 compaction也适用于很多“旁路任务”对历史做总结执行技能或子任务生成中间摘要做 fork 分支探索凡是这类操作只要它们共享足够多的父上下文就应该尽量做成 cache-safe fork。这篇文章给我们的真正启示如果只看表面这篇文章像是在讲一套 prompt caching 的调优技巧但我觉得它真正传达的是更底层的方法论设计 Agent不要只从能力和语义出发还要从“可缓存性”出发。换句话说Prompt Caching 不是最后再加的一层性能优化而应该成为产品设计时的“约束条件”。它会影响prompt 怎么分层状态怎么表达工具怎么组织模型怎么协作长上下文怎么压缩功能切换怎么实现很多看起来“更自然”的实现方式在缓存层面可能都不是最优解。真正成熟的 Agent 系统往往不是语义上最直观的那种而是既满足语义又尽量保持前缀稳定的那种。如果我们自己做 Agent可以直接借鉴什么结合这篇文章我觉得至少可以马上落地下面几条实践1. 把 Prompt 分成稳定层和变化层稳定层包括核心 system prompt固定工具定义项目级说明文档变化层包括当前任务状态临时提醒文件变更用户最新输入目标是让稳定层尽量不变把变化都压到后面。2. 给缓存命中率做监控如果一个 Agent 产品已经进入真实使用阶段就应该监控cache hit rate平均输入 token 成本首 token 延迟因 prompt 变化导致的缓存失效比例否则你很可能只看到“模型越来越贵”却不知道问题出在系统设计上。3. 用消息表达状态不要频繁改工具和 Prompt像“进入规划模式”“当前时间更新了”“文件刚被改过”这类信息优先考虑system reminder状态消息显式状态工具而不是直接改前缀。4. 把复杂能力设计成子任务而不是打断主会话如果某一步适合小模型、专门模型或单独执行就用子 agent、handoff、fork 的方式处理不要轻易破坏主会话的缓存积累。5. 对总结、压缩、分叉任务做“前缀复用”设计任何旁路任务只要仍然依赖父会话就应优先复用父会话的前缀环境而不是临时起一个完全不同的调用模板。结语这篇文章最有价值的地方在于它提醒我们重新理解 Agent 工程里的“优化”。在很多传统系统里缓存是性能优化但在 Agent 系统里尤其是长上下文、多轮调用、强工具依赖的系统里缓存其实已经上升为产品可行性的条件之一。当一个系统的成本、延迟、额度策略都和缓存命中率强相关时你就不能把它当成底层黑盒而必须让它进入架构设计。所以如果你正在做自己的 coding agent、workflow agent或者任何长会话 AI 产品这篇文章最值得记住的一句话可能不是“prompt caching 很重要”而是把缓存当成系统设计的一部分而不是部署完成后才想起来补上的优化。