【Claude Code-上下文实测】不要等上下文爆炸：Claude Code 长会话的可控压缩策略指南
非线智能API经验 [Claude Code-上下文实测] 第22篇
摘要
可控压缩策略的目标不是把历史变短，而是在长会话中保住任务状态。Claude Code 这类 coding agent 会不断积累 system prompt、项目上下文、工具定义、文件内容、工具结果、错误日志和历史对话；如果只依赖 auto-compact，压缩触发时机、摘要质量和失败恢复都不可控。
本文给出一套可落地的压缩策略：提前触发、分级保留、结构化摘要、工具结果外置、压缩后检查、用实验验证。核心原则是区分“必须保留原文”的高价值上下文和“可以摘要 / 清理”的低价值上下文，并让每次 compact 都可追踪、可复盘、可恢复。
数据来源：非线智能Nonlinear 官网
适用范围
这套策略适用于：
• 长时间运行的 Claude Code / coding agent 会话。
• 多轮调研、实现、测试、审查任务。
• 工具调用频繁、测试日志较大、MCP 输出较多的项目。
• 需要跨模型路由、prompt cache 或服务端 compaction 的 agent runtime。
它不假设某个固定 auto-compact 阈值，也不把 compaction 当成无损历史存储。
压缩触发策略
不要等上下文接近上限再压缩。建议设置多级触发：
| 触发条件 | 动作 |
|---|---|
| 单次工具输出超过预算 | 进入上下文前摘要 / 分页 |
| live tool window 超过预算 | 清理旧工具结果，保留摘要和 raw_ref |
| 会话进入阶段边界 | 生成阶段摘要 |
| 上下文使用率达到软阈值 | 主动 compact dynamic history |
| cache miss 连续上升 | 检查是否动态内容污染前缀 |
| 子任务完成 | 把子任务结果写入决策账本 |
软阈值要按模型和 provider 校准。一个保守起点是 65% 到 75% 使用率触发主动整理，而不是等到 90% 以上。
内容分级
压缩前，先把上下文分成四类：
| 类别 | 处理方式 | 例子 |
|---|---|---|
| 原文保留 | 不摘要、不改写 | 用户硬约束、权限边界、关键 API 契约 |
| 结构化摘要 | 用固定字段压缩 | 决策、已验证事实、测试状态 |
| 外置引用 | 原文离开上下文，保留 ref/hash | 完整日志、截图、大文件片段 |
| 丢弃 | 不再进入上下文 | 重复日志、已过期探索、无关输出 |
这个分级应由 agent runtime 执行，而不是让模型自由判断所有历史的重要性。
必须保留原文的内容
以下内容不应只靠摘要保留：
| 内容 | 原因 |
|---|---|
| 用户硬约束 | 摘要可能弱化“不要做”的边界 |
| 安全和权限要求 | 错误压缩会导致外部写入或危险命令 |
| 外部 API 契约 | 字段、类型、错误语义不能随意改写 |
| 当前 diff 的关键片段 | 后续修改依赖精确代码 |
| 未闭合工具调用状态 | 关系到协议状态机 |
| 测试失败根因的最小证据 | 修复方向依赖原始断言 |
原文保留不意味着无限保留全文。可以保留最小原文片段，并记录完整原文引用。
可以摘要的内容
适合摘要的内容：
| 内容 | 摘要应保留 |
|---|---|
| 已解决错误日志 | 错误、修复方式、验证状态 |
| 重复测试输出 | 失败测试名、退出码、关键 stack |
| 探索性讨论 | 最终结论和被排除方案 |
| 长搜索结果 | 命中路径、关键片段、选择理由 |
| 大文件阅读过程 | 读过哪些范围、发现什么 |
| 子代理调研 | 结论、证据等级、引用 |
摘要要区分“已验证事实”和“推测”。很多上下文腐烂来自把早期假设压缩成确定结论。
压缩摘要模板
推荐固定模板：
## Compact Checkpoint
### Current Goal
- ...
### Hard Constraints
- ...
### Verified Facts
- [current] ...
- [stale] ...
### Decisions
- Decision: ...
Rationale: ...
Rejected alternatives: ...
### Code State
- Changed files:
- Critical locations:
- Current diff summary:
### Tool State
- Tests:
- Failed commands:
- Archived outputs:
- Truncated results:
### Open Issues
- ...
### Next Steps
- ...
字段顺序固定有两个好处：人能快速检查遗漏，系统也能用 prefix diff 归因摘要变化。
压缩过程控制
一次可控压缩应包含以下步骤：
1、冻结当前工具状态，确认没有未闭合工具调用。
2、提取用户硬约束和安全边界，作为原文或高优先级字段保留。
3、把大工具结果外置，生成摘要、hash 和 raw_ref。
4、生成结构化 compact checkpoint。
5、检查摘要是否覆盖目标、约束、事实、决策、文件状态、下一步。
6、如果使用 pause_after_compaction，在继续前注入补充状态。
7、记录 compact event：时间、token 前后、触发原因、摘要 hash。
带 tools 的摘要阶段应明确约束：只输出文本摘要，不调用工具。
compact event 记录
每次压缩都应写一条事件：
{
"event_type": "compact",
"event_id": "compact_20260618_001",
"trigger": "context_usage_soft_limit",
"before_tokens": 142000,
"after_tokens": 42000,
"model": "claude-opus-4-7",
"preserved_constraints_hash": "hmac:...",
"summary_hash": "hmac:...",
"archived_artifacts": [
{
"type": "tool_result",
"path": "artifacts/test.log",
"sha256": "..."
}
]
}
这条记录用于复盘：压缩后如果模型遗忘约束，可以追查是摘要遗漏、注入失败，还是后续上下文污染。
验证实验
设计三类任务：
| 任务 | 压缩风险 |
|---|---|
| 调研型 | 来源多，容易丢证据等级 |
| 实现型 | diff 和约束容易丢 |
| 调试型 | 失败根因和日志状态容易混淆 |
对每类任务比较三种策略：
| 策略 | 说明 |
|---|---|
| 无主动压缩 | 只靠 auto-compact |
| 自由摘要 | 让模型自然总结 |
| 结构化可控压缩 | 使用模板、artifact、检查清单 |
记录任务成功率、token 成本、约束遗漏、compact 后恢复轮数、cache 命中变化。
失败模式
| 失败模式 | 触发原因 | 修复策略 |
|---|---|---|
| 摘要丢约束 | 没有硬约束字段 | constraints 原文保留 |
| 压缩后重复工作 | 已排除方案没记录 | decisions 记录 rejected alternatives |
| 根因漂移 | 失败日志摘要过粗 | 保留最小原始断言和 raw_ref |
| 无法复盘 | 只保留摘要 | compact event + artifact store |
| 压缩触发太晚 | 依赖 auto-compact | 软阈值主动压缩 |
| cache 被打碎 | compact 改写稳定前缀 | 只压缩 dynamic history |
工程结论
可控压缩是 agent runtime 的核心能力，不是一次性 prompt 技巧。压缩策略要提前触发、分级保留、结构化摘要、外置原文、记录事件、压缩后检查。真正的目标不是“少 token”，而是让长会话在变短之后仍然能正确继续。
参考链接
• Anthropic Compaction
• Anthropic Cookbook: Automatic context compaction
• Anthropic Cookbook: Context engineering, memory, compaction, and tool clearing
• anthropics/claude-code #28728
• anthropics/claude-code #26220
• Claude Code MCP Docs
• AkitaOnRails: Claude Code source analysis
本文由非线智能API Claude Code 行业专家整理编写
