Prompt Caching（提示缓存）是 Claude Code 速度和成本控制的核心机制。理解它的工作原理，能帮你避免无意间让缓存频繁失效、白白多花 Token 预算。
为什么需要 Prompt Caching
Claude 模型在两次 API 请求之间不会「记住」任何东西。这意味着每次你在 Claude Code 中发一条消息，它都要把完整上下文重新发一遍：系统提示词、项目上下文、之前所有的消息和工具结果，加上你的新消息。
由于新内容总是追加在末尾，每次请求的绝大部分内容和上一次是一样的——Prompt Caching 正是用来避免重复处理这部分未变化内容的机制。
缓存的组织方式：前缀匹配
API 通过匹配每个请求的**开头部分（前缀）**与最近处理过的内容来实现缓存。在正常的一轮对话中，前缀就是上一次的完整请求，只有最新的一次问答是新内容。
关键点：匹配是精确匹配。前缀中任何位置发生变化，都会导致该位置之后的全部内容重新计算——没有按文件或按片段的细粒度缓存。
请求的三层结构
为了最大化前缀匹配的命中率，Claude Code 把内容按「变化频率」从低到高排列：
| 层级 | 内容 | 何时变化 |
|---|---|---|
| 系统提示词 | 核心指令、工具定义、输出风格 | 加载的工具定义变化，或 Claude Code 升级 |
| 项目上下文 | CLAUDE.md、自动记忆、未限定范围的规则 | 会话开始时，或执行 /clear、/compact 之后 |
| 对话内容 | 你的消息、Claude 的回复、工具结果 | 每一轮都会变化 |
这个分层设计的意义：对话层的变化不会影响系统提示词和项目上下文层的缓存；但系统提示词层的变化会让后面所有内容的缓存失效，因为后续内容现在处于一个不同的前缀之后。
哪些操作不会破坏缓存
Plan Mode 和 Skill 加载的指令是作为对话消息追加的，因此缓存的前缀保持完整，不会失效。
# 这些操作 —— 缓存友好 ✅
> /plan 进入 Plan Mode 分析代码
> /some-skill 加载一个 Skill
# 都以对话消息形式追加，前缀缓存不受影响
哪些操作会破坏缓存
根据分层原理，以下操作通常会让缓存失效并触发重建：
# 这些操作 —— 会使缓存失效 ⚠️
/clear # 清空对话，项目上下文层重新加载
/compact # 压缩对话历史，项目上下文层重新加载
# 会话中途修改系统提示词相关的设置
# 比如切换 output style、加载新工具定义
系统提示词层的变化影响最大，因为它处于最前面的位置——一旦变化，后面的项目上下文层和对话层全部要重新计算和写入缓存。
实用建议：如何减少不必要的缓存失效
- 减少频繁的
/clear和/compact：只在真正需要清空上下文时使用，而不是习惯性地清 - 避免会话中途频繁切换 output style 或工具集：这类改动会波及系统提示词层
- 善用 Plan Mode 和 Skill：它们的指令走对话层，不会打断已建立的缓存
- 长时间稳定的会话更省钱：一次建立的缓存前缀，只要不触发上层变化，会一直被复用
如何检查缓存表现
如果发现某个项目的 Token 用量看起来异常高，可以留意是否触发了以下常见场景：
- 频繁执行
/clear（每次都要重建项目上下文层） - 会话中反复切换模型或权限模式（可能影响系统提示词层）
- 使用了会频繁改变工具定义集合的自定义配置
与 Claude Sonnet 5 的关联
值得一提的是，Claude Code v2.1.201 专门针对 Claude Sonnet 5 会话做了优化：不再用「对话中系统角色」传递 Harness 提醒信息，避免了这类提醒消息在对话中途插入导致前缀失配、缓存被打破的问题。这个改动本质上就是应用了本文讲的分层原理——把原本可能出现在「意外位置」的内容，改为不会打断前缀匹配的方式处理。
总结
Prompt Caching 对 Claude Code 的速度和成本影响巨大，理解「系统提示词 → 项目上下文 → 对话」这个三层结构和精确前缀匹配的规则，能帮你避免无意间频繁触发缓存重建，尤其是在长时间运行的 Agent 任务和后台代理场景中，缓存命中率的差异会直接反映在账单上。
来源：How Claude Code uses prompt caching — Anthropic 官方文档