Appearance
Claude Code 通过三个阶段的代理循环完成任务：收集上下文、采取行动、验证结果。它会根据你的指令自主选择使用文件操作、搜索、执行命令、网页访问等工具，每次工具调用结果都会反馈到循环中。关键限制：上下文窗口填满后，早期指令可能被压缩丢失，因此持久规则需写入 CLAUDE.md；所有文件编辑自动生成检查点，可按 Esc 两次回退。用 /context 查看上下文占用，用 /compact 控制压缩焦点。
Claude Code 工作原理与架构详解
理解代理循环、内置工具以及 Claude Code 如何与你的项目交互。
Claude Code 是一个运行在终端中的智能编码助手。它擅长编码，也能帮你完成任何命令行能做的事：写文档、运行构建、搜索文件、调研问题等等。
本指南覆盖核心架构、内置能力以及高效使用技巧。分步教程请见常见工作流。关于技能、MCP、钩子等扩展功能，请见扩展 Claude Code。
Claude Code 的代理循环如何工作
当你给 Claude 一个任务时，它会经历三个阶段：收集上下文、采取行动、验证结果。这三个阶段是交织在一起的。Claude 全程使用工具：搜索文件理解代码、编辑文件做修改、运行测试检查结果。
循环会自适应调整。一个关于代码库的问题可能只需要收集上下文。修复一个 bug 会反复经历三个阶段。重构可能需要大量验证。Claude 根据前一步学到什么来决定下一步需要什么，可以链式执行数十个动作并沿途纠偏。
你也是这个循环的一部分。你可以随时中断，引导 Claude 换个方向、提供更多上下文、或者要求它尝试不同方法。Claude 自主工作，但随时响应你的输入。
代理循环由两个组件驱动：模型负责推理，工具负责行动。Claude Code 作为 代理框架 围绕 Claude 模型：它提供工具、上下文管理和执行环境，把语言模型变成能干的编码代理。
模型
Claude Code 使用 Claude 模型来理解你的代码并推理任务。Claude 能读取任何语言的代码，理解组件如何连接，以及计算出需要做什么改变来达成目标。对于复杂任务，它会分解成步骤、执行它们，并根据学到的东西调整。
多种模型可供选择，各有优劣。Sonnet 能很好地处理大多数编码任务。Opus 为复杂架构决策提供更强推理。在会话期间用 /model 切换，或者用 claude --model <name> 启动。
当本指南说 "Claude 选择" 或 "Claude 决定"，都是模型在做推理。
工具
工具是让 Claude Code 具备代理性的关键。没有工具，Claude 只能回复文本。有了工具，Claude 就能行动：读取代码、编辑文件、运行命令、搜索网络、与外部服务交互。每次工具调用都会返回信息，反馈到循环中，指导 Claude 的下一个决策。
内置工具大致分为五类，每类代表一种不同的代理能力。
| 类别 | Claude 能做什么 |
|---|---|
| 文件操作 | 读取文件、编辑代码、创建新文件、重命名和重新组织 |
| 搜索 | 按模式查找文件、用正则搜索内容、探索代码库 |
| 执行 | 运行 shell 命令、启动服务器、运行测试、使用 git |
| 网页 | 搜索网络、抓取文档、查错信息 |
| 代码智能 | 编辑后看到类型错误和警告、跳转到定义、查找引用（需要代码智能插件） |
这些是主要能力。Claude 还有生成子代理、向你提问以及其他编排任务的工具。完整列表见Claude 可用工具。
Claude 根据你的提示以及沿途学到的信息来选择使用哪些工具。当你说 "修复失败的测试"，Claude 可能会：
- 运行测试套件看看哪些失败
- 读取错误输出
- 搜索相关源文件
- 读取那些文件理解代码
- 编辑文件来修复问题
- 再次运行测试来验证
每次工具调用都给 Claude 新信息，指导下一步。这就是代理循环的实际运作。
扩展基础能力： 内置工具是基础。你可以通过技能扩展 Claude 的知识，通过 MCP 连接外部服务，通过钩子自动化工作流，通过子代理分担任务。这些扩展构建在核心代理循环之上。关于选择合适扩展的指导，见扩展 Claude Code。
Claude Code 能访问什么
本指南聚焦终端。Claude Code 也在 VS Code、JetBrains IDE 和其他环境中运行。
当你在一个目录中运行 claude 时，Claude Code 获得以下访问权限：
- 你的项目。 你目录及其子目录中的文件，经你许可后还能访问其他位置的文件。
- 你的终端。 任何你能运行的命令：构建工具、git、包管理器、系统工具、脚本。如果你能从命令行做，Claude 也能。
- 你的 git 状态。 当前分支、未提交的更改、最近的提交历史。
- 你的 CLAUDE.md。 一个 Markdown 文件，用于存储项目特定的指令、约定和上下文，Claude 每次会话都会知道。
- 自动记忆。 Claude 在你工作时自动保存的学习内容，比如项目模式和你偏好的设置。每次会话开始时，会加载
MEMORY.md的前 200 行或前 25KB（以先到为准）。 - 你配置的扩展。 用于外部服务的 MCP 服务器、用于工作流的技能、用于委托任务的子代理、以及用于浏览器交互的 Chrome 中的 Claude。
因为 Claude 能看到整个项目，所以能跨文件工作。当你要求 Claude "修复认证 bug"，它会搜索相关文件、读取多个文件理解上下文、跨文件做协调修改、运行测试验证修复、并按你的要求提交更改。这与只看到当前文件的内联代码助手不同。
环境与界面
上面描述的代理循环、工具和能力在 Claude Code 的任何使用位置都是一样的。变化的是代码在哪里执行以及你如何交互。
执行环境
Claude Code 运行在三种环境中，每种环境对代码执行位置有不同的权衡。
| 环境 | 代码运行位置 | 使用场景 |
|---|---|---|
| 本地 | 你的机器 | 默认。完全访问你的文件、工具和环境 |
| 云端 | Anthropic 管理的虚拟机 | 卸载任务，处理你没有本地仓库的项目 |
| 远程控制 | 你的机器，从浏览器控制 | 使用 Web UI 同时保持所有环境本地 |
界面
你可以通过终端、桌面应用、IDE 扩展、claude.ai/code、远程控制、Slack 和 CI/CD 流水线 访问 Claude Code。界面决定了你如何看到和交互 Claude，但底层的代理循环是相同的。完整列表见随处使用 Claude Code。
会话管理
Claude Code 会在你工作时本地保存对话。每条消息、每次工具使用和结果都写到一个纯文本 JSONL 文件中，位于 ~/.claude/projects/ 下。这支持回退、续传和分叉。在 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 Instructions" 部分，或运行带焦点的 /compact（如 /compact focus on the API changes）。
如果某个文件或工具输出太大，导致每次总结后上下文立即再次填满，Claude Code 会在几次尝试后停止自动压缩，并显示错误而不是无限循环。恢复步骤见自动压缩停止并报 "thrashing" 错误。
运行 /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/agents帮你配置自定义子代理/doctor诊断安装中的常见问题
它是对话式的
Claude Code 是对话式的。你不需要完美的提示词。从你想要的开始，然后逐步优化：
text
修复登录 bug[Claude 调查，尝试]
text
不太对。问题出在会话处理上。[Claude 调整方法]
当第一次尝试不对时，你不需要重新开始。你是在迭代。
中断和引导
你可以在任何时候重定向 Claude，不需要等它完成或重新开始：
- 按
Esc立即停止 Claude。正在运行的工具调用被取消，Claude 等待你的下一个指令。 - 输入修正并按
Enter在不停止正在运行的工具的情况下发送。Claude 在当前动作完成后立即读取，并在决定下一步之前调整。
一开始就明确
初始提示越精确，需要的纠正就越少。引用特定文件、提及约束、指向示例模式。
text
结账流程对有已过期卡片的用户是坏的。
检查 src/payments/ 中的问题，特别是 token 刷新。
先写一个失败的测试，然后修复它。模糊的提示也能工作，但你会花更多时间引导。像上面这样的具体提示通常一次就能成功。
给 Claude 提供验证依据
当 Claude 能检查自己的工作时，表现更好。提供测试用例、粘贴预期 UI 截图、或定义你想要的输出。
text
实现 validateEmail。测试用例：'user@example.com' → true，
'invalid' → false，'user@.com' → false。之后运行测试。对于视觉工作，粘贴设计截图，让 Claude 将其实现与截图比较。
先探索再实现
对于复杂问题，将调研与编码分开。使用计划模式（按两次 Shift+Tab）先分析代码库：
text
读取 src/auth/ 并了解我们如何处理会话。
然后创建一个添加 OAuth 支持的计划。审查计划，通过对话完善，然后让 Claude 实现。这种两步法比直接跳到代码产生更好的结果。
委派，而不是指挥
想象一下委派给一个能干的同事。提供上下文和方向，然后信任 Claude 来处理细节：
text
结账流程对有已过期卡片的用户是坏的。
相关代码在 src/payments/。你能调查并修复吗？你不需要指定要读哪些文件或运行什么命令。Claude 会搞定。
下一步
常见问题
Claude Code 上下文窗口满了怎么办？
当上下文接近限制时，Claude Code 会自动压缩：先清除旧工具输出，再总结对话。你的请求和关键代码片段会被保留，但早期指令可能丢失。运行 /context 查看空间占用，运行 /compact 控制压缩焦点。如果要防止丢失，把持久规则写在 CLAUDE.md 中。
如何撤销 Claude Code 对文件的修改？
按两次 Esc 回退到之前的状态，或者直接告诉 Claude 撤销。每个文件编辑前都会创建检查点，支持无限回退。注意检查点只覆盖文件更改，不影响远程系统（数据库、API、部署）。
Claude Code 能访问我电脑上的哪些内容？
当你运行 claude 时，它能访问项目目录中的文件、你的终端（任何你能运行的命令）、当前 git 状态、以及在 CLAUDE.md 和自动记忆文件中的指令。访问其他位置的文件需要你的明确许可。