← All Articles

Anthropic：Prompt Caching 是构建 Claude Code 的一切 — 7 条工程经验

AGI Hunt · Original

Anthropic 工程团队公开了构建 Claude Code 时的 7 条 prompt caching 实战经验。AGI Hunt 把英文原文翻译并加了几个生活化比喻。核心一句：缓存不是优化手段，是架构约束——从第一天起就要围绕 cache 来设计。

为什么 caching 在 Claude Code 里是基建级别

Anthropic 内部把 prompt cache 命中率当 server uptime 同等重要的指标监控。命中率掉了直接触发 oncall 告警。

为什么这么夸张？因为 Claude Code 这类 agent 产品有个特殊性——长对话。一个 session 几十轮，每轮都要把所有上下文重发给模型。每次从头算的话延迟和成本会爆炸。

Prompt caching 的原理一句话：前缀匹配。API 缓存从请求开头到每个 cache_control 断点之间的所有内容。下次请求前缀一样就直接复用。

下面 7 条经验全部围绕这个约束展开。

经验 1: 排好队形 — 越不变的越往前

既然靠前缀匹配，prompt 内容的排列顺序就至关重要。Anthropic 给出的最佳实践：

  1. 静态系统 prompt + 工具定义（全局缓存，所有 session 共享）
  2. CLAUDE.md 文档（项目级缓存，同项目内共享）
  3. Session 上下文（会话级缓存，单次会话内共享）
  4. 对话消息（逐轮增长，每轮只新增最后一条）

类比：收拾书桌，常年不动的参考书放最底层，这周要看的资料放中间，今天的草稿放最上面。每天坐下来不用把整张桌子翻一遍。

特别容易踩的坑：

经验 2: 别动 Prompt — 信息更新走消息流

如果信息真的过时了（时间戳、文件变更状态）怎么办？

Anthropic 的做法：别去改 prompt，把更新塞进下一轮消息里。

具体：用 <system-reminder> 标签把更新信息放进 user message 或 tool result。这样系统 prompt 纹丝不动，缓存完好。

设计思路：prompt 是「不可变的基础设施」，消息才是「流动的信息层」。把它们分开，缓存自然就稳了。

经验 3: 别换模型 — 缓存跟模型绑定

直觉的”简单问题切 Haiku 省钱、难题切 Opus”在 Claude Code 里反而最贵。

原因：缓存按模型隔离。换模型 = 之前积攒的所有缓存全部作废，得从头重建。重建缓存的成本往往比让 Opus 直接回答那个简单问题还要高。

所以 Claude Code 的策略：主对话自始至终用同一个模型。需要小模型干活时怎么办？用子 Agent——子 agent 有自己独立的上下文和缓存，不污染主对话缓存链。做完只把结果传回来。

类比：办公室里你不会让实习生坐到你工位上用你的电脑，而是给他分配一台独立机器，做完发结果。

这条原文还提了个相关警告：cache 是按账号隔离的。账号池中转、cc switch 来回切账号都会让命中率暴跌——文章作者亲眼看过有人因为账号池命中率过低反而暴露被封。

经验 4: 别碰工具 — Session 期间工具集不动

直觉：当前任务只用 3 个工具，把没用的 27 个移走 context 不更干净？

错。工具定义是缓存前缀的一部分。加一个、减一个，缓存就断。一断就是整个对话的缓存全部重建，代价远远超过多放几个工具定义的 token 开销。

看似在优化，实则在添乱。

经验 5: Plan Mode 的实现 — 用工具不用状态切换

Claude Code 有个 Plan Mode，进入后模型只思考不执行。直觉的实现：进 Plan Mode 把执行类工具移走，退出再加回来。

Anthropic 没这么干。他们的做法是保留所有工具不动，加了两个特殊工具：EnterPlanMode 和 ExitPlanMode。模型自己调用就进/退规划模式。“规划模式下不能执行”这个约束用 system message 传达，工具集不碰。

意外好处：模型可以自主判断何时进 Plan Mode——遇到复杂任务它自己 EnterPlanMode 先想清楚再动手，不需要用户手动切换。

经验 6: 延迟加载 — 工具用 stub 而非完整 schema

Claude Code 可能接入几十个 MCP 工具。把所有工具完整 schema 都塞进 prompt，token 太大；按需加减又会破坏缓存。

折中方案：延迟加载（lazy loading）。

一开始只放轻量 stub（存根），标记 defer_loading: true。模型看到的只是工具名 + 一句话描述，不含完整参数定义。需要用某个工具时通过 Tool Search 拉取完整 schema。

好处：prompt 前缀始终只包含轻量 stub，不会因为加载某个工具的完整 schema 而变化，缓存稳稳的。

类比：图书馆目录——先翻目录，找到想看的书再去书架取，不用把所有书都搬到桌上。

经验 7: Compaction 用 Cache-Safe Forking

长对话跑久了 context window 会满，需要压缩之前的对话成摘要腾空间。

直觉做法：另起一个 API 调用做压缩，用不同的 system prompt 不带工具定义……结果从第一个 token 开始就跟主对话缓存对不上。两条缓存链互相不复用，白白多花钱。

Anthropic 的解决方案叫 Cache-Safe Forking：

这样压缩请求跟主对话共享同一条缓存链，新增成本只有压缩指令本身。

同时还要预留压缩缓冲区给摘要输出留够空间。

新闻一条：原文顺带提到 Compaction 功能已经直接内置到 API 里，开发者可以直接用，不需要自己从头实现。

一句话总结：先确定约束，再围绕约束做设计

7 条经验其实在说同一件事：Prompt Caching 是前缀匹配。所有设计围绕这个约束展开。

这看起来是讲缓存优化，但本质是讲一种系统设计哲学：先确定约束，再围绕约束做设计。

不是「做完了顺便加个缓存」，而是从第一天起就围绕缓存来设计。

跟 Justin 已有笔记的连接

Justin 之前在 ~/CC/Learning/CC-Architecture/day6-services-api.md 的 “Prompt Cache 是一等公民” 段已经梳理过 CC 这套设计哲学，包括：

这次 Anthropic 官方博客的增量价值：

  1. “基建级别监控” 这条 Anthropic 官方背书——cache 命中率掉 oncall 告警，说明这不是”内部 nice-to-have”而是 SLO 级别的指标
  2. defer_loading: true + Tool Search 这两个具体机制名（之前你笔记里只笼统说”延迟加载”）
  3. EnterPlanMode / ExitPlanMode 实现 Plan Mode 用工具调用而非状态切换——这是个 architectural pattern，可推广到任何”模式切换不动 prompt”的场景
  4. Cache-Safe Forking 是个具体术语 + 在压缩场景的应用——你之前笔记里讲了 fork，没具体到 compaction 这个用例
  5. Compaction 已直接内置 API——开发者直接调，不用自己实现

对你自己的 CC harness 设计也有应用——你的 skills hub 设计本身就可以借这套：让 hub 主文件保持不变（前缀缓存），具体 workflow / spoke 在 user message 里 lazy load（不污染前缀）；mental-models.md 这种长文件应该按”越不动的越往前”重新组织（pre-write hooks 在最前面，案例 entries 按时间倒序）。

拧巴的地方 / 我的怀疑

文章本身硬料密度高（7 条经验都是真踩坑结论），但作为读者有几条值得追问：

  1. 缓存命中率门槛 — 修正：原文给了”few percentage points of cache miss rate can dramatically affect cost”——意思是 miss 几个百分点就当 incidents，相当于命中率要保持 95%+ 数量级。这条是微信版翻译掉的
  2. 延迟加载 stub 的代价 — Tool Search 本身要不要消耗 token / 触发模型推理？stub 描述写多详细才不会让模型选错工具？文章只给了机制名没给细节
  3. Cache-safe forking 的”压缩缓冲区”具体多大 — 没给数字，工程上很难直接照搬
  4. 账号池命中率暴跌的具体阈值 — 翻译里”号没了”是轶事，没给具体数据。如果有人做账号池中转，这条要怎么量化决策？
  5. EnterPlanMode 这个工具的存在让模型自主决策何时进规划模式——但如果模型 misjudge 该不该进 Plan Mode 怎么办？文章只提了 upside 没说 failure mode

翻译 vs 原文 — 译者加了什么、漏了什么

AGI Hunt 翻译保真度高，但有 3 处译者自加 + 2 处原文细节漏译。原文 Anthropic 博客 2026-04-30 发布，作者 Thariq Shihipar (Claude Code team)，标题 Lessons from building Claude Code: Prompt caching is everything。

译者自加（不是原文措辞，但比喻无害）： - “书桌比喻” - “办公室实习生（不会让实习生坐到你工位上）” - “图书馆目录索引” - 账号池中转 / cc switch 切账号那段：原文完全没提——这是 AGI Hunt 自己加的中文场景应用警告

原文漏译的 4 个具体细节（值得直接引用原文）：

  1. 100k tokens 的具体例子：原文给了”100k tokens into a conversation with Opus and want to ask a question that is fairly easy to answer, it would actually be more expensive to switch to Haiku than to have Opus answer”——这条给了具体规模，不只是抽象论断
  2. Claude Code 的 Explore agents 用 Haiku：原文提了具体落地案例 “We do this often with Claude Code’s Explore agents, which use Haiku”。Hand-off message 是 Claude 主对话和子 agent 之间的 protocol——微信版省略了
  3. Plan Mode 的具体 system message 内容：原文写 “explore the codebase, don’t edit files, and call ExitPlanMode when the plan is complete”——可以直接借鉴的指令模板
  4. Tool Search 已通过 API 暴露：原文说 “You can also use the tool search tool through our API to simplify this”——开发者可以直接调用，不用自建 stub 系统。微信版略过了这层

最关键的一条原文措辞（建议保留英文）：

Monitor your cache hit rate like you monitor uptime. “We alert on cache breaks and treat them as incidents. A few percentage points of cache miss rate can dramatically affect cost and latency.”

—— 微信版翻译掉了”few percentage points 就能 dramatically affect cost”这句关键定量论断。这条直接回答了”命中率多低算事故”——几个百分点的 miss 都被当 incident。

原文 metadata: - Date: April 30, 2026 - Category: Claude Code - Reading time: 5 min - 作者: Thariq Shihipar（Claude Code team 技术员工）