# Claude Code 上下文窗口

> Claude Code 上下文窗口如何被系统提示、CLAUDE.md、规则、文件读取、工具输出、Hooks 和子代理占用,以及 /clear、/compact、/context 的使用边界。

URL: https://docs.passion8.cc/docs/claude-code/context
Language: zh-CN
Publisher: Passion8

Claude Code 每一轮都会把必要上下文重新发送给模型。上下文窗口不是“聊天记录”这么简单,它同时包含系统提示、项目规则、文件内容、工具输出、Hook 反馈、子代理结果和你的新消息。

## 上下文从哪里来

| 来源 | 何时进入上下文 | 建议 |
| --- | --- | --- |
| System prompt | 会话启动 | 由 Claude Code 管理,升级版本后可能变化 |
| 环境信息 | 会话启动 | 包括工作目录、平台、shell、Git 状态 |
| `~/.claude/CLAUDE.md` | 会话启动 | 放个人长期偏好,控制长度 |
| 项目 `CLAUDE.md` | 会话启动 | 放团队约定、架构、命令,建议短而准 |
| `.claude/rules` | 读到匹配文件时 | 用 `paths:` 让规则按需加载 |
| Skills 描述 | 会话启动或调用时 | 描述越短越好,正文按需加载 |
| MCP 工具 | 启动或按需搜索 | 支持 tool search 时只加载工具名和按需 schema |
| 文件读取 | Claude 调用 Read/Grep/LSP/Bash 后 | 文件越大越占窗口 |
| Hook 输出 | Hook 返回 additionalContext 时 | 只返回给 Claude 真正需要的信息 |
| 子代理结果 | 子代理结束后 | 主会话只看到最终摘要,中间读取留在子代理窗口 |




最常见的上下文浪费不是提示太长,而是一次任务里读了太多无关文件、长日志和大表格。




## `/context` 看什么

`/context` 会可视化当前窗口占用,并提示哪些部分最重。常用判断:

| 看到的问题 | 处理方式 |
| --- | --- |
| 文件读取占比高 | 缩小任务范围,让 Claude 先定位再读 |
| 工具输出占比高 | 让命令输出更短,必要时写到文件再按需读取 |
| 记忆或规则太大 | 拆成 path-scoped rules 或 skill |
| 会话历史太长 | 在自然断点 `/compact`,新任务用 `/clear` |
| MCP 工具太多 | 开 tool search,或拆 server / 禁用不用的工具 |

`/context all` 展开更多细节,适合排查为什么窗口很快满。

## `/clear`、`/compact`、`/rewind`

| 命令 | 做什么 | 缓存影响 | 适合场景 |
| --- | --- | --- | --- |
| `/clear [name]` | 清空当前对话,旧会话仍可恢复 | 新会话重新加载项目上下文 | 换一个完全不同任务 |
| `/compact [说明]` | 用摘要替换历史 | 摘要请求可读旧缓存,下一轮重建短历史缓存 | 同一任务继续做,但历史太长 |
| `/rewind` | 回退到早前检查点 | 通常回到已缓存前缀 | 走错方向,想撤回部分对话和改动 |
| `/context` | 只查看占用 | 不改变缓存 | 决定该不该整理上下文 |

不要把 `/compact` 当作万能省钱按钮。它会多发一次摘要请求,适合在自然断点做,不适合频繁点。需要撤回错误方向时,先看 [Checkpoint 与回退](https://docs.passion8.cc/docs/claude-code/checkpointing)。

## 什么会在 compact 后保留

| 内容 | 结果 |
| --- | --- |
| 系统提示和工具定义 | 保留 |
| 项目 `CLAUDE.md`、auto memory | 重新加载 |
| 已触发的 path rules | 由摘要和后续文件读取决定 |
| 已调用 skill 的重要结论 | 依赖摘要质量 |
| 未调用 skill 的完整正文 | 不会自动保留 |
| 子代理中间过程 | 不进入主会话,只有最终结果可能被摘要 |
| 文件系统实际改动 | 保留在磁盘,不靠上下文保存 |

如果某个信息之后一定要用,不要只指望模型记住。把它写进文件、issue、计划文档或明确告诉 `/compact` 摘要要保留。

## 控制上下文的实践





### 把长期规则写短


`CLAUDE.md` 放稳定约定,不要塞长 API 文档、日志、TODO 列表。长材料做成 skill 或项目文档,需要时再让 Claude 读取。




### 先定位再读取


让 Claude 先用 `rg`、文件树、符号搜索缩小范围,再读关键文件。大仓库尤其要避免“先通读整个 src”。




### 把探索交给子代理


研究型任务可以用 [子代理](https://docs.passion8.cc/docs/claude-code/subagents) 隔离大规模读取。主会话只接收结论,不会被每个文件内容撑爆。




### 长输出先落盘


测试、日志、分析报告很长时,先输出到文件,再让 Claude 摘要或按关键词读取。







## 跟缓存的关系

上下文窗口和 prompt caching 是两件事,但互相影响:

| 行为 | 上下文影响 | 缓存影响 |
| --- | --- | --- |
| 普通追问 | 历史变长 | 旧前缀通常命中 |
| 读取大文件 | 窗口明显增加 | 作为新内容追加,旧前缀命中 |
| `/compact` | 历史变短 | 后续 conversation 层换成摘要 |
| `/clear` | 当前历史清空 | 新会话重新建缓存 |
| 换模型或 effort | 上下文内容不一定变 | cache key 变,全量 miss |

更多 TTL 和命中判断见 [Prompt 缓存](https://docs.passion8.cc/docs/claude-code/prompt-caching),子代理上下文边界见 [子代理](https://docs.passion8.cc/docs/claude-code/subagents)。

大型仓库还要从启动目录、分层 `CLAUDE.md`、`Read` deny 和稀疏 Worktree 控制上下文入口,详见 [大型代码库与 Monorepo](https://docs.passion8.cc/docs/claude-code/large-codebases)。

## 官方参考

- [Explore the context window](https://code.claude.com/docs/en/context-window.md)
- [How Claude Code uses prompt caching](https://code.claude.com/docs/en/prompt-caching.md)
- [Manage sessions](https://code.claude.com/docs/en/sessions.md)