Claude Code Context 演进问答

版本：2026-07-04

定位：这是一篇基于 claude-code-context-management-guide.md 改写的问答式学习文档。它用“遇到问题 -> 做出设计 -> 又遇到新问题 -> 继续迭代”的方式，讲清楚 Claude Code 为什么需要 CLAUDE.md、Auto Memory、Skill、Subagent、Slash Commands、/compact、交接文档和大型仓库上下文策略。

说明：本文是上下文管理的学习型推演，不是 Claude Code 官方真实历史时间线。它更像一次工程复盘：把现在的 Context 管理方法倒推成一串自然出现的问题和回答。

0. 先给一个结论

问：Claude Code 的 Context 到底是什么？

答：Context 是 Claude Code 当前能看到、能使用的工作记忆。它不只是聊天记录，还包括项目说明、用户要求、读过的文件、工具输出、测试日志、Git diff、Skill 描述、Subagent 总结、Auto Memory，以及 /compact 后的摘要。

一句话：

Claude Code 的能力上限不只取决于模型多聪明，也取决于当前上下文里有没有正确、足够、不过量的信息。

问：为什么 Context 管理这么重要？

答：因为 Claude Code 是代码 Agent，不是简单问答机器人。它要在真实仓库里读文件、改代码、跑命令、处理测试失败、总结变更。上下文如果乱，Agent 就会：

• 忘记目标。
• 漏掉项目约定。
• 被旧日志带偏。
• 重复读无关文件。
• 压缩后丢失关键决策。
• 在大型仓库里把自己读迷路。

上下文管理的目标不是“塞更多”，而是“让关键事实一直在场，让噪音及时退场”。

1. 最开始的问题：我只是想让 Claude Code 看懂项目

问：最简单的使用方式是什么？

答：打开仓库，直接说：

1帮我看看这个项目，然后修一下这个 bug。

Claude Code 会读取文件、搜索代码、运行命令，然后尝试完成任务。

问：这有什么问题？

答：小项目里没问题。大型仓库里，很快会遇到麻烦：

• 项目结构复杂，不知道从哪里读。
• 测试命令不统一。
• 某些目录不能随便改。
• 编码规范散落在旧 PR、README 和人脑里。
• 任务相关文件只占仓库很小一部分。
• 读太多文件后，上下文被无关信息挤满。

这时 Claude Code 不是不努力，而是缺少一张“项目地图”。

问：第一个设计回应是什么？

答：给项目写 CLAUDE.md。

它告诉 Claude Code：

• 项目是什么。
• 技术栈是什么。
• 常用命令是什么。
• 目录结构怎么理解。
• 修改代码要遵守什么规则。
• 哪些文件或操作要谨慎。

问：新发现是什么？

答：代码 Agent 不是只需要代码，还需要项目约定。没有约定时，它会从代码里猜；猜多了，就容易很有礼貌地猜错。

2. 第一次迭代：用 CLAUDE.md 保存稳定规则

问：`CLAUDE.md` 应该解决什么问题？

答：解决“每次进项目都应该知道”的稳定信息。

适合写进去：

• 项目目标。
• 技术栈。
• 常用开发、测试、构建命令。
• 目录地图。
• 编码规范。
• 提交规范。
• 常见坑。
• 安全边界。
• 不要修改的文件或目录。

问：为什么不直接把所有文档都放进去？

答：因为 CLAUDE.md 每次会话都会加载。它越大，越容易挤占当前任务真正需要的空间。

巨型 CLAUDE.md 的问题：

• 每次任务都带着无关模块细节。
• 临时 TODO 和长期规则混在一起。
• 过期内容难发现。
• 复杂流程污染简单任务。
• 模型更难抓住真正重要的约束。

问：所以 `CLAUDE.md` 的原则是什么？

答：短、稳、可执行。

1短：只放高频信息。2稳：只放长期有效规则。3可执行：写清命令、边界、禁止事项。

问：新发现是什么？

答：CLAUDE.md 是项目记忆，不是项目百科。百科应该按需打开，记忆应该每次都轻装上阵。

3. 第二个问题：一个根说明撑不起大型仓库

问：大型仓库只有一个根 `CLAUDE.md` 够吗？

答：通常不够。

大型仓库可能有：

• 前端应用。
• 后端服务。
• 共享包。
• 基础设施。
• 移动端。
• 数据脚本。
• 多套测试命令。

如果所有规则都写进根 CLAUDE.md，它会越来越像一本仓库电话簿。

问：怎么解决？

答：使用分层上下文。根目录放全局规则，模块目录放局部规则。

1repo/2  CLAUDE.md3  apps/4    web/5      CLAUDE.md6  services/7    api/8      CLAUDE.md9  packages/10    shared/11      CLAUDE.md

问：每一层应该写什么？

答：

问：新发现是什么？

答：上下文要就近。全局规则放全局，局部规则放局部。不要让后端服务每次都背着前端组件库的视觉规范。

4. 第三个问题：Context 不是一次加载完的

问：Claude Code 的上下文什么时候变化？

答：它会随任务流动。

会话启动时可能进入上下文：

• 系统和开发者指令。
• 项目级 CLAUDE.md。
• 用户级或组织级记忆。
• Auto Memory。
• 工具名称和描述。
• Skill 名称和简介。

任务执行时又会加入：

• 用户补充需求。
• 读过的文件。
• 命令输出。
• 测试日志。
• Git diff。
• 工具结果。
• 计划、假设、状态。

问：这带来什么问题？

答：上下文会越跑越大，也会越来越杂。开始时很清楚，跑着跑着就出现：

• 老日志还在。
• 已解决错误还在。
• 临时假设还在。
• 读过但无关的文件片段还在。
• 新目标和旧目标混在一起。

问：怎么改进？

答：把 Context 当成预算管理，而不是无限容器。

每次加入上下文前都问：

• 这对当前任务有用吗？
• 是短期状态还是长期规则？
• 是原文必要，还是摘要足够？
• 会不会干扰后续判断？
• 是否应该放进 Skill、Subagent 或交接文档？

问：新发现是什么？

答：Context Window 不是仓库，也不是垃圾箱。它更像当前任务工作台。工作台上可以有工具和材料，但不要把仓库库存都堆上来。

5. 第四个问题：文件读取不能靠“全都看一遍”

问：为了稳妥，Claude Code 能不能先读完整个仓库？

答：理论上听起来稳，实践中很快变慢、变贵、变乱。

大型仓库里，当前任务需要的通常只是很小一部分。全仓库读取会导致：

• 上下文成本暴涨。
• 关键文件被无关文件淹没。
• 模型更难判断主线。
• 任务速度下降。
• 后续 /compact 更难保住重点。

问：更好的方式是什么？

答：渐进式披露。

推荐顺序：

1. 先看目录结构。
2. 搜索关键词。
3. 读入口文件。
4. 读调用链关键文件。
5. 读测试。
6. 必要时再读边缘实现。

问：这和人类工程师有什么关系？

答：很像。人类熟悉仓库也不是从第一行读到最后一行，而是先找入口、调用链、测试和错误现场。

Claude Code 也一样。上下文管理好，Agent 就像有经验的工程师在定位；上下文管理差，就像在仓库里认真翻每一个纸箱。

6. 第五个问题：命令输出和日志太吵

问：测试失败日志要不要完整放进上下文？

答：不一定。很多日志只有少量信息有价值。

应该保留：

• 失败命令。
• 第一个根因错误。
• 涉及文件和行号。
• 复现方式。
• 已尝试方案。
• 下一步判断。

通常不值得保留：

• 重复 stack trace。
• 无关 warning。
• 巨长依赖安装日志。
• 已解决的临时错误。
• 和当前任务无关的历史输出。

问：为什么日志噪音危险？

答：因为模型会认真阅读它看到的东西。噪音越多，注意力越容易被拉走。

尤其是长任务里，旧错误留在上下文中，可能导致 Claude Code 继续围着已经解决的问题打转。

问：怎么改进？

答：把原始输出转成结构化结论。

1Command:2- `pytest tests/test_login.py`3 4Result:5- Failed6 7Root Cause:8- `validate_token()` returns `None` when token is expired.9 10Files:11- `app/auth.py`12- `tests/test_login.py`13 14Next:15- Add expired-token branch and update test expectation.

问：新发现是什么？

答：工具输出不是越完整越好，而是越可行动越好。Context 需要的是线索，不是瀑布。

7. 第六个问题：长任务会挤爆上下文

问：任务很长时会发生什么？

答：上下文不断增长，直到接近窗口上限。表现可能是：

• 旧决策被遗忘。
• 新文件读不进去。
• 重要约束被压缩丢失。
• 模型开始混淆当前状态。
• 成本和延迟上升。

问：Claude Code 怎么处理？

答：使用 /compact。它把长会话压缩成摘要，释放上下文空间。

问：`/compact` 应该保留什么？

答：

• 当前目标。
• 已完成事项。
• 未完成事项。
• 关键文件和路径。
• 已做出的技术决策。
• 重要约束。
• 已知问题。
• 下一步动作。
• 已运行验证和结果。

问：`/compact` 不应该保留什么？

答：

• 重复日志。
• 长命令输出。
• 已解决的临时错误。
• 中间推理废稿。
• 不再相关的文件片段。

问：为什么不能直接压缩？

答：因为压缩不是魔法备份。压缩前如果上下文里没有清晰状态，压缩后也很难凭空生成清晰状态。

所以长任务中最好先准备一份结构化摘要，再 /compact。

问：新发现是什么？

答：压缩不是清理现场，而是写交接班记录。交接班写得好，下一班接着干；写得糊，下一班先考古。

8. 第七个问题：跨会话恢复需要交接文档

问：有 `/compact` 了，为什么还要 `context-handoff.md`？

答：因为有些任务会跨会话、跨天、甚至跨人协作。不能只依赖当前聊天窗口。

交接文档适合保存：

• 当前目标。
• 已完成内容。
• 正在处理什么。
• 关键决策。
• 重要文件。
• 已知问题。
• 下一步。
• 验证结果。

问：交接文档和 `CLAUDE.md` 有什么区别？

答：

不要把任务交接写进 CLAUDE.md。否则一个临时 bug 修复状态，可能在三个月后还在提醒 Claude Code “下一步修这个文件”。这就像把便利贴贴进公司章程。

问：好的交接文档应该长什么样？

答：它应该让接手者用一分钟知道：

• 为什么做。
• 已经做了什么。
• 还差什么。
• 哪些文件重要。
• 怎么验证。

问：新发现是什么？

答：Context 管理不只服务模型，也服务协作。能交接的任务，才是真的可恢复。

9. 第八个问题：长期记忆不能靠临时聊天

问：Claude Code 的 Auto Memory 解决什么？

答：Auto Memory 用来记录 Claude 在仓库中逐步学到的事实和模式，例如项目偏好、历史修正、常见约定。

问：它和 `CLAUDE.md` 有什么区别？

答：

问：Auto Memory 会带来什么问题？

答：

• 记忆可能过期。
• 记忆可能误解。
• 临时状态可能被长期保存。
• 安全策略可能被误当成提示。
• 仓库规则可能重复或冲突。

问：怎么管理？

答：

• 定期用 /memory 检查。
• 把反复确认正确的内容沉淀进 CLAUDE.md。
• 把流程型内容迁移到 Skill。
• 把临时任务状态放到交接文档。
• 删除过期或误导记忆。

问：新发现是什么？

答：记忆是帮手，不是法律。长期规则要人维护，安全约束要系统执行。

10. 第九个问题：长流程不该塞进每次上下文

问：发布流程、安全审查清单、PDF 生成流程这些放哪里？

答：不要都放进 CLAUDE.md。适合做成 Skill。

Skill 解决的问题是：

有些说明很长，但不是每次任务都需要。

问：什么时候应该写 Skill？

答：

• 你反复粘贴同一段操作流程。
• 某个任务需要长检查清单。
• 需要携带示例文件、模板、参考资料。
• 任务跨多个项目复用。
• 需要把复杂流程封装成可重复能力。

问：Skill 和 `CLAUDE.md` 怎么分工？

答：

问：新发现是什么？

答：好上下文不是把所有知识都常驻，而是把知识做成按需加载。少数核心规则常驻，长流程按需上场。

11. 第十个问题：高噪音任务要隔离

问：为什么需要 Subagent？

答：为了保护主上下文。

有些任务会产生大量噪音：

• 大型仓库搜索。
• 长日志分析。
• 开源方案调研。
• 安全审查。
• 代码审查。
• 测试覆盖分析。

如果这些原始过程都进入主会话，主上下文会很快变脏。

问：Subagent 应该做什么？

答：在独立上下文中完成高噪音任务，然后只把高信号摘要返回主会话。

一个好的 Subagent 摘要应该包含：

• 相关文件。
• 关键函数。
• 调用链。
• 风险点。
• 证据路径。
• 建议下一步。

问：Subagent 不适合做什么？

答：

• 主线必须连续决策的核心实现。
• 需要用户实时确认的产品取舍。
• 涉及危险写操作且没有明确边界的任务。
• 很小的文件读取或简单命令。

问：新发现是什么？

答：Subagent 不是为了显得阵容豪华，而是为了让主线程保持清醒。调研可以很热闹，主线最好安静。

12. 第十一个问题：命令是上下文控制台

问：Slash Commands 在 Context 管理里是什么角色？

答：它们像上下文控制台。不同命令处理不同状态：

问：推荐节奏是什么？

答：

1. 新仓库先 /init。
2. 任务开始前确认 CLAUDE.md 是否够用。
3. 长任务中途用 /context 看状态。
4. 信息过多时先整理摘要，再 /compact。
5. 任务结束前用 /diff、测试输出和总结收口。

问：新发现是什么？

答：命令不是装饰，它们是上下文生命周期的操作手柄。会用命令，Claude Code 就不只是“会聊天的终端”，而是可控的协作环境。

13. 第十二个问题：并发、稳定性和性能怎么处理？

问：Claude Code 上下文管理会遇到哪些并发问题？

答：

• 多个任务在同一个会话里交错。
• 用户中途改目标。
• 长任务跨 /resume 继续。
• Subagent 同时返回多个摘要。
• 运行命令和修改文件之间状态变化。
• 分支切换后上下文仍保留旧假设。

问：怎么降低混乱？

答：

问：稳定性问题主要有哪些？

答：

• CLAUDE.md 过期。
• Auto Memory 误导。
• 压缩丢失关键决策。
• 日志噪音污染判断。
• Subagent 摘要缺证据。
• 读文件太散，漏掉关键调用链。
• 任务结束没有验证记录。

问：怎么改进？

答：

• CLAUDE.md 保持短而稳定。
• 定期审查 Auto Memory。
• /compact 前写结构化摘要。
• 长日志只保留根因。
• Subagent 输出路径和证据。
• 渐进式读取文件。
• 最终总结包含修改、验证、风险。

问：性能问题在哪里？

答：

• 上下文太长导致延迟和成本上升。
• 读太多文件。
• 反复运行大命令。
• Subagent 返回过多原文。
• Skill 设计过重。
• 根 CLAUDE.md 太大。

问：优化方向是什么？

答：

问：新发现是什么？

答：Claude Code 的性能优化很多时候不是“让模型更快”，而是让上下文更瘦、更准、更有序。

上下文像行李箱。装得越满，不代表旅行越顺利。

14. 第十三个问题：安全边界不能只靠记忆

问：能不能把安全规则写进 `CLAUDE.md` 或 Auto Memory 就完事？

答：不能。

CLAUDE.md 和 Auto Memory 都是上下文，不是硬约束。它们可以提醒 Claude Code，但不能替代：

• 权限配置。
• Hook。
• CI。
• 测试。
• 代码审查。
• 沙箱。
• 密钥管理。

问：哪些内容适合写进上下文？

答：

• 不要提交密钥。
• 不要修改生产迁移文件，除非任务明确要求。
• 数据删除逻辑必须有测试。
• 高风险改动先说明方案。

问：哪些必须靠系统机制？

答：

• 阻止密钥提交。
• 限制危险命令。
• 强制测试通过。
• 权限审批。
• 生产环境变更门禁。

问：新发现是什么？

答：Context 可以让 Agent 知道规则，但不能保证规则不可破。真正的安全边界要落在工具、权限、测试和审查上。

“请小心”很好，但门锁也要装。

15. 第十四个问题：最终体系为什么是这样？

问：能把 Claude Code Context 的演进压缩成一张表吗？

答：可以。

问：Claude Code Context 管理的核心思想是什么？

答：

1稳定规则 -> CLAUDE.md2长期学习 -> Auto Memory3长流程 -> Skill4高噪音调研 -> Subagent5长任务状态 -> context-handoff.md6会话过长 -> /compact7当前执行证据 -> diff、测试摘要、工具结果摘要8硬性约束 -> 权限、Hook、CI、审查

每个组件都不是为了多一个名词，而是为了让主上下文保持清晰、准确、可恢复。

16. 复述模板

问：如果要快速介绍 Claude Code Context 管理，怎么说？

答：可以这样说：

1Claude Code 的 Context 是当前模型可见的工作记忆，包括用户请求、项目说明、读过的文件、工具输出、测试日志、Git diff、记忆、Skill 描述、Subagent 摘要和压缩摘要。Context 管理的核心不是尽可能多塞信息，而是把稳定规则放进 CLAUDE.md，把长期学习交给 Auto Memory，把长流程做成 Skill，把高噪音搜索和日志分析交给 Subagent，把长任务状态写进 context-handoff.md，并在会话过长时用 /compact 保留目标、决策、文件、风险和下一步。大型仓库要用分层 CLAUDE.md、渐进式文件读取和日志摘要控制上下文成本；安全边界不能只靠记忆或提示，而要依赖权限、Hook、CI、测试和审查。

17. 学习路线：按问题而不是按命令学

问：学习 Claude Code Context 管理应该从哪里开始？

答：按这个顺序：

1. 在小项目中创建短 CLAUDE.md。
2. 对比有无 CLAUDE.md 的任务表现。
3. 把一个过长 CLAUDE.md 拆成根说明、模块说明和 Skill 草稿。
4. 用渐进式读取完成一次代码定位任务。
5. 把长测试日志改写成根因摘要。
6. 模拟长任务，写 context-handoff.md。
7. 在 /compact 前准备结构化摘要。
8. 设计一个只读 repo-explorer Subagent。
9. 把重复流程写成 Skill。
10. 用 Context 质量评估表复盘一次真实会话。

问：每学一个组件都该问什么？

答：

• 它解决了什么上下文问题？
• 如果没有它，会怎样污染或丢失上下文？
• 它适合放长期规则、临时状态，还是按需流程？
• 它是否会引入新噪音？
• 它能不能让任务更容易恢复？

问：最后最重要的提醒是什么？

答：Claude Code Context 管理不是记笔记比赛，而是持续维护“当前任务的清醒程度”。

读得少可能漏，读得多可能乱。真正的功夫是：该看的看，该记的记，该压缩的压缩，该隔离的隔离，该忘的也要舍得忘。