Claude Code 深度学习手册

主题

上下文管理（窗口/压缩） ​

Claude Code 的上下文窗口装着整个 session 的指令、文件与回复；本页用交互模拟讲清什么会自动加载、各占多少 token，以及 /compact 压缩后哪些内容保留或重载。

你的上下文构成 ​

每次会话一开就被这些填掉一部分（你的真实情况）：

  • system prompt（看不见，最先加载）
  • ~/.claude/CLAUDE.md（全局）+ 项目根 ./CLAUDE.md
  • 你 5 个 MCP server 的工具——默认 deferred（只占工具名，几乎不占），要用时才 ToolSearch 调入
  • ~50 个技能的一行描述（不是正文）
  • auto memory 的 MEMORY.md（你那 3 条，前 200 行/25KB）
  • 你子目录的 AGENTS.md（端口/鉴权表）默认不在这里——CC 不读 AGENTS.md（见 Memory 节）

之后你每读一个文件就加一截——file reads 是上下文占用的大头。

去真实体验 ​

想验证什么这样做
看上下文实时占用 + 优化建议输入 /context（按类别 breakdown）
看启动加载了哪些 CLAUDE.md / 记忆/memory
腾空间（开始新长任务前）/compact（压成摘要）；想精确控制保留点用 /rewind 的 summarize

对你的实际意义（省上下文三招，都贴你的习惯） ​

  1. 用 Explore/serena 而不是读整文件——大量读取留在子窗口，主对话只拿摘要（正是你 AGENTS.md 的约定）。
  2. prompt 要具体：「修 kj-frontend/src/.../login.ts 的 bug」比「修登录 bug」少让 Claude乱读文件。
  3. 稳定内容靠前、别频繁改——既利缓存命中，也避免 /compact 后丢失（项目根 CLAUDE.md 会重注入，但子目录的、path-scoped 规则压缩后要重新读到文件才回来）。

/compact 会丢逐字对话（完整工具输出、中间推理），保留摘要（意图、关键文件、错误与修复、待办）。重要的别只存在对话里——存进 CLAUDE.md 或 auto memory。

官方文档要点 ​

以下为按官方文档整理的系统性参考。

是什么 ​

本页是 Claude Code 官方关于「context window（上下文窗口）」的讲解页，核心是一个交互式 simulation，演示一次 session 中上下文如何被逐步填满：什么在启动时自动加载、每次读文件花多少 token、rules 与 hooks 何时触发、subagent 如何用独立窗口省上下文，以及 /compact 压缩后哪些内容会保留或重载。页面用约 200K（MAX = 200000）的窗口和一组 illustrative token 数演示，并给出查看真实占用的命令（/context、/memory）和减少上下文的实用建议。

怎么工作 ​

  • 上下文窗口（context window）容纳本次 session 的全部内容：你的指令、Claude 读的文件、它自己的回复，以及一些在终端里看不到的内容。本页示例用 MAX = 200000（约 200K tokens）作为窗口上限（标注为 illustrative，实际随 CLAUDE.md、MCP、文件长度而变）。
  • 启动阶段（你还没输入前）就已加载大量内容：System prompt（约 4200 tokens，永远第一个加载、你看不到）、Auto memory MEMORY.md（约 680 tokens，加载前 200 行或 25KB 取先到者）、Environment info（约 280 tokens；git branch/status/recent commits 作为单独 block 放在系统提示最末）、MCP 工具名（deferred，约 120 tokens）、Skill descriptions（约 450 tokens，仅一行描述）、~/.claude/CLAUDE.md（全局，约 320 tokens）、Project CLAUDE.md（约 1800 tokens）。
  • 工作阶段：每次读文件都增加上下文（示例 auth.ts 约 2400 tokens 等），file reads 是上下文占用的大头；path-scoped rules 在读到匹配文件时自动随之加载（如 api-conventions.md 约 380、testing.md 约 290）。
  • Hook 注入机制：PostToolUse hook（如 prettier）通过返回 JSON 的 hookSpecificOutput.additionalContext 字段把信息送入 Claude 上下文；普通 stdout 在 exit 0 时不进上下文，只写到 debug log；PostToolUse 的 exit code 2 会把 stderr 作为错误浮现给 Claude，但工具已执行完故无法阻止。additionalContext 进入上下文时不截断，需保持简洁。
  • subagent 机制：subagent 在自己独立的上下文窗口工作，会加载 CLAUDE.md、同样的 MCP 与 skill，但不带主 session 的对话历史与 auto memory；它读的大量文件（示例共 6100 tokens）不占主上下文，只有最终文本回复（示例 420 tokens）+ 少量 metadata trailer（token 数、duration）返回主上下文。
  • compaction（压缩）机制：把对话历史总结成一个 structured summary 以腾出空间。摘要保留：你的请求与意图、关键技术概念、查看/修改过的文件及重要代码片段、错误及修复方式、待办、当前工作；丢弃逐字对话——完整 tool outputs 和中间推理消失，Claude 仍能引用但拿不到之前读过的确切代码。
  • 压缩后的重载规则按加载方式不同而不同（见下表式 keyFacts）：system prompt 与 output style 不变（本就不在 message history）；project-root CLAUDE.md、unscoped rules、auto memory 从磁盘重新注入；path-scoped rules 和 nested CLAUDE.md 丢失，直到再次读到匹配文件；invoked skill bodies 重新注入但有 cap；hooks 不受影响（作为代码运行，不占上下文）。
  • Skill 列表是启动内容里唯一不会在 /compact 后重新注入的部分（noSurviveCompact）：只有你实际调用过的 skill 才被保留。

怎么配置 / 用法 ​

查看与管理上下文的命令/配置（均来自本页）：

  • 查看实时占用：/context —— 按类别给出 live breakdown，并附 optimization suggestions。
  • 查看启动加载了哪些 CLAUDE.md 与 auto memory：/memory。
  • 手动压缩：/compact —— 把对话替换成 structured summary，终端只显示 "Conversation compacted" 提示，摘要过程不在终端展示。
  • 控制 MCP 工具 schema 加载量（env）：ENABLE_TOOL_SEARCH=auto（仅当 schema 能放进上下文窗口的 10% 时才在启动时全部加载）；ENABLE_TOOL_SEARCH=false（启动时全部加载所有 schema）。默认行为：只列 MCP 工具名（deferred），按需 tool search 加载具体 schema。
  • 让 skill 不被模型自动调用、彻底不进上下文：在 skill frontmatter 设 disable-model-invocation: true，只能用 /name 手动触发；对有副作用的 skill（commit/deploy/发消息）官方建议这样设。
  • 路径作用域规则：在 .claude/rules/ 下的规则文件用 paths: frontmatter（如匹配 src/api/**、*.test.ts）；读到匹配文件时自动加载。
  • 让规则跨 compaction 存活：去掉 paths: frontmatter，或把内容移到 project-root CLAUDE.md。
  • CLAUDE.md 建议：保持在 200 行以内，把参考内容移到 skills 或 path-scoped rules。
  • SKILL.md：把最重要的指令放文件顶部（compaction 截断时保留文件开头）。
  • 自定义 agent 持久记忆：在其 frontmatter 写 memory:，会加载它自己单独的 MEMORY.md。
  • 启动注入系统提示的额外途径：output style、--append-system-prompt（CLI flag）。
  • bash mode：用 ! 前缀（如 !git status）在 shell 跑命令，命令与输出都进入你的消息上下文。

什么时候用 ​

  • 当 /context 显示上下文占用已开始影响性能、或要开始一个全新的长任务前，运行 /compact 腾空间。
  • 想知道当前真实占用与各类别明细时用 /context（带优化建议）；想确认启动加载了哪些 CLAUDE.md/auto memory 时用 /memory。
  • research-heavy 或要读大量文件的子任务，交给 subagent 处理，让大文件读取留在它的独立窗口、不占主上下文。
  • 对有副作用的 skill（commit/deploy/发消息）设 disable-model-invocation: true，让它平时零上下文、只在 /name 调用时加载。
  • 希望某规则在 /compact 后仍存活时，别用 paths: frontmatter，改放 project-root CLAUDE.md。
  • 别把大量参考内容堆进 CLAUDE.md（保持 <200 行），改放 skills 或 path-scoped rules 按需加载；prompt 要具体以减少 Claude 读文件数。

限制 / 坑 ​

  • file reads 是上下文占用的主导项——读太多文件会迅速吃满窗口；官方建议 prompt 要具体（如『fix the bug in auth.ts』）以减少读文件数。
  • 示例中的所有 token 数都是 illustrative（代表性数值），真实占用随你的 CLAUDE.md 大小、MCP servers、文件长度变化，不可当精确值。
  • path-scoped rules（带 paths:）和 nested CLAUDE.md 在 compaction 后会丢失，直到再次读到匹配文件才重载；要持久必须去掉 paths: 或并入 project-root CLAUDE.md。
  • invoked skill bodies 重载有硬上限：每个 skill 5,000 tokens、总计 25,000 tokens，超出按最旧先丢；大 skill 会被截断（只保留开头）。
  • skill descriptions 列表在 /compact 后不重载，只有实际调用过的 skill 才保留——依赖某 skill 描述被模型自动发现的工作流，在压缩后可能失效。
  • PostToolUse hook 的 exit code 2 只能把 stderr 作为错误浮现，不能阻止工具（工具已执行完）；hook 的 additionalContext 进上下文不截断，写太长会直接占满。
  • 压缩会丢掉逐字对话：完整 tool outputs 和中间推理消失，Claude 拿不到之前读过的确切代码，只能靠摘要引用。
  • CLAUDE.md 过大直接吃启动上下文，官方提示保持 under 200 lines。

硬事实速查（22 条） ​

  • 示例窗口上限 MAX = 200000 tokens（约 200K），标注为 illustrative（真实值随 CLAUDE.md 大小、MCP servers、文件长度变化）。
  • 占用进度条配色阈值：pct > 75% 显示 #D97757（橙/警示），> 50% 显示 #B8860B，否则 #558A42（绿）。
  • System prompt 约 4200 tokens，永远第一个加载，用户看不到（invisible in terminal）。
  • Auto memory = MEMORY.md，加载『前 200 行或 25KB，取先到者（whichever comes first）』，示例约 680 tokens。
  • Environment info 约 280 tokens：working directory、platform、shell、OS version、是否 git repo；git branch/status/recent commits 作为单独 block 放系统提示最末。
  • MCP 工具默认 deferred（只列名，示例约 120 tokens）；ENABLE_TOOL_SEARCH=auto 仅当 schema 能装进上下文窗口 10% 时启动加载；ENABLE_TOOL_SEARCH=false 启动加载全部 schema。
  • Skill descriptions 约 450 tokens，只是一行描述；设 disable-model-invocation: true 的 skill 不在该列表，彻底不进上下文直到用 /name 调用。
  • Skill 列表是唯一不在 /compact 后 re-inject 的启动内容；只有实际 invoke 过的 skill 被保留。
  • ~/.claude/CLAUDE.md（全局偏好）约 320 tokens；Project CLAUDE.md 约 1800 tokens，建议保持 under 200 lines。
  • 用户 prompt 很小（示例 45 tokens），相比已加载的项目知识微不足道。
  • path-scoped rules 放 .claude/rules/，用 paths: frontmatter 匹配（示例 src/api/** → api-conventions.md ~380 tokens；*.test.ts → testing.md ~290 tokens），读到匹配文件时自动加载。
  • PostToolUse hook 通过 JSON 的 hookSpecificOutput.additionalContext 进入上下文；普通 stdout（exit 0）只进 debug log；PostToolUse exit code 2 把 stderr 作为 error 浮现但无法阻止（工具已运行）；additionalContext 进上下文不截断。
  • subagent 用独立上下文窗口：示例其系统提示约 900 tokens、自带 CLAUDE.md 1800、MCP+skills 970、task prompt 120；built-in Explore 和 Plan agent 跳过 CLAUDE.md 以减小上下文。
  • subagent 默认拿不到 Agent 工具本身（防递归），也没有 plan-mode controls 和 background-task tools；不带主 session 的 auto memory。
  • subagent 示例读了 6100 tokens 文件，只返回 420 tokens 结果 + 小 metadata trailer（token 数、duration）。
  • compaction 摘要保留：请求与意图、关键技术概念、查看/修改文件及重要代码片段、错误与修复、pending tasks、current work；丢弃逐字 tool outputs 与中间推理。
  • 压缩后重载表：System prompt 与 output style 不变（不在 message history）；project-root CLAUDE.md 与 unscoped rules 从磁盘 re-inject；auto memory re-inject；带 paths: 的 rules 丢失直到再次读匹配文件；nested CLAUDE.md 丢失直到再读该子目录文件；invoked skill bodies re-inject 但 capped at 5,000 tokens per skill 且 25,000 tokens total，超出按 oldest dropped first；hooks 不适用（作为代码运行）。
  • skill body 截断保留文件开头（start of the file），故 SKILL.md 重要指令放顶部。
  • /context：实时按类别 breakdown + optimization suggestions；/memory：查看启动加载了哪些 CLAUDE.md 与 auto memory。
  • /compact：把对话替换成 structured summary，终端只显示 'Conversation compacted'，摘要过程不在终端显示。
  • bash mode 用 ! 前缀（如 !git status），命令与输出都进入你的消息上下文。
  • output style 与 CLI flag --append-system-prompt 都按同样方式进入 system prompt。

官方出处：https://code.claude.com/docs/en/context-window