Claude Code Context 管理研究系列（00）—— Claude Code 的 200K 账本
内容提要
本文研究Claude Code的上下文管理，核心是Prompt Cache作为设计底座。文章提出三条铁律：前缀匹配、字节变化即失效、断点决定缓存起点。由此衍生四大策略（压缩、结构化笔记、子代理分解、按需检索）和31条具体机制，所有设计均以维持缓存稳定为目标。文章还列出8处官方文档与源码不符之处，并预告后续7篇系列文章。
延伸解读
为什么没有“上下文管理”模块？
文章指出，Claude Code 源码中并不存在一个集中的 ContextManager 类，压缩、注入等逻辑分散在多个文件中。这并非设计缺失，而是因为缓存是横切关注点，类似日志记录。每个功能模块自行维护缓存不变量，避免上帝对象。这种去中心化设计让功能迭代更灵活，但也意味着理解整体行为需要跨文件追踪，增加了研究门槛。
缓存优先如何塑造反直觉设计
文章列举了多个看似奇怪的设计，如 CLAUDE.md 不注入 system prompt 而走 messages 段、日期变更通过 system reminder 单独发送、fork 子代理用占位符替换 tool_result 等。这些设计均以维持前缀缓存稳定为目标，避免因小变动导致整个缓存失效。理解这一原则，有助于解释 Claude Code 中许多看似低效或绕弯的实现，实为成本与性能的权衡。
官方文档与源码的差异提醒
文章列出 8 处官方文档与源码不符之处，如 @import 递归深度、auto-compact 阈值、/compact 所用模型等。这些差异可能源于文档更新滞后或团队沟通不畅。对深度用户而言，源码是更可靠的依据，但官方文档仍具参考价值。建议在依赖具体参数或行为时，以实际版本源码为准，并关注版本更新带来的变化。
Q&A
Claude Code 的上下文管理为什么以 Prompt Cache 为设计底座？
因为 Anthropic 的 Thariq Shihipar 曾表示整个 harness 都围绕 prompt caching 构建。Claude Code 的许多看似不合直觉的设计，如 CLAUDE.md 的注入位置、子代理的构造方式、skill listing 的增量发送等，追溯到底都是为了维持缓存稳定，避免缓存失效。
Anthropic Prompt Cache 的三条铁律是什么？
三条铁律是：1. 从头前缀匹配，只有前缀相同才能复用缓存；2. 一字节变化即前缀断裂，导致后续所有内容重新计算；3. 断点决定缓存起点，每次请求最多挂 4 个 cache_control 断点，断点之前的内容写入缓存。
Claude Code 为什么没有一个中央 ContextManager 模块？
因为缓存是一个横切关注点，类似日志，不适合集中管理。如果强塞进一个 ContextManager 会形成上帝对象，导致维护困难。Claude Code 采用分散实现，但通过铁的不变量——保 cache——来约束每个功能模块。
Claude Code 的四大上下文管理策略是什么？
四大策略是：Compaction（压缩）、Structured note-taking（结构化笔记）、Sub-agent decomposition（子代理分解）、Just-in-time retrieval（按需检索）。每个策略都为了维持缓存稳定而做出让步，例如压缩只影响 messages 段，CLAUDE.md 走 messages 段而非 system prompt，fork subagent 用占位符保持前缀一致，skill listing 用增量发送。
为什么 CLAUDE.md 不注入到 system prompt 而是放在 messages 段？
因为 CLAUDE.md 内容会变化，如果放在 system prompt 中，一旦变化就会导致整个前缀缓存失效。放在 messages 段的 prepend 位置，变化只影响 messages 缓存，不影响更稳定的 system 段缓存。
Claude Code 中 fork subagent 如何保持缓存前缀一致？
fork subagent 会将所有 tool_result 替换为占位符文本（如 "Fork started — processing in background"），这样多次 fork 的前缀字节完全相同，从而共享同一个缓存前缀，避免缓存失效。
官方文档与源码不符的 8 处差异中，关于 @import 递归上限和 auto-compact 阈值分别是什么？
官方文档称 @import 递归上限为 4-hop，但源码实际是 5-hop（MAX_INCLUDE_DEPTH = 5）。auto-compact 阈值官方说是 context 的 80%/90%，但源码实际是绝对值：contextWindow - 20K reservedOutput - 3K buffer。
Claude Code 的 31 条具体机制中，Compaction 策略包含哪些机制？
Compaction 策略包含 /compact（手动压缩）、auto-compact（阈值触发）、micro-compact（轮内低成本剪枝）、reactive-compact（API 返回 prompt_too_long 时应急）、sessionMemoryCompact（跨 session 持久化）、contextCollapse（feature-flag 灰度中的激进变种）、/clear（不总结只重置）、/rewind（时间轴级回退）等机制。
