Claude Code官方文档上下文Context Window

Claude Code 上下文窗口详解 - 自动加载 / 文件成本 / Hooks 触发时机

Claude Code 上下文窗口的工作原理——会话期间什么会自动加载、每次文件读取的成本、规则和 hooks 何时触发，以及压缩后什么内容保留。(原文为英文，已翻译)

发布于 2025年5月1日 · 阅读约 8 分钟

Claude Code 的上下文窗口包含 Claude 关于您会话的所有信息：您的指令、它读取的文件、它自己的响应，以及永远不会出现在您终端中的内容。本文介绍了什么内容会加载以及何时加载。

时间线展示了什么

会话遵循具有代表性 token 数量的真实流程：

在您输入任何内容之前：CLAUDE.md、自动内存、MCP 工具名称和 skill 描述都加载到上下文中。您自己的设置可能会在此处添加更多内容，例如输出样式或来自 --append-system-prompt 的文本，两者都以相同的方式进入系统提示。
当 Claude 工作时：每次文件读取都会添加到上下文中，路径范围规则会在匹配文件旁边自动加载，PostToolUse hook 会在每次编辑后触发。
后续提示：subagent 在其自己的单独上下文窗口中处理研究，因此大型文件读取保留在您的上下文之外。只有摘要和小的元数据尾部返回。
结束时：/compact 用结构化摘要替换对话。大多数启动内容会自动重新加载；下表显示了每种机制发生的情况。

以下是在您输入第一条提示之前发生的事情：

加载	大约 tokens	描述
系统提示	4,200	行为、工具使用和响应格式的核心说明。始终首先加载。您从未看到它。
自动内存（MEMORY.md）	680	Claude 给自己的笔记：它从以前的会话中学到的构建命令、注意到的模式、要避免的错误。最初的 200 行或 25KB（以先到者为准）会加载到对话上下文中。
环境信息	280	工作目录、平台、shell、操作系统版本，以及这是否是 git 仓库。
MCP 工具（延迟加载）	120	列出 MCP 工具名称，以便 Claude 知道有什么可用。默认情况下，完整架构保持延迟，Claude 通过工具搜索按需加载特定的架构。
Skill 描述	450	可用 skills 的一行描述，以便 Claude 知道可以调用什么。完整的 skill 内容仅在 Claude 实际使用时加载。
`~/.claude/CLAUDE.md`	320	您的全局首选项。适用于每个项目。
项目 CLAUDE.md	1,800	项目约定、构建命令、架构说明。您可以创建的最重要的文件。

当 Claude 处理您的请求时：

您的提示 进入上下文（典型大小：约 45 tokens）
Claude 读取的每个文件 都会添加到上下文（每个 1,000 - 5,000 tokens 不等）
路径范围规则 在 Claude 读取目录中的文件时自动加载（例如，.claude/rules/api-conventions.md 在读取 src/api/ 中的文件时加载）
Hook 输出 通过 additionalContext JSON 进入上下文
Claude 的分析和编辑 进入上下文

当您使用 subagent 时：

例如，subagent 可能读取 6,100 tokens 的文件并将其浓缩为 420 tokens 的结果。这就是上下文节省。

并非所有上下文都出现在您的终端中：

带有 disable-model-invocation: true 的 Skills 在启动时不出现在 skill 索引中，因此在您调用它们之前花费零上下文。一旦您键入 /skill-name，完整的 skill 内容才加载。

💡 在带有副作用的 skills 上设置 disable-model-invocation: true，例如提交、部署或发送消息。它们完全留在上下文之外，直到您需要它们。

带有 ! 前缀的命令（如 !git status）在您的 shell 中运行，输出附加到您的下一条消息。这对于将 Claude 基于命令输出而不让它运行命令很有用。

当长会话被压缩时，Claude Code 会总结对话历史以适应上下文窗口。您的指令发生的情况取决于它们的加载方式：

机制	压缩后
系统提示和输出样式	不变；不是消息历史的一部分
项目根目录 CLAUDE.md 和无范围规则	从磁盘重新注入
自动内存	从磁盘重新注入
带有 `paths:` frontmatter 的规则	丢失，直到再次读取匹配文件
子目录中嵌套的 CLAUDE.md	丢失，直到再次读取该子目录中的文件
调用的 skill 主体	重新注入，每个 skill 上限为 5,000 tokens，总共 25,000 tokens；最旧的先丢弃
Hooks	不适用；hooks 作为代码运行，而不是上下文

路径范围规则和嵌套 CLAUDE.md 文件在读取触发文件时加载到消息历史中，因此压缩会将它们与所有其他内容一起总结。它们会在 Claude 下次读取匹配文件时重新加载。如果规则必须在压缩期间持续存在，请删除 paths: frontmatter 或将其移动到项目根目录的 CLAUDE.md。

Skill 主体在压缩后重新注入，但大型 skills 被截断以适应每个 skill 的上限，最旧的调用 skills 会在超出总预算后被丢弃。截断保留文件的开头，因此将最重要的说明放在 SKILL.md 的顶部附近。

可视化使用代表性数字。要查看您实际的上下文使用情况，请运行 /context 进行实时按类别分解，并提供优化建议。运行 /memory 检查在启动时加载了哪些 CLAUDE.md 和自动内存文件。

在您输入之前会加载很多内容。CLAUDE.md、内存、skills 和 MCP 工具在您的第一个提示之前都在上下文中。
每个文件读取都会增加上下文。在您的提示中具体（“修复 auth.ts 中的 bug”），以便 Claude 读取较少的文件。
Hooks 自动在工具事件上触发。输出通过 additionalContext JSON 到达 Claude。退出代码 2 将 stderr 显示给 Claude。退出 0 上的纯 stdout 转到调试日志，而不是成绩单。
Subagent 在其自己的单独上下文窗口中工作。它的所有文件读取都不会触及您的。只有最终摘要返回。
Bang 命令在您的 shell 中运行 并将输出添加到下一条消息。
用户专用的 skills 完全留在上下文之外，直到您调用它们。启动时的 skill 索引仅列出 Claude 可以自行调用的 skills。
/compact 总结对话 以释放空间，同时保留关键信息。