5.4　在大型代码库探索中有效管理上下文

这一条考什么

这一条考你在 Claude Code 或 Agent SDK 里探索大型代码库时，怎么防止长会话中出现上下文退化。你要能认出上下文退化的症状，知道如何用草稿文件（scratchpad）、子 Agent 委派、阶段摘要、结构化状态导出（manifest）和 /compact 来保留关键发现，并且在会话崩溃之后能恢复。

核心概念

上下文退化的症状

长时间探索之后，上下文里堆满了读过的文件内容、grep 输出和中间推理。典型的表现是：

• 回答前后不一致，比如前面说缓存失效在 CacheManager.invalidate() 里，后面又说在别处；
• 不再引用之前找到的具体类名和文件路径，转而说"通常这类系统会用观察者模式"这种典型模式的泛泛之谈；
• 忘记之前已经确认过的约束。

只要看到"模型开始谈典型模式，而不是具体代码"，就说明上下文已经饱和，或者早期的细节不再被充分关注。

草稿文件：把关键发现移出对话历史

让 Agent 维护一个草稿文件（比如 notes/exploration.md），每确认一个关键发现就写进去：模块职责、关键符号、文件路径和行号、架构关系、未解决的问题。之后回答问题时先读这个文件，而不是依赖对话历史里可能已经被稀释的内容。

# exploration.md
## 已确认
- 退款入口：api/refunds.py::create_refund（L40），调用 services/refund_service.py::RefundService.process
- RefundService 依赖 PaymentGateway（gateways/stripe.py）与 LedgerWriter（ledger/writer.py）
- 金额校验在 RefundService._validate_amount（L88），上限读取 settings.REFUND_MAX
## 待查
- LedgerWriter 失败时是否回滚网关退款？

草稿文件是持久的，可以跨越上下文边界：/compact、/clear、新会话之后都还在。

子 Agent 委派：隔离冗长的探索输出

主 Agent 负责高层理解和协调，把具体的、边界清楚的问题委派给子 Agent：

• "找出所有和支付相关的测试文件，列出路径和覆盖的函数"
• "追踪退款流程的依赖链，返回调用图摘要"

子 Agent 在自己的独立上下文里读几十个文件、跑大量 grep，最后只把精简的结论返回给主 Agent。主 Agent 的上下文里只留下结论，不会被原始输出淹没。在 Claude Code 里可以通过 Task 工具或者 .claude/agents/ 里定义的子 Agent 来实现。

阶段摘要：把前一阶段的结论注入下一阶段

探索往往是分阶段进行的，比如先摸清渲染模块，再看物理模块。进入下一阶段之前：

1. 把当前阶段的关键发现总结成结构化摘要（具体类名、路径、关系）；
2. 启动下一阶段的子 Agent（或新上下文）时，把这份摘要作为初始上下文注入。

这样新阶段既有干净的上下文，又不会丢掉前一阶段的成果。比"继续在已经饱和的会话里硬撑"和"/clear 后从零开始"都好。

结构化状态持久化与崩溃恢复

多 Agent 的长任务可能半路崩溃，比如处理了 28 份文档中的 12 份时。恢复设计应该是：

• 每个 Agent 定期把结构化状态导出到已知位置：已完成的项目 ID、提取到的发现、来源、待办事项、schema 版本；
• 协调者维护一个 manifest，记录各 Agent 状态文件的位置和进度；
• 重启时，协调者先读 manifest，再把相关状态注入各 Agent 的提示词，从断点继续。

{
  "run_id": "research-2026-10-21",
  "schema_version": 2,
  "agents": {
    "web_search": {"state_file": "state/web_search.json", "status": "done"},
    "doc_analyzer": {"state_file": "state/doc_analyzer.json", "status": "in_progress",
                     "completed_ids": ["doc-01", "doc-02", "doc-12"], "next": "doc-13"},
    "synthesizer": {"state_file": "state/synth.json", "status": "partial"}
  }
}

和其他方案比较：每个 Agent 各自读写自己的状态文件，缺少协调者的统一视图，彼此之间容易不一致；只保存协调者的对话日志，恢复时要重放，成本高而且数据不结构化；放进向量库靠语义检索恢复，结果不精确，可能会漏掉。

/compact：压缩冗长的上下文

在 Claude Code 里，探索会话被冗长的调查输出塞满时，可以执行 /compact。它会把对话历史压缩成摘要，释放上下文空间，还可以附带指示，告诉它摘要时重点保留什么：

/compact 保留所有已确认的类名、文件路径与调用关系，丢弃原始 grep 输出

/compact 有损，所以最好配合草稿文件一起用：关键事实先写进文件，再压缩。/clear 则会清空全部上下文，一般只在切换到毫不相关的任务时使用。

正确做法与反模式

• 正确：主 Agent 保持高层协调，把"找所有测试文件"、"追踪退款依赖"这类具体问题交给子 Agent。反模式：主 Agent 亲自把几十个文件全读进自己的上下文。
• 正确：维护草稿文件记录关键发现，后续提问时参考它。反模式：每隔 15 分钟定时清空上下文，或者指望换一个更大上下文的模型来解决问题。
• 正确：阶段结束时先做摘要，再把摘要注入下一阶段的子 Agent。反模式：/clear 后从零开始，或者在已经饱和的会话里继续探索新模块。
• 正确：每个 Agent 把结构化状态导出到已知位置，协调者读取 manifest 后恢复。反模式：崩溃后整个流程重跑，或者各 Agent 各自恢复、缺乏统一视图。
• 正确：上下文被冗长输出塞满时，先把要点写进草稿文件，再用 /compact。反模式：上下文已经退化还继续追问，并且相信那些"典型模式"式的回答。

常见陷阱

• "`/clear` 然后重新读最关键的文件"：会丢掉已经积累的理解，还要重复读取。题干说"已有大量有效发现"时，应该选摘要 + 注入或者子 Agent 方案。
• "换更大上下文的模型"：只是推迟退化，没有解决信息组织的问题。
• "定时自动清空上下文"：会粗暴地丢失有价值的发现。
• "让子 Agent 探索，然后手动合并"：如果主 Agent 的上下文已经退化，单纯加一个子 Agent 不够，关键是先把已有发现摘要出来再注入。
• "每个 Agent 各自维护状态文件、各自恢复"：缺少协调者的 manifest，Agent 之间的状态会不一致，正确答案通常带有"协调者读取 manifest 并注入"。
• "共享向量库 + 语义检索恢复状态"：状态恢复需要精确、完整，语义检索做不到这一点。

实操练习

目标：在 Claude Code 里用"子 Agent + 草稿文件 + /compact"探索一个中等规模的仓库。

1. 在仓库里创建一个子 Agent 定义 .claude/agents/explorer.md，让它只读、只返回精简的结论。
2. 在 CLAUDE.md 里要求：每确认一个发现就追加到 notes/exploration.md。
3. 在交互会话中让主 Agent 委派两个问题，并观察主上下文的增长。
4. 执行 /compact，再提问，检查回答是否仍然引用具体路径。

---
name: explorer
description: 用于回答关于代码库的具体、有边界的调查问题（查找文件、追踪调用链）。返回精简结论。
tools: Read, Grep, Glob
---
你是代码库调查员。只回答被委派的具体问题。
输出格式：
- 结论（3-8 条，每条带 文件路径:行号）
- 未确认的疑点
不要粘贴大段源码。

## 探索约定（追加到 CLAUDE.md）
- 每确认一个关键发现（类、函数、路径、调用关系），立即追加到 notes/exploration.md 的"已确认"一节
- 回答架构问题前，先读取 notes/exploration.md

claude
# 会话内依次输入：
# > 用 explorer 子 Agent 找出所有测试文件，并按被测模块分组
# > 用 explorer 子 Agent 追踪 <某核心功能> 的依赖链
# > /context
# > /compact 保留已确认的类名、路径与调用关系
# > 这个功能出错时异常是在哪个文件被捕获的？

要检查的结果：/context 显示主会话的上下文占用增长有限，因为大量文件读取发生在子 Agent 的上下文里；notes/exploration.md 里有带行号的具体条目；/compact 之后的回答仍然能说出具体的文件路径和函数名，而不是"一般会在中间件里处理"这种泛泛之谈。

自测清单

• 长会话出现上下文退化时有哪些典型症状？
• 草稿文件应该记录什么？为什么它能跨越上下文边界保留信息？
• 子 Agent 委派是怎么保护主 Agent 上下文的？哪些问题适合委派？
• 切换探索阶段时，为什么"摘要 + 注入"比 /clear 后重来更好？
• 设计一个崩溃恢复方案：每个 Agent 导出什么、导出到哪里？协调者重启时做什么？
• /compact 和 /clear 有什么区别？使用 /compact 之前应该先做什么？