Claude Code 上下文窗口管理：CLAUDE.md 配置和 token 预算实战指南

Claude Code 的上下文窗口是最关键的资源，管理不好会导致遗忘指令和质量下降。本文讲解 CLAUDE.md 的正确写法、压缩时机选择和子代理隔离策略。

Claude Code 上下文窗口管理：CLAUDE.md 配置和 token 预算实战指南

Claude Code 的大多数最佳实践都来自同一个约束：上下文窗口会很快填满，填满后性能会下降。一个调试会话或代码库探索可能消耗数万个 token。窗口满了，Claude 开始"遗忘"早期的指令并犯更多错误。管理上下文窗口是使用 Claude Code 最重要的技能——比选择哪个模型更重要。

上下文窗口里有什么

打开 Claude Code 会话，在你输入任何内容之前，窗口里已经加载了：

  • CLAUDE.md 文件（项目根目录 + 子目录）
  • 自动记忆（Claude 自己写的偏好和修正记录）
  • MCP 工具名称列表
  • Skill 描述列表

随着你工作：每次文件读取都追加到上下文，路径规则随匹配文件自动加载，每个工具调用的输出都进入上下文。

你的 token 预算在被持续消耗。

CLAUDE.md：正确的写法

CLAUDE.md 是 Claude Code 每个会话开始时必然加载的文件，用来传递 Claude 无法从代码里推断的持久上下文。

目标长度：200 行以下。

超过 200 行会让 Claude 开始忽略你的实际指令——膨胀的 CLAUDE.md 文件降低的正是它本来要提升的遵从度。

检验每一行的问题： "删掉这行，Claude 会犯什么错误？"如果答案是"不会犯错"，删掉它。

一个健康的 CLAUDE.md 包含：

## 构建和测试命令
- 开发：`pnpm dev`
- 测试：`pnpm test`
- 类型检查：`pnpm typecheck`

## 代码规范
- TypeScript strict 模式，不用 any
- 用 Result<T, E> 代替 throw（错误处理约定）

## 架构约束
- 不要自动运行数据库迁移（生产环境手动执行）
- 不要编辑 src/generated/（由 pnpm codegen 重新生成）
- API 调用统一走 src/lib/api.ts，不要直接 fetch

不应该放进 CLAUDE.md 的内容：

  • 只在特定工作流里用到的领域知识（放进 Skill 文件，按需加载）
  • 特定目录的规则（用路径规则，只在 Claude 读取该目录时加载）
  • 教程或背景解释（Claude 用不到）

路径规则：让指令只在需要时加载

.claude/rules/ 目录下的文件可以设置 paths: 前缀，只有当 Claude 读取匹配的文件时才加载：

---
paths:
  - "src/api/**"
---
API 路由必须在 route handler 里做输入验证，不在 service 层做。
所有响应使用 src/lib/response.ts 的 ok() 和 err() 辅助函数。

这条规则只有在 Claude 读取 src/api/ 下的文件时才会进入上下文，不会在写前端组件时消耗 token。

会话中的上下文管理

监控使用量： /status 命令显示当前上下文使用百分比。

压缩时机： 两种策略各有适用场景：

策略 时机 适合场景
提前压缩 使用率到 50-60% 就 /compact 长会话，不需要保留早期完整记录
延迟压缩 让自动压缩在 80-85% 时触发 短会话，所有细节都重要

带焦点的压缩： 在开始新任务前，用指令控制压缩保留什么：

/compact 专注于认证 bug 修复，保留 JWT 处理的所有文件修改记录

默认的自动压缩会猜测保留什么，带焦点的压缩让你控制保留内容。

重要状态不要只存在对话里

对话历史是有损的——压缩会丢失细节，会话重启会清空一切。重要状态要落盘：

  • 用 Git commit 保存中间状态
  • 进度用文件（TODO 列表、进度日志）记录，不只在对话里提到
  • "我们在迁移到 v2 API，不要写 v1 调用"这类关键约定放进 CLAUDE.md，不只在对话里说——因为压缩可能把早期对话概括掉

子代理：隔离大文件读取

子代理（Explore、Plan 或自定义子代理）在独立的上下文窗口里运行，把结果摘要返回给父代理。父代理只看到摘要，不看到子代理读取的原始文件。

适合用子代理处理的：

  • 代码库全局搜索（用 Explore 子代理）
  • 读取大量文件的研究任务
  • 任何可以"给我找到什么，总结一下"的任务

不适合子代理的：

  • 需要父代理直接操作文件内容的任务
  • 步骤之间有紧密依赖的连续任务

常见错误

错误一：把所有文档都放进 CLAUDE.md 每次会话都加载全部内容，大部分时候用不到，但一直消耗 token 预算。

错误二：只在对话里说约束，不写进文件 "我们不用 v1 API"说过就说过，一旦压缩，可能被概括进历史变得模糊甚至丢失。

错误三：不用路径规则 把所有规则都塞进根 CLAUDE.md，无论工作在哪个目录都全部加载。

错误四：让单个长会话做太多事 几十轮对话 + 大量文件读取后，上下文质量明显下降。对于跨越多天的大任务，定期用 /clear 开新会话，靠文件和 Git 传递状态，而不是靠压缩后的对话历史。

常见问题

问：CLAUDE.md 里的内容算 token 吗？ 答：算。每次会话开始时 CLAUDE.md 的全部内容都进入上下文，消耗的 token 计入你的用量。这是为什么控制长度很重要。

问：子目录可以有自己的 CLAUDE.md 吗？ 答：可以。Claude Code 会加载根目录 CLAUDE.md，以及你当前工作的目录层级上的所有 CLAUDE.md 文件。如果有冲突的规则，Claude 可能随机选一个。定期检查多个 CLAUDE.md 之间有没有矛盾。

问：/compact 之后，之前的文件读取会保留吗？ 答：不会。压缩会把之前的对话（包括文件读取结果）总结成摘要，原始内容丢失。下一次 Claude 读取同一文件会重新加载。路径规则和嵌套 CLAUDE.md 文件也是同理——压缩后，只有再次读取匹配文件时才会重新加载。

问：自动记忆和 CLAUDE.md 有什么区别？ 答：CLAUDE.md 是你写的，由你控制内容。自动记忆是 Claude 根据你的纠正和偏好自己写的笔记，你可以用 # 命令查看和清除，但内容由 Claude 生成。两者都在每次会话开始时加载。

参考资料