Claude Code 的工作原理

理解智能体循环、内置工具以及 Claude Code 如何与你的项目交互。

Claude Code 是一个运行在终端中的智能体助手。除了擅长编码，它还能帮助完成任何可以通过命令行完成的工作：编写文档、运行构建、搜索文件、研究主题等。

本指南涵盖核心架构、内置能力以及高效使用 Claude Code 的建议。如需分步操作指南，请参阅常见工作流。如需了解技能、MCP 和钩子等功能扩展，请参阅扩展 Claude Code。

智能体循环

当你给 Claude 分配任务时，它会经历三个阶段：收集上下文、采取行动和验证结果。这些阶段相互融合。Claude 在整个过程中使用工具，无论是搜索文件以理解代码、编辑代码以做出更改，还是运行测试以检查工作。

循环会根据你的请求自适应调整。关于代码库的问题可能只需要收集上下文。修复 bug 则需要反复循环所有三个阶段。重构可能涉及大量验证。Claude 根据上一步学到的内容决定每一步需要什么，将数十个动作串联在一起，并沿途修正路线。

你也是这个循环的一部分。你可以随时中断，引导 Claude 转向不同方向、提供额外上下文，或要求它尝试不同方法。Claude 自主工作，但始终对你的输入保持响应。

智能体循环由两个组件驱动：模型负责推理，工具负责执行。Claude Code 作为 Claude 的智能体 harness：它提供工具、上下文管理和执行环境，将语言模型转变为有能力的编码智能体。

模型

Claude Code 使用 Claude 模型来理解你的代码并推理任务。Claude 可以读取任何语言的代码，理解组件之间的连接方式，并找出需要更改什么才能完成目标。对于复杂任务，它会将工作分解为步骤，执行它们，并根据学到的内容进行调整。

多个模型可用，各有不同的权衡。Sonnet 处理大多数编码任务表现良好。Opus 为复杂的架构决策提供更强的推理能力。在会话期间使用 /model 切换，或使用 claude --model <name> 启动。

当本指南提到"Claude 选择"或"Claude 决定"时，指的是模型在进行推理。

工具

工具使 Claude Code 具有智能体能力。没有工具，Claude 只能用文本回应。有了工具，Claude 可以采取行动：读取代码、编辑文件、运行命令、搜索网络以及与外部服务交互。每次工具使用都会返回信息，反馈到循环中，为 Claude 的下一步决策提供依据。

内置工具通常分为五类，每类代表一种不同的能动性。

这些是主要能力。Claude 还有用于生成子智能体、向你提问和其他编排任务的工具。完整列表请参阅 Claude 可用工具。

Claude 根据你的提示和沿途学到的内容选择使用哪些工具。当你说"修复失败的测试"时，Claude 可能会：

1. 运行测试套件查看哪些测试失败
2. 读取错误输出
3. 搜索相关源文件
4. 读取这些文件以理解代码
5. 编辑文件修复问题
6. 再次运行测试以验证

每次工具使用都给 Claude 提供新信息，指导下一步。这就是智能体循环的实际运作。

扩展基础能力： 内置工具是基础。你可以通过技能扩展 Claude 的知识，通过 MCP 连接外部服务，通过钩子自动化工作流，并通过子智能体卸载任务。这些扩展在核心智能体循环之上形成一层。有关选择合适扩展的指导，请参阅扩展 Claude Code。

Claude 可以访问什么

本指南聚焦于终端。Claude Code 也运行在 VS Code、JetBrains IDE 和其他环境中。

当你在目录中运行 claude 时，Claude Code 获得以下访问权限：

• 你的项目。 你目录和子目录中的文件，以及经你许可的其他位置的文件。
• 你的终端。 你可以运行的任何命令：构建工具、git、包管理器、系统工具、脚本。如果你可以从命令行执行，Claude 也可以。
• 你的 git 状态。 当前分支、未提交的更改和最近的提交历史。
• 你的 CLAUDE.md。 一个 markdown 文件，用于存储项目特定的指令、约定和 Claude 每次会话都应知道的上下文。
• 自动记忆。 Claude 在工作时自动保存的学习内容，如项目模式和你的偏好。MEMORY.md 的前 200 行或 25KB（以先到者为准）在每个会话开始时加载。
• 你配置的扩展。 用于外部服务的 MCP 服务器、用于工作流的技能、用于委派工作的子智能体，以及用于浏览器交互的 Claude in Chrome。

因为 Claude 可以看到你的整个项目，它可以跨项目工作。当你要求 Claude "修复认证 bug" 时，它会搜索相关文件，读取多个文件以理解上下文，跨文件进行协调编辑，运行测试验证修复，并在你要求时提交更改。这与只能看到当前文件的内联代码助手不同。

环境和接口

上述智能体循环、工具和能力在你使用 Claude Code 的任何地方都是相同的。变化的是代码执行的位置以及你与之交互的方式。

执行环境

Claude Code 在三种环境中运行，每种环境对代码执行位置有不同的权衡。

接口

你可以通过终端、桌面应用、IDE 扩展、claude.ai/code、远程控制、Slack 和 CI/CD 流水线访问 Claude Code。接口决定你如何看到和与 Claude 交互，但底层智能体循环是相同的。完整列表请参阅随处使用 Claude Code。

会话管理

Claude Code 在本地保存你的对话。每条消息、工具使用和结果都写入 ~/.claude/projects/ 下的纯文本 JSONL 文件，这支持回退、恢复和分叉会话。在 Claude 修改代码之前，它还会对受影响文件进行快照，以便在需要时恢复。有关路径、保留策略和如何清除这些数据，请参阅 ~/.claude 中的应用数据。

会话相互独立。 每个新会话以全新的上下文窗口开始，不包含之前会话的对话历史。Claude 可以使用自动记忆跨会话持久化学习内容，你可以在 CLAUDE.md 中添加自己的持久指令。

跨分支工作

每次 Claude Code 对话都是一个绑定到当前目录的会话。/resume 选择器默认显示当前工作树的会话，并提供键盘快捷键将列表扩展到其他工作树或项目。有关选择器快捷键和名称解析的完整列表，请参阅管理会话。

Claude 看到你当前分支的文件。当你切换分支时，Claude 看到新分支的文件，但你的对话历史保持不变。Claude 记得你讨论的内容，即使在切换之后。

由于会话绑定到目录，你可以通过使用 git worktrees 创建并行 Claude 会话，为单个分支创建单独的目录。

恢复或分叉会话

使用 claude --continue 或 claude --resume 恢复会话会在相同的会话 ID 下重新打开它，并将新消息追加到现有对话中。使用 --fork-session 或 /branch 分叉会将历史复制到新的会话 ID，保持原始会话不变。

有关恢复标志、/resume 选择器、命名以及同一会话在两个终端中打开时会发生什么，请参阅管理会话。

上下文窗口

Claude 的上下文窗口保存你的对话历史、文件内容、命令输出、CLAUDE.md、自动记忆、加载的技能和系统指令。随着工作进行，上下文会被填满。Claude 会自动压缩，但对话早期的指令可能会丢失。将持久规则放入 CLAUDE.md，并运行 /context 查看什么在占用空间。

有关加载内容和时机的交互式导览，请参阅探索上下文窗口。

上下文填满时

当你接近限制时，Claude Code 会自动管理上下文。它首先清除较旧的工具输出，然后在需要时总结对话。你的请求和关键代码片段会被保留；对话早期的详细指令可能会丢失。将持久规则放在 CLAUDE.md 中，而不是依赖对话历史。

要控制压缩期间保留的内容，请在 CLAUDE.md 中添加"压缩指令"部分，或使用 /compact 并指定焦点（如 /compact focus on the API changes）。

如果单个文件或工具输出太大，导致每次总结后上下文立即重新填满，Claude Code 会在几次尝试后停止自动压缩并显示错误，而不是陷入循环。有关恢复步骤，请参阅自动压缩因抖动错误停止。

运行 /context 查看什么在占用空间。MCP 工具定义默认延迟加载，并通过工具搜索按需加载，因此在 Claude 使用特定工具之前，只有工具名称消耗上下文。运行 /mcp 检查每个服务器的成本。

使用技能和子智能体管理上下文

除了压缩之外，你还可以使用其他功能控制加载到上下文中的内容。

技能按需加载。Claude 在会话开始时看到技能描述，但完整内容只在技能被使用时加载。对于手动调用的技能，设置 disable-model-invocation: true 以在需要之前将描述保留在上下文之外。对于非你编写的技能，使用 skillOverrides 在设置中执行相同操作。

子智能体获得自己的全新上下文，与你的主对话完全隔离。它们的工作不会膨胀你的上下文。完成后，它们返回摘要。这种隔离性就是子智能体有助于长会话的原因。

有关每个功能的成本，请参阅上下文成本，有关管理上下文的技巧，请参阅减少 token 使用。

通过检查点和权限保持安全

Claude 有两个安全机制：检查点让你撤销文件更改，权限控制 Claude 可以在不询问的情况下做什么。

使用检查点撤销更改

每次文件编辑都是可逆的。 在 Claude 编辑任何文件之前，它会对当前内容进行快照。如果出现问题，按两次 Esc 回退到之前状态，或要求 Claude 撤销。

检查点对你的会话是本地的，与 git 分开。它们只覆盖文件更改。影响远程系统的操作（数据库、API、部署）无法检查点，这就是 Claude 在运行具有外部副作用的命令之前会询问的原因。

控制 Claude 可以做什么

按 Shift+Tab 循环切换权限模式：

• 手动：Claude 在文件编辑和 shell 命令之前询问
• 接受编辑：Claude 编辑文件并运行常见的文件系统命令如 mkdir 和 mv 而不询问，其他命令仍会询问
• 计划：Claude 探索并提出计划，不编辑你的源文件；权限提示与手动模式相同
• 自动：Claude 通过后台安全检查评估所有操作。目前为研究预览版

你还可以在 .claude/settings.json 中允许特定命令，这样 Claude 就不会每次都询问。这对于 npm test 或 git status 等可信命令很有用。设置可以从组织范围策略到个人偏好进行分层。详情请参阅权限。

高效使用 Claude Code

这些技巧帮助你从 Claude Code 获得更好的结果。

向 Claude Code 求助

Claude Code 可以教你如何使用它。问诸如"如何设置钩子？"或"组织 CLAUDE.md 的最佳方式是什么？"等问题，Claude 会解释。

内置命令也会引导你完成设置：

• /init 引导你创建项目的 CLAUDE.md
• /doctor 运行设置检查，诊断安装和配置问题并可以修复它们

这是一场对话

Claude Code 是对话式的。你不需要完美的提示。从你想要什么开始，然后完善：

修复登录 bug

[Claude 调查，尝试某些方法]

不太对。问题在会话处理中。

[Claude 调整方法]

当第一次尝试不正确时，你不需要重新开始。你迭代。

中断和引导

你可以随时重定向 Claude，无需等待回合结束或重新开始：

• 按 Esc 立即停止 Claude。正在运行的工具调用被取消，Claude 等待你的下一个指令。
• 输入更正并按 Enter 在运行工具时发送，无需停止它。Claude 在当前操作完成后读取它，并在决定下一步之前调整。

upfront 具体

你的初始提示越精确，需要的更正就越少。引用特定文件，提及约束，并指向示例模式。

结账流程对过期卡用户已损坏。
检查 src/payments/ 中的问题，特别是 token 刷新。
先写一个失败的测试，然后修复它。

模糊的提示也可以工作，但你会花更多时间引导。像上面这样的具体提示通常第一次尝试就能成功。

给 Claude 验证依据

当 Claude 可以检查自己的工作时，它表现更好。包含测试用例、粘贴预期 UI 的截图，或定义你想要的输出。

实现 validateEmail。测试用例：'user@example.com' → true，
'invalid' → false, 'user@.com' → false。之后运行测试。

对于视觉工作，粘贴设计截图并要求 Claude 将其与实现进行比较。

先探索再实现

对于复杂问题，将研究与编码分开。使用计划模式（按 Shift+Tab 两次）先分析代码库：

读取 src/auth/ 并理解我们如何处理会话。
然后制定添加 OAuth 支持的计划。

审查计划，通过对话完善它，然后让 Claude 实现。这种两阶段方法比直接跳到代码产生更好的结果。

委派，而非命令

将 Claude 视为委派给有能力的同事。提供上下文和方向，然后相信 Claude 会弄清楚细节：

结账流程对过期卡用户已损坏。
相关代码在 src/payments/ 中。你能调查并修复吗？

你不需要指定读取哪些文件或运行哪些命令。Claude 会弄清楚。

下一步