Claude Code 到底怎么工作：官方文档画出的那条主循环
你敲进去一句「把失败的测试修好」，屏幕上滚过去几十行东西，最后它说改完了。中间那几十次动作是按什么顺序发生的？工具是谁决定要调的？你写在 CLAUDE.md 里的规则，是在哪一刻进入这条链路的？
这篇只做一件事：把官方文档 code.claude.com/docs/en/how-claude-code-works 和 code.claude.com/docs/en/features-overview 这两页里写明的路径按顺序走一遍，把工具与配置项的介入点逐个标出来。这个产品是闭源的，我们没有源码，也没有跑过，所以凡是文档没写的，下面一律写「官方文档没有说明这一点」——不替它补，也不由文档措辞去反推它内部怎么实现。
三个阶段，但不是三段流水线
文档把这条循环拆成三个阶段：gather context（收集上下文）、take action（采取动作）、verify results（验证结果）。
紧接着那句话很关键，转述时最容易漏掉：文档明确写着这几个阶段是混在一起的，Claude 全程都在用工具——搜索文件是为了理解代码，编辑是为了做出改动，跑测试是为了检查自己的工作。别把它想成「先查完、再改完、最后统一验证」的三段式流水线。
循环的形态随任务变。文档给的说法是：一个关于代码库的问题可能只需要收集上下文这一段；一个 bug 修复会把三个阶段反复走好几轮；一次重构可能牵扯大量验证工作。每一步要做什么，由模型基于上一步学到的东西来决定。
文档还自述了 Claude Code 自己的定位：这条循环由负责推理的模型和负责行动的工具两部分驱动，而 Claude Code 本身是围在模型外面的 agentic harness，提供工具、上下文管理和执行环境。这句是文档自述，原样转述，不做延伸。模型这一侧文档写明有多个可选，会话中用 /model 切换，或启动时用 claude --model <name>；具体有哪几个随时在变，这里不列。
工具是在哪一步介入的
文档说得直白：没有工具，模型只能回文本；有了工具才能读代码、改文件、跑命令、搜网页、跟外部服务打交道。每一次工具调用返回的信息都会回流进这条循环，成为下一步决策的输入。
内置工具，文档的原话是「大体上归为五类」（这个「五」我们回源数过，就是那张表的五行），每一类代表一种不同的行动能力：
| 类别 | 文档写明 Claude 能做什么 |
|---|---|
| File operations | 读文件、改代码、建新文件、重命名与重组 |
| Search | 按模式找文件、用正则搜内容、探索代码库 |
| Execution | 跑 shell 命令、起服务、跑测试、用 git |
| Web | 搜网页、抓文档、查报错信息 |
| Code intelligence | 编辑后看到类型错误与告警、跳转到定义、查找引用 |
最后一行有个前提条件容易被漏：文档写明 Code intelligence 这一类需要装对应的 code intelligence plugin，并且在《Extend Claude Code》那页进一步写明，在你为自己的语言装上插件之前，LSP tool 是 inactive 的。这一类能力不是开箱就在循环里的。这五类之外，文档说还有用于派生 subagent、向你提问以及其它编排用途的工具，完整清单在 code.claude.com/docs/en/tools-reference。
那么「一个工具什么时候会被调」这个问题，文档给的答案是：由模型根据你的 prompt 和沿途学到的信息来选。文档举的例子是你说「fix the failing tests」，它可能这样走（这六步是文档写的示例，不是我们跑出来的结果）：
- 跑测试套件，看哪里失败
- 读报错输出
- 搜相关的源文件
- 读这些文件、理解代码
- 编辑文件、修掉问题
- 再跑一次测试来验证
请注意文档在这里没有给出任何触发规则表、优先级或判定条件。想在脑子里建一个「什么输入必然触发什么工具」的状态机，这两页撑不起来。要确定性触发，文档指的是另一件东西——见下面 hooks 那一段。
循环开始之前，它手上已经有什么
文档列了在某个目录下运行 claude 之后它能访问到的东西：当前目录及子目录里的文件（目录之外的需要你授权）、你的终端（你能从命令行跑的任何命令）、你的 git 状态（当前分支、未提交改动、近期提交历史）、你的 CLAUDE.md、auto memory，以及你配置的扩展（MCP 服务器、skills、subagent，还有用于浏览器交互的 Claude in Chrome）。
auto memory 那一条有个细节值得记：文档写明每个会话开始时只载入 MEMORY.md 的开头一段，超过一定行数或体积就截断，以先到者为准。
扩展层挂在循环的哪个点上
《Extend Claude Code》开篇一句就定了调：扩展是插在这条 agentic loop 的不同位置上的。逐个说介入点：
CLAUDE.md：会话开始时载入全文，之后每个请求都带着它。多层级的CLAUDE.md是叠加关系，各层内容同时进上下文；冲突时文档说由模型自行调和，通常更具体的那条优先- skills：默认在会话开始只载入描述，被用到时才载全文。在 frontmatter 里写
disable-model-invocation: true，这个 skill 对模型完全不可见，直到你手动调用；不是你写的 skill 想做同样的事，文档给的是在 settings 里配skillOverrides - MCP：会话开始只载入工具名，完整的 JSON schema 延后加载，真要用某个工具时才取，文档写明 tool search 默认开启。看每个 server 的连接状态与占用用
/mcp - subagent：按需派生，拿到一份全新的隔离上下文。文档把里面装了什么列得很细——agent 自己的 system prompt（不是完整的 Claude Code system prompt）、
skills:字段里列出的 skill 的全文（启动时全量预载，跟主会话的按需加载不一样）、CLAUDE.md与 git 状态（内置的 Explore 和 Plan 两个 agent 这两样都不载），加上 lead agent 在 prompt 里传进去的内容。它不继承你的对话历史与已调用的 skills，干完只回一份摘要 - hooks：在生命周期事件上触发，比如工具执行、会话边界、prompt 提交、权限请求、压缩这些点位。文档写明 hook 在主对话之外执行，上下文成本为零，除非它返回的输出被作为消息加回对话
- code intelligence：在文件编辑之后、以及模型主动查符号时介入
hooks 这一条正好回答了上一节留下的确定性问题：文档写着，在 CLAUDE.md 或 skill 里写「永远别改 .env」是一个请求，不是保证；而一个 PreToolUse hook 把这次编辑挡下来才是强制。规则必须每次都成立时，文档给的建议是做成 hook 而不是写成提示词。
同名冲突时谁生效也是介入点的一部分：文档写明 skills 与 subagent 按名覆盖，MCP 服务器按名覆盖且顺序是 local > project > user，而 hooks 是合并的——所有注册过的 hook 都会在匹配事件上触发，不管来自哪一层。另外必须照实标一句：文档写明 agent teams 是 experimental，且默认关闭，别当成现成能力来规划工作流。
上下文填满时，先被丢掉的是什么
这是最值得记住的一段。文档写明上下文窗口里装着对话历史、文件内容、命令输出、CLAUDE.md、auto memory、已加载的 skills 和系统指令。快满的时候处理顺序是：先清掉较早的工具输出，不够再对对话做摘要。保留下来的是你的请求和关键代码片段，而对话早期那些详细指令可能会丢。
所以文档给的建议不是「多提醒几遍」，而是把长期规则放进 CLAUDE.md。想看什么在占地方用 /context；想控制压缩时保留什么，文档给了两条路：在 CLAUDE.md 里加一节 Compact Instructions，或者带焦点跑压缩，示例原文是 /compact focus on the API changes。
还有一个失败形态文档专门写了：如果单个文件或单次工具输出大到每次摘要完立刻又把上下文填满，Claude Code 会在若干次尝试后停止自动压缩并报错，而不是无限循环下去；恢复步骤在 code.claude.com/docs/en/troubleshooting 那一页。
你能在哪几个位置插手
文档说你也是这条循环的一部分，给了两个粒度不同的打断方式：按 Esc 是立即停下，正在跑的那次工具调用会被取消，然后等你的下一条指令；直接打字然后回车则不打断正在跑的工具，Claude 会在当前动作做完后读到你这句，再决定下一步。
另一侧是两个安全机制。checkpoints 这边，文档写明在编辑文件之前会先给文件内容拍快照，出问题按两下 Esc 回退，或者直接让它撤销。边界也写清楚了：checkpoints 独立于 git，恢复会话后仍然在；只覆盖文件改动；恢复时会跳过 symlink 与 hard link 的文件；影响远程系统的动作（数据库、API、部署）没法 checkpoint——文档自述这正是它在跑有外部副作用的命令前会先问你的原因。
permission mode 这边，文档写明按 Shift+Tab 在四档之间循环（这个「四」是我们把文档那一节的档位逐条数出来的，文档本身没写数字）：Manual 在文件编辑与 shell 命令前都问；Accept edits 会直接改文件、直接跑 mkdir、mv 这类常见文件系统命令，其它命令仍然问；Plan 只探索和提方案，不动你的源文件；Auto 则由它对所有动作做背景安全检查。此外可以在 .claude/settings.json 里放行特定命令，文档举的例子是 npm test 和 git status，并写明设置可以从组织级策略一路细化到个人偏好。
必须说明白：以上是文档写明的档位语义，不等于「授权了就没风险」。这条循环本来就是在你的机器上跑 shell、访问你的仓库，放行范围怎么定要按你自己的环境评估。
会话、路径与 Windows 这一侧
文档写明对话会以纯文本 JSONL 的形式写到本地，路径写法是 ~/.claude/projects/，每条消息、每次工具调用与结果都在里面，这也是回退、恢复与分叉的基础。
Windows 这一侧要说明白：这两页给出的就是 ~/.claude/projects/ 这一种写法，没有单独说明 Windows 下的对应位置，路径、保留期与清理方式要去 code.claude.com/docs/en/claude-directory 那一页查。上面提到的 Esc、Shift+Tab 这些键位，这两页同样没有做平台区分的标注——我们没有实测，所以不替它写「Windows 上应该也是这样」。
会话之间相互独立：文档写明每个新会话都是全新的上下文窗口，不带上一轮的对话历史；跨会话要留东西，靠的是 auto memory 和你写进 CLAUDE.md 的内容。恢复与分叉的区别写得很清楚：claude --continue 或 claude --resume 是在同一个 session ID 下追加消息；--fork-session 或 /branch 是把历史复制进一个新的 session ID，原会话不动。会话跟目录绑定，所以文档给的并行做法是用 git worktree 让每个分支各占一个目录，/resume 的选择器默认只列当前 worktree 的会话。以上命令与参数均为官方文档中出现的写法，未经实测，以官方文档与 --help 的实际输出为准。
执行环境文档列了三种：本地、云端（Anthropic 托管的虚拟机，或你所在组织自运维的 self-hosted 环境）、以及 Remote Control（代码仍在你的机器上跑，从浏览器操控）。接口则有终端、桌面端、IDE 扩展、网页端、Slack 与 CI/CD 等入口。文档强调的是：换接口不改变底层这条循环。
这两页没有回答的问题
走完一遍，有几处空白值得记住，免得在别处看到「据说」就当真：工具选择没有规则表，文档只说由模型基于 prompt 与沿途信息来定；压缩摘要的具体策略没写，只写了「先清工具输出、再摘要对话」的先后与什么会被优先保留；平台差异没写，路径与键位只有一种写法。
这个产品迭代频繁，上面每一个命令、配置项与档位名都可能随版本变动，请以官方文档最新内容为准。
本文依据 Claude Code 官方文档（code.claude.com/docs）于 2026-08-17 的公开内容整理。
该产品闭源，本文只复述官方文档写明的机制，不推断其内部实现；
我们没有对文中涉及的功能做过实测，因此不涉及界面外观、操作手感与运行速度的任何描述。
该产品迭代频繁，文中涉及的命令、配置项与默认值随版本变动，请以官方文档最新内容为准。
本文不涉及价格、额度与限流的具体数值，相关信息请以官方定价与用量说明页为准。
安全与合规相关做法请结合自身环境评估，本文不构成安全方案建议。