工作原理：看懂 Claude Code

第一次用 Claude Code 的人，常有这样一个瞬间：你只说了句「订单列表接口偶尔返回 500，帮我修一下」，它却不急着改代码，而是先翻了七八个文件、跑了一遍测试、又查了日志格式。你可能会想：直接改不就完了？

这一课就回答这个问题。把它的工作方式拆开看，你会发现「先读」不是磨蹭，而是它把事做对的前提。理解了这一点，后面学 CLAUDE.md、权限、上下文管理时，你会知道每个配置到底在影响哪一环。

智能体循环：收集、行动、验证

官方把 Claude Code 的工作方式描述为一个循环，分三个阶段：

1. 收集上下文：搜索、读文件、看 git 状态，弄清现状；
2. 采取行动：编辑文件、运行命令；
3. 验证结果：跑测试、看报错、对照目标，不满足就回到第 1 步。

这三个阶段不是死板的流水线。问一个「登录流程是怎么走的」，可能只需要第 1 步；修一个 bug，会反复转好几圈；做重构，验证可能占一半时间。每一步做什么，由模型根据上一步拿到的信息决定。

驱动这个循环的是两样东西：模型负责推理，工具负责动手。Claude Code 本身是包在模型外面的那一层，负责提供工具、管理模型能看到的内容，官方把这一层叫作「智能体运行框架（agentic harness）」。

你也在这个循环里。随时按 Esc 可以立即停下当前操作；如果不想打断，直接输入一句纠正再回车，消息会排队，Claude 在当前工具调用结束后就会读到并调整方向。

> 订单列表接口偶尔返回 500，帮我找原因并修好
⏺ 先复现问题，看一下测试和日志。
  Bash pnpm test -- order
  ✗ 1 failed: 分页参数 pageSize=0 时抛出除零异常
# ↑ 收集上下文：先跑测试拿到真实报错
  Read src/modules/order/order.service.ts
  Read src/common/pagination.ts
⏺ 问题在分页工具没有校验 pageSize，我在入口处加校验并补一个测试。
  Edit src/common/pagination.ts  (+5 -1)
  Edit test/order.spec.ts  (+12 -0)
# ↑ 采取行动
  Bash pnpm test -- order
  ✓ 9 passed
# ↑ 验证结果，通过后才汇报
⏺ 已修复：pageSize 小于 1 时返回 400 和明确提示，新增测试覆盖该情况。

内置工具：它能伸手做哪些事

没有工具，模型只能回复文字；有了工具，它才能读代码、改文件、跑命令。官方把内置工具分成五类：

此外还有一批「编排类」工具：Agent 用来派出子智能体，AskUserQuestion 用来向你提选择题，Skill 用来调用 Skill，EnterPlanMode / ExitPlanMode 负责进出计划模式。完整清单以官方 Tools reference 为准，工具名就是你以后写权限规则时用的名字。

有两个细节值得记住：

• 在 macOS、Linux 和 WSL 上，默认工具集里没有 Glob 和 Grep。Claude 改用 Bash 里的 find 和 grep（内置的是 bfs 和 ugrep 实现）来搜索，所以你在权限规则和 hook 里看到的是 Bash 调用。Windows 上则保留这两个工具。
• 读文件不用批准，改文件和跑命令要过一道关。Read、搜索类操作在工作目录内直接执行；在 Manual 模式下，Edit、Write、Bash、WebFetch 都会在执行前请求你许可（ls、cat、git status 这类内置的只读命令除外）；新版默认的 auto 模式下，则由一个分类器模型代你审查，只拦下有风险的操作。具体怎么调，第 3 课权限模式与安全会细讲。

为什么它总是先读文件

回到开头的问题。「先读」至少有四个原因：

第一，每个会话都从空白开始。 新会话的上下文窗口是空的，它不记得昨天和你聊过什么。除了 CLAUDE.md 和自动记忆这类每次都会加载的内容（第 2 课细讲），它对你的项目一无所知，只能现场去看。

第二，Edit 是精确替换，不读就没法改。 Edit 工具的原理是拿一段原文 old_string 换成新文本 new_string，不做模糊匹配，差一个空格都会失败，而且这段原文在文件里必须唯一。所以它要先看到文件的真实内容。官方还设置了「先读后改」检查：较早的模型必须先在本会话里读过文件才能编辑，较新的模型在读取无需授权时可以放宽，但它通常仍会先读。

第三，读文件会顺带加载局部规则。 子目录里的 CLAUDE.md、带 paths 的路径规则，都是在 Claude 读到对应目录的文件时才加载的。不读，这些约定就进不了上下文。

第四，没有证据就没法验证。 先跑一遍测试、看一遍现有实现，它才知道「改完以后什么样算对」。

上下文窗口：它「知道」的全部

上下文窗口（context window）是模型在这一刻能看到的全部内容。打开会话、你还没输入时，里面已经有：系统指令、CLAUDE.md、自动记忆索引 MEMORY.md 的前 200 行或 25KB（以先到者为准）、MCP 工具的名字、各个 Skill 的描述。之后，你的每条消息、它读的每个文件、每次命令输出，都会继续往里放。

窗口快满时，Claude Code 会自动处理：先清理较早的工具输出，必要时把对话压缩成摘要。你的请求和关键代码会尽量保留，但对话早期的细节指令可能丢失。所以官方的建议很明确：需要长期遵守的规则写进 CLAUDE.md，不要只在聊天里说一次。

随时可以输入 /context 查看窗口被哪些内容占用。怎么清理、压缩、开新会话，第 4 课管理上下文与会话会系统讲。

在哪里用：同一个引擎，多个入口

Claude Code 不只是一个终端程序。官方提供了多种界面，背后是同一套智能体循环和工具，区别在于你怎么看、怎么操作，以及代码在哪里执行。

另外还有几种集成方式：在 Slack 里 @Claude 把问题变成 PR，在 GitHub Actions / GitLab CI 里跑自动化（第 9 课无头模式与 CI），用 Remote Control 从手机或浏览器继续操作本机上正在跑的会话。

从执行位置看，可以归成三种：本地（代码在你电脑上跑，默认方式）、云端（在 Anthropic 托管的虚拟机里跑）、Remote Control（在你电脑上跑，但用网页界面操控）。在本地的几个入口之间，项目的 CLAUDE.md、设置文件和 MCP 服务器配置是共用的，所以在终端里配好的东西，换到 VS Code 里同样生效。

动手试一试

找一个你熟悉、已经用 git 管理的项目，进入目录运行 claude，把下面这段话发给它。这一步只读不改，可以放心尝试：

看它的回复时，留意第 3 条：它读了哪些文件、跑了哪些命令，这就是循环里「收集上下文」那一步。再输入 /context，看看这一轮对话占了多少上下文。