13 - 上下文管理策略

1. 定位：为什么上下文管理是第一优先级

Claude Code 的上下文窗口是最稀缺的资源。所有交互——你的输入、AI 的输出、工具调用结果、CLAUDE.md 内容——都在消耗这个有限的窗口。

核心事实：

• 性能随上下文填满而下降 — 窗口越满，AI 越容易遗忘早期指令、产生幻觉、重复犯错
• 上下文 = 钱 — 每个 token 都有真实成本，浪费的上下文就是浪费的钱
• 上下文退化不可逆 — 一旦窗口被低质量内容填满，没有办法"选择性遗忘"，只能压缩或重来

把上下文窗口当作一块有限的白板。 你不会在白板上随便写，同样也不应该在上下文中堆积无用信息。

2. 上下文窗口基础

什么占用上下文

来源	占比	说明
系统提示	~5-10%	CLAUDE.md、settings、Skill 元数据，会话启动时自动加载
你的输入	~15-25%	Prompt 文本、@ 引用的文件内容
AI 的输出	~25-35%	回答文本、代码块、分析内容
工具调用结果	~30-40%	Read/Grep/Glob 返回的文件内容、Bash 输出

工具调用结果是最大的上下文消费者。一次 Read 一个 500 行文件就可能消耗数千 token。

自动压缩

当上下文窗口接近满载时，Claude Code 会自动触发压缩（summarization）：

• 保留最近的对话和关键信息
• 压缩早期对话为摘要
• 这个过程可能丢失细节

不要依赖自动压缩。 主动管理远优于被动抢救。

状态栏监控

Claude Code 状态栏显示当前上下文使用量。养成习惯定期查看：

• < 50%：安全区，继续工作
• 50-70%：注意区，考虑 /compact
• > 70%：危险区，立即 /compact 或 /clear

3. 会话管理命令速查

/clear — 清空会话

维度	说明
何时用	切换任务、上下文严重退化、完成当前任务开始新任务
效果	完全清空对话历史，回到初始状态（CLAUDE.md 重新加载）
示例	完成功能 A 的开发后，/clear 再开始功能 B

/compact [指令] — 压缩保留

维度	说明
何时用	上下文 > 50%、想继续当前任务但释放空间
效果	压缩对话历史为摘要，可指定保留什么
示例	/compact 保留所有已修改文件路径、当前任务进度、测试命令

自定义保留模板（推荐写入 CLAUDE.md）：

/compact 保留：
1. 当前任务目标和进度
2. 已修改的文件清单
3. 未完成的步骤
4. 关键的架构决策

/rewind（Esc×2）— 撤销最近一轮

维度	说明
何时用	AI 最后一轮回复跑偏，想回到之前的状态重试
效果	撤销最近一轮 AI 回复和你的输入
示例	AI 给了错误的方案，Esc×2 撤销后重新提问

--continue — 继续上次会话

维度	说明
何时用	意外关闭终端、需要恢复未完成的工作
效果	恢复最近一次会话的完整上下文
示例	claude --continue

--resume — 恢复指定会话

维度	说明
何时用	需要回到之前某个特定会话继续工作
效果	列出历史会话供选择恢复
示例	claude --resume 选择要恢复的会话

/rename — 重命名会话

维度	说明
何时用	给会话一个有意义的名字，方便后续 --resume 查找
效果	修改当前会话的标题
示例	/rename 用户认证-OAuth实现

4. 主动控制策略

一任务一会话纪律

这是最重要的上下文管理策略。不同类型的任务使用不同会话：

❌ 一个会话干所有事：探索代码 → 写功能 → 修 Bug → 审查 → 提交

✅ 按任务分会话：
  会话 1：探索认证模块架构
  会话 2：实现 OAuth 登录
  会话 3：审查 OAuth 代码
  会话 4：修复审查中发现的问题

每个会话聚焦单一目标，上下文利用率最高。

/compact 保留模板

在上下文达到 50% 时主动压缩。建议在 CLAUDE.md 中配置标准保留模板：

## 上下文管理

执行 /compact 时默认保留：
- 当前任务目标（一句话）
- 已完成和未完成的步骤
- 已修改文件清单及关键改动
- 约定的测试命令和验证方法
- 本会话中做出的架构决策

检查点模式

大任务拆成里程碑，每个里程碑后压缩或清空：

里程碑 1：数据模型设计完成
  → /compact 或 git commit + /clear

里程碑 2：Service 层实现完成
  → /compact 或 git commit + /clear

里程碑 3：API 层 + 测试完成
  → /compact 或 git commit + /clear

关键：里程碑之间用 git commit 保存进度，这样 /clear 不会丢失工作。新会话可以通过 git log 和 git diff 恢复上下文。

完整的检查点执行流程（WIP commit + Handoff 模板 + 恢复 SOP）详见 19-上下文管理执行手册

两次纠错规则

如果 AI 在同一个问题上修了两次还不对：

第 1 次修复失败 → 给更明确的指令再试
第 2 次修复失败 → 停！执行 /clear，在新会话中重新描述问题

为什么：反复纠错会在上下文中积累错误的尝试和你的否定反馈，AI 越改越乱。干净的会话重新开始反而更快。

5. 用子代理保护主会话上下文

子代理在独立上下文中运行，不消耗主会话窗口。主会话只接收子代理返回的结果摘要。

Explore Agent 做研究

❌ 在主会话中反复搜索：
  "搜 auth 相关文件" → 搜 "用户认证" → "看看 middleware" → ...
  （每次搜索结果都留在主会话上下文中）

✅ 用 Explore Agent：
  "用 Explore Agent 搜索项目中所有认证相关模块，给我一份总结"
  （搜索过程在子代理上下文中，主会话只收到一份总结）

context:fork 隔离执行 Skill

需要执行重型分析的 Skill（如 /impact、/health-report），可以用 context: fork 在隔离上下文中运行：

---
name: impact
context: fork
agent: Explore
---

效果：Skill 的执行过程不占用主会话上下文，只有最终结果返回主会话。

后台子代理

用 run_in_background: true 派发非紧急任务：

研究性任务 → 后台 Explore Agent
代码扫描 → 后台 Bash Agent
依赖检查 → 后台 general-purpose Agent

后台代理完全不占用主会话上下文，完成后通过 output_file 获取结果。

6. 上下文退化：识别与应对

退化信号

信号	严重度	说明
重复之前被否决的方案	中	AI 忘记了你的反馈
忘记 CLAUDE.md 中的规则	中	系统提示被压缩时丢失
同一个错误修了又犯	高	上下文中充满矛盾信息
回答变得笼统、不具体	中	AI 失去了具体的代码上下文
开始产生幻觉（编造不存在的 API）	高	严重退化，立即处理
响应速度明显变慢	低	上下文过大导致推理变慢

应对策略

轻度退化（忘记规则、方案重复）：
  → /compact 带明确的保留指令

中度退化（反复犯错、回答笼统）：
  → /compact 如果还需要当前上下文
  → /clear 如果可以重新开始

重度退化（幻觉、编造 API）：
  → 立即 /clear，不要继续在退化的上下文中工作
  → 新会话中重新描述任务

7. 成本视角：上下文 = 钱

上下文管理不只关乎质量，还直接影响费用。Claude API 按 token 计费，更多上下文 = 更多 token = 更多钱。

成本公式

每轮交互成本 ≈ (累积上下文 token × 输入价格) + (输出 token × 输出价格)

重要认知：上下文是累积的。第 10 轮对话要处理前 9 轮的所有内容。同一个会话中的第 20 轮，成本远高于新会话的第 1 轮。

模型选择策略

主会话：Opus — 最强推理能力，处理复杂任务
子代理：Sonnet — 编码能力接近 Opus，成本更低
后台任务：Haiku — 最快最便宜，搜索和简单分析足够

降低成本的核心不是少用 AI，而是每次交互都高质量 — 精确的 prompt、及时的 /compact、合理的模型分级。

模型定价和详细成本分析参见 doc-03 §10 成本控制 和 12-效率最佳实践 §11.5。定价变动频繁，不在此处重复。

8. Prompt Caching：上下文设计的底层约束

Claude Code 的架构围绕 Prompt Caching（前缀缓存）构建。理解这个机制，能让本文档和 doc-01、doc-05 中的很多经验规则从"建议"升级为"有机制支撑的设计约束"。

机制要点

• 缓存按前缀匹配：从请求开头到 cache_control 断点之前的内容被缓存
• Claude Code 的 Prompt 顺序固定：System Prompt → Tool Definitions → Chat History → 当前输入
• 高缓存命中率同时降低成本、提升速率限制额度和响应速度

常见的缓存破坏行为

行为	后果
System Prompt 中放时间戳等动态内容	每次请求前缀变化，缓存失效
会话中途增删 MCP/工具	工具定义变化，缓存失效
非确定性地打乱工具定义顺序	同上

Claude Code 自身通过在用户消息中注入 <system-reminder> 传递动态信息（如当前时间），而非修改 System Prompt，正是为了保护缓存前缀。

对设计取舍的影响

这个机制解释了体系中多条规则的底层原因：

• MCP 不超过 5 个（doc-05）→ 每个 MCP Server 带来 20-30 个工具定义，固定占用缓存前缀空间
• Skill 描述符要精简（doc-02）→ Skill 元数据常驻工具定义层，膨胀直接挤压可用窗口
• 模型切换要谨慎（§7）→ 切换模型需为新模型重建缓存，100K 会话从 Opus 切 Haiku 反而更贵；需要切换时用 Subagent 交接，而非中途换模型

9. 常见反模式

厨房水槽会话

症状：一个会话做所有事——探索、实现、调试、审查、提交。

后果：上下文快速耗尽，AI 在不相关的历史中迷失方向。

治疗：一任务一会话。完成一个任务就 /clear 或新开会话。

无限探索

症状：不断让 AI 搜索更多文件、读取更多代码，但没有明确的行动目标。

后果：大量搜索结果填满上下文，真正需要参考的内容被挤出。

治疗：探索之前先明确目标。用 Explore Agent 隔离搜索，主会话只接收结论。

过度纠正

症状：AI 每产出一段代码就反复要求修改细节，积累大量来回对话。

后果：修改历史占满上下文，AI 在多个版本之间困惑。

治疗：一次性给出所有修改意见，而不是逐条追加。超过两次纠正就 /clear 重来。

信任-验证鸿沟

症状：让 AI 生成大量代码但不验证，等到最后才发现基础假设是错的。

后果：大量无效工作占用了上下文，回退成本极高。

治疗：小步验证。每实现一个函数就跑测试确认。验证失败时及时止损。

10. 与其他子系统的关系

CLAUDE.md ──定义──→ /compact 保留模板、上下文管理规则
Skills ──消耗──→ Skill 执行占用上下文（context:fork 可隔离）
子代理 ──保护──→ 子代理在独立上下文中运行，保护主会话
Hooks ──不影响──→ Hook 在 Claude Code 外执行，不占用 AI 上下文
07-操作手册 ──补充──→ §8 从人的操作角度描述上下文管理
12-效率实践 ──补充──→ §11.5 从成本角度分析 token 消耗
doc-19 上下文管理执行手册 ──→ 本文档的执行 SOP 层（WIP commit、Handoff、会话切换 Checklist）
/checkpoint Skill ──→ 检查点操作的一键执行
/handoff Skill ──→ 会话恢复的一键执行