《Claude Code 源码解析系列》第4章｜Context 管理

前一篇讲 Prompt Runtime 时我们已经看到：Claude Code 每一轮都会重新组装 system prompt、项目记忆、动态上下文、工具说明、历史消息和工具结果。怎么说呢，

这一篇继续往下问：

这些信息越积越多以后Claude Code 怎么决定该留下什么、压缩什么、丢掉什么？

很多人容易把 Context 管理想成一句话：

把更多历史塞给模型。

这个理解只对了一半。

从使用者痛点一来看。模型失忆 vs Token 爆炸

• 如果只给少量上下文，模型忘记之前的操作，导致重复工作或错误决策。
• 如果一次性塞入所有历史。Token 超限直接卡死，成本和延迟飙升。按理说，

Context 不是一段文本。而是每轮重新装配的工作台

普通聊天里Context 确实像聊天记录。但 Claude Code 是编程 Agent，它的 Context 更像一个动态工作台。模型每一轮看到的远不止“使用者说过什么”——程序规则、项目规范、工具说明、文件读取结果、命令输出、错误日志、上一次改过的文件、当前任务进度。还有压缩后的历史摘要，全都可能摆上来。

真正的问题不是“要不要给上下文”。而是：

一个会持续读文件、跑命令、改代码的 Agent，怎么决定这一轮该给模型看什么？旧信息怎么留，空间快满时怎么压缩？

如果前一篇 Prompt 编写讲的是“怎么给模型组装操作手册”，那这一篇讲的是更底层的一层：

模型的工作台空间有限。Claude Code 必须一边干活，一边整理工作台。话说回来，

从使用者痛点二来看。信息爆炸导致的三大失败

• Token 爆炸：工具结果堆积，超过直接卡死。老实说，
• 上下文污染：旧文件内容或旧错误日志仍在上下文中。被模型误认为是当前事实，
• 压缩失忆：压缩过于粗糙，模型忘掉使用者原始意图或当前任务进度。

一、Context 不是保存聊天记录，而是“上下文调度”

先把前文的关键事实接回来：模型每次调用本身是无状态的。Claude Code 能连续工作。全靠外层 harness 每一轮都把“当前最需要的工作现场”重新装配好，再塞给模型。

一轮模型请求不是：

使用者问题 -> 模型

而是更接近这方面，

程序规则 + 项目规则 + 使用者偏好 + 当前工具说明 + 历史消息 + 工具调用结果 + 压缩摘要 + 当前使用者输入 => 本轮模型请求

这就是为什么 Context 管理不能被理解成“保存聊天记录”。更准确的名字应该是上下文调度它要回答以下具体问题：

• 哪些信息每轮必须保留？
• 哪些只留在运行时不该暴露给模型？按理说，
• 哪些可以缓存？按理说，哪些等模型需要时再读？
• 哪些旧工具结果已经过时？哪些历史必须压成摘要，
• 压完之后模型还得继续知道自己正在做什么。

二、为什么编程 Agent 的 token 会涨得特别快？

User Pain Point: 一次文件读取、一段堆栈追踪甚至一次全局搜索都可能产生数千 token。若不及时治理，这些信息会迅速占满窗口。

• Larger artifacts: 单个源码文件几千行；话说回来，测试失败带回长长 stack trace；搜索返回 dozens of matches。 按理说，
• Persistence requirement: 下一轮仍需知道：“刚才读了哪个文件？”、“错误发生在哪行，”、“已尝试哪些方案？”等关键事实，

Agent 的上下文增长不是线性“多聊几句”。而是工具调用不断追加环境信息，引发上述三种典型失败。这也解释了为何 Claude Code 的 Context 管理必须在主循环里持续进行容量治理——相当于常驻 GC 线程，而不是等堆满才一次性清理。

三、把 Context 放回 QueryEngine 主循环

User Pain Point: 开发者常把 Context 当作副产品，只在出现错误时才手动干预。它是主循环不可分割的一环。

1. 预取项目和会话信息 → 组装本轮上下文 → 请求模型 → 判断模型是回答还是调用工具 → 执行工具并写回消息历史 → 检查 token 压力 → 必要时清理/折叠/压缩 → 带着新状态进入下一轮。

The arrow segment H → I → J → B 表示：每一次工具结果都写回消息历史，接下来 评估这份历史是否还能安全喂给模型。没有这一步，主循环很快因 Token 超限或信息污染而崩溃。话说回来，

四、先做信息治理。再谈压缩

User Pain Point: 很多团队把 “Context Management = Compression” 视为唯一手段，却忽略了信息可见性与权威性的根本治理，从而导致频繁失忆或误判。

A mature agent must answer four categories of questions:

1️⃣ 可见性

这条信息该给模型看，还是只留在运行时？

• Sensitive API keys / 权限对象 – 不进 prompt.
• LARGE 文件 / 长日志 – 保留引用或摘要即可.

2️⃣ 权威性

程序规则 / 项目规则 / 使用者指令 / 长期记忆冲突时谁说了算？

• If project rule forbids editing generated files but user insists。system must enforce rule rar than let model guess.

3️⃣ 冷热分层

哪些是 Hot Context，哪些是 Warm，哪些是 Cold？

• *Hot*的观点是，最近一次测试失败日志.
• 再看*Warm*，两小时前已修复的旧错误.
• *Cold*的观点是。完整对话 transcript.

4️⃣ 形态转换

同一条信息该以原文、摘要、结构化状态、diff 还是引用形式存在？至于例子，txt
再看命令，pnpm test
至于状态，失败
关键错误这方面，TypeError: user.id should be string
说到相关文件。src/auth/session.ts
接下来的观点是，检查 mock user 构造逻辑
不同形态占用 token 差距巨大，对推理帮助也不同。
Context 管理是信息治理，压缩只是其中一种动作。

五、Claude Code 的压缩不是“一刀切”，而是分级防线 

The compression pipeline works like a series of increasingly aggressive guards. It prefers local。low‑loss clean‑ups before falling back to full‑summary abstraction.

. Tool Result Budget – 限制噪音源大小 


Bash 输出几千行日志

`Read` 大文件

`Grep` 返回 dozens of matches

`WebFetch` 拉回整页网页






The function applyToolResultBudget
ensures a single tool result never monopolizes entire workspace.
别让一个工具结果把整张工作台占满。

. Snip – 局部裁剪不破坏结构 

`snip` 把低价值的大段内容替换为标记或简短占位，同时保留消息链中的 ID 与前后关联。不过，直接删除会破坏 “tool_result ↔ 对话轮次” 的映射关系。
内容变短，账本不断。

. MicroCompact – 清理已过期的工具产出 

`MicroCompact` 专注于那些体积大且已被后续步骤覆盖的信息，例如旧的文件读取结果或旧的搜索块。它不会动及使用者原始提问或最近仍然活跃的回复/工具结果。
清垃圾，不改账本。

. Context Collapse – 折叠视图而非直接摘要 

`Context Collapse` 投影出更紧凑的上下文视图。如果折叠后 token 已低于安全阈值，就不必触发更昂贵的 `AutoCompact`。它类似于先把桌面材料分组折叠，而不是立刻烧掉所有纸张只剩会议纪要。其实，
能保留细粒度就别急着全局摘要。

. AutoCompact – 最终一步生成任务交接单

If all previous layers still exceed limit,`AutoCompact` produces a summary that functions as a **handover document** rar than a vague recap.
使用者主要请求
关键约束
涉及过的文件 & 关键事实
遇到的错误 & 已尝试修复
当前正在做什么
接下来应该做什么


This ensures that after compression model still knows exactly where task stopped and what to continue with.


——从痛点到实践的完整闭环 


Pain Point 1: Model forgetting vs Token overflow → Use balanced context scheduling.

Pain Point 2: Rapid token growth from tool results → Apply per‑tool budget。snip,micro‑compact before any global summary.

Pain Point 3: Incorrect or stale information polluting decisions → Periodically prune outdated tool outputs and keep only references/abstracts for cold data.

Pain Point 4: Over‑aggressive compression causing loss of task state → Ensure every compact step retains “当前正在做什么”和“接下来应该做什么”。


The core takeaway is that **Context Management = Continuous Information Governance**,not just an after‑‑fact compression script. By embedding visibility checks,authority resolution。temperature layering,and shape transformation into each iteration of QueryEngine loop,Claude Code can keep its working‑bench tidy while staying fully aware of ongoing programming mission.

。

---