# 工作原理：看懂 Claude Code

> 理解智能体循环、内置工具和上下文窗口这三样东西，你就能看懂 Claude Code 每一步在做什么，知道它为什么先读文件，也能挑对终端、IDE、桌面或网页里最适合你的那个入口。

- 网址：https://coding.chengyu.dev/learn/claude-code/how-it-works/
- 学习路径：Claude Code 精通
- 预计用时：15 分钟；核实日期：2026-10-25
- 官方来源：[How Claude Code works（Claude Code 官方文档）](https://code.claude.com/docs/en/how-claude-code-works)，[Tools reference（Claude Code 官方文档）](https://code.claude.com/docs/en/tools-reference)，[Explore the context window（Claude Code 官方文档）](https://code.claude.com/docs/en/context-window)，[Platforms and integrations（Claude Code 官方文档）](https://code.claude.com/docs/en/platforms)，[Claude Code 概览（Claude Code 官方文档）](https://code.claude.com/docs/en/overview)

## 学习目标

- 能说出智能体循环的三个阶段，并在真实会话里认出它们
- 能列出内置工具的五大类，知道哪些操作需要审批
- 能解释 Claude Code 为什么总是先读文件，以及上下文窗口里装了什么
- 能根据自己的工作方式选择终端、IDE、桌面或网页入口

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

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

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

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

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

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

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

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

```text
> 订单列表接口偶尔返回 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 和明确提示，新增测试覆盖该情况。
```

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

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

| 类别 | 能做什么 | 典型工具 |
|---|---|---|
| 文件操作 | 读文件、精确修改、新建或覆盖文件 | `Read`、`Edit`、`Write` |
| 搜索 | 按文件名模式找文件、按正则搜内容 | `Glob`、`Grep`，或 Bash 里的 `find` / `grep` |
| 执行 | 运行 shell 命令、启动服务、跑测试、用 git | `Bash`（Windows 上还有 `PowerShell`） |
| 网络 | 搜索网页、抓取文档 | `WebSearch`、`WebFetch` |
| 代码智能 | 改完后看到类型错误、跳转定义、查引用 | `LSP`（需要安装代码智能插件） |

此外还有一批「编排类」工具：`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 课[权限模式与安全](/learn/claude-code/permissions/)会细讲。

## 为什么它总是先读文件

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

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

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

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

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

> **国内老项目常见的坑：GBK 编码**
>
> `Edit` 和 `NotebookEdit` 会把整个文件按 UTF-8 写回，所以遇到 GBK、GB2312 这类旧编码的文件，它们会拒绝修改，避免把中文变成乱码。这时 Claude 会改用保留原编码的 shell 命令，或先问你要不要转成 UTF-8。维护老 Java、老 PHP 项目时，建议先统一编码再大规模交给它改。

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

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

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

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

> 小测：你让 Claude Code 把一个函数里的变量名 total 改成 amount，它却先用工具读了这个文件。最根本的原因是？

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

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

| 入口 | 适合 | 特点 |
|---|---|---|
| 终端 CLI | 习惯命令行、要写脚本或在服务器上用 | 功能最全，`claude -p` 非交互模式和 Agent SDK 只在 CLI 提供 |
| VS Code 扩展（也可装在 Cursor） | 不想离开编辑器 | 行内 diff、@ 引用文件、计划审阅 |
| JetBrains 插件 | IntelliJ IDEA、PyCharm、WebStorm 用户 | 在 IDE 终端里运行 CLI，需单独安装 CLI |
| 桌面应用 | 想要图形界面、并行跑多个会话 | 可视化 diff、应用预览，自带 Claude Code |
| 网页 claude.ai/code | 长任务、本地没有的仓库 | 在云端运行，关掉电脑也会继续 |
| 手机 App | 出门在外发起或查看任务 | 连接云端会话，或通过 Remote Control 操控本地会话 |

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

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

> **怎么选**
>
> 拿不准就先装终端 CLI：在项目目录里运行 `claude` 即可开始，功能最完整，后面的课程也以它为主。不习惯命令行的话，桌面应用是同一个引擎加图形界面。

> 小测：你在本机终端里给项目配好了 CLAUDE.md 和 .claude/settings.json，现在想换到 VS Code 扩展里继续用。这些配置会怎样？

## 动手试一试

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

**观察智能体循环**

```text
先不要修改任何文件。请帮我快速了解这个项目：
1. 它是做什么的，用了哪些主要技术栈；
2. 启动、构建、测试分别用什么命令（从配置文件里找依据，不要猜）；
3. 列出你为了回答上面两个问题实际读过的文件和运行过的命令。

最后告诉我：如果我要你给这个项目加一个小功能，你会先读哪几个文件，为什么。
```

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

- [ ] 能用自己的话说出智能体循环的三个阶段
- [ ] 记住哪些操作要过审批关：改文件、跑命令、联网抓取
- [ ] 在一个真实项目里运行 `claude`，发送上面的提示词，核对它读过的文件
- [ ] 输入 `/context`，看一眼上下文被哪些内容占用
- [ ] 根据自己的习惯，选定主力入口：终端、IDE 扩展、桌面应用或网页