上下文管理

管理 Claude Code 的上下文窗口：哪些内容会加载、压缩后保留什么，以及如何让长会话保持可用。

为什么上下文管理重要

Claude Code 工作在有限的上下文窗口中。每条指令、文件读取、工具结果、MCP schema、skill body 和对话轮次都会占用空间。

好的上下文管理不只是省 token，而是确保 Claude 在需要时能看到正确的信息。

哪些内容会进入上下文

Claude Code 会从多个来源构建上下文：

所以即使你的 prompt 很短，运行时也可能已经携带了大量项目指令、工具能力和会话历史。

核心命令

/context

展示上下文窗口使用情况：

/context

当会话开始变慢、重复或遗忘时使用它。

/compact

压缩当前对话，同时尽量保留有用状态：

/compact
/compact focus on the auth refactor decisions and failing tests

Claude Code 在窗口接近容量时也会自动 compact。把自动 compact 当安全网，不要当计划。

/clear

为不相关任务清空对话历史：

/clear

/clear 后，CLAUDE.md、rules、memory 和 tool availability 等持久上下文仍会再次加载。旧对话不会继续作为工作上下文存在。

@ 引用

精准加载文件或目录：

Look at @src/auth/session.ts and @src/auth/refresh.ts.
Why does the refresh token expire early?

已知相关文件时用 @。不知道文件在哪里时用 subagent 探索。

压缩策略

Compact 很有用，但它有损。它应该保留决策、文件路径、当前任务、关键错误和下一步，而不是保留每一行日志或工具输出。

长会话 compact 前，主动告诉 Claude 什么重要：

/compact keep:
- current branch and files changed
- the three rejected approaches
- failing test names and error messages
- the plan we agreed to implement next

压缩后，如果任务风险高，让 Claude 先复述 checkpoint：

Before editing again, restate the current plan, changed files, and known risks.

保持主窗口干净

不同信息放在不同容器里：

主上下文窗口应该保留任务状态，而不是保留抵达任务状态过程中发现的所有中间产物。

实用模式

• 不相关任务之间清空。 Bug 排查上下文会影响功能开发判断。
• 先看 /context，再怀疑模型。 很多质量下降其实是上下文卫生问题。
• 直接引用文件。 @src/api/users.ts 比 “look through the API” 更好。
• 把广泛搜索交给 subagent。 Subagent 可以探索大模块，然后只返回有证据的小报告。
• 有意图地 compact。 长会话接近上限前告诉 Claude 要保留什么。
• 重复上下文移出聊天。 同一条指令说第二遍时，它可能应该进 CLAUDE.md、rules 或 skill。

反模式

• 巨大的 CLAUDE.md：每个会话都要付 token 成本。
• 粘贴完整日志：除非全量日志真的重要，否则只给相关片段或摘要。
• 提问前先加载十个文件：先从最可能的两三个开始。
• 任由工具输出堆积：用 subagents、--output-format 或更精准的命令。
• 把 compact 当完美记忆：压缩后要验证关键决策。

延伸阅读

• Claude Code 架构 — 上下文在 harness 中的位置
• CLAUDE.md 与记忆 — 持久上下文来源
• Subagents — 隔离高噪声探索
• Skills — 把可复用流程移出主窗口