文档索引

在此获取完整文档索引：https://code.claude.com/docs/llms.txt 使用此文件发现所有可用页面，然后再进一步探索。

Claude Code 工作原理

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

Claude Code 是一个在终端中运行的智能体助手。虽然它擅长编码，但它可以帮助你完成任何可以从命令行完成的事情：编写文档、运行构建、搜索文件、研究主题等。

本指南涵盖核心架构、内置功能和高效工作的技巧。有关分步演练，请参阅常见工作流。有关技能、MCP 和钩子等可扩展性功能，请参阅扩展 Claude Code。

智能体循环

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

The agentic loop: Your prompt leads to Claude gathering context, taking action, verifying results, and repeating until task complete. You can interrupt at any point.

循环会适应你的要求。关于代码库的问题可能只需要上下文收集。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
Web	搜索网络、获取文档、查找错误消息
代码智能	编辑后查看类型错误和警告、跳转到定义、查找引用（需要代码智能插件）

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

Claude 根据你的提示和沿途学到的内容选择使用哪些工具。当你说"fix the failing tests"时，Claude 可能会：

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

每次工具使用都给 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 服务器、用于工作流的技能、用于委派工作的子智能体和用于浏览器交互的 Chrome 中的 Claude。

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

环境和接口

上面描述的智能体循环、工具和功能在你使用 Claude Code 的任何地方都是相同的。变化的是代码在哪里执行以及你如何与之交互。

执行环境

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

环境	代码运行位置	使用场景
本地	你的机器	默认。完全访问你的文件、工具和环境
云	Anthropic 管理的 VM	卸载任务、处理你本地没有的仓库
Remote Control	你的机器，从浏览器控制	使用 Web UI 同时保持一切在本地

接口

你可以通过终端、桌面应用、IDE 扩展、claude.ai/code、Remote Control、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 worktree 运行并行 Claude 会话，它为单个分支创建单独的目录。

恢复或分叉会话

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

Session continuity: resume continues the same session, fork creates a new branch with a new 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 会在几次尝试后停止自动压缩并显示错误而不是循环。有关恢复步骤，请参阅自动压缩因抖动错误而停止。

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

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

除了压缩，你可以使用其他功能来控制什么加载到上下文中。

技能按需加载。Claude 在会话开始时看到技能描述，但完整内容仅在使用技能时加载。对于你手动调用的技能，设置 disable-model-invocation: true 以在你需要之前将描述排除在上下文之外。对于你没有编写的技能，使用 skillOverrides 从设置中实现相同效果。

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

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

使用检查点和权限保持安全

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 可以教你如何使用它。问一些问题，如 "how do I set up hooks?" 或 "what's the best way to structure my CLAUDE.md?"，Claude 会解释。

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

/init 指导你为项目创建 CLAUDE.md
/agents 帮助你配置自定义子智能体
/doctor 诊断安装中的常见问题

这是一场对话

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

Fix the login bug

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

That's not quite right. The issue is in the session handling.

[Claude 调整方法]

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

中断和引导

你可以在任何时候重定向 Claude，无需等待轮次完成或重新开始：

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

提前具体说明

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

The checkout flow is broken for users with expired cards.
Check src/payments/ for the issue, especially token refresh.
Write a failing test first, then fix it.

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

给 Claude 可验证的东西

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

Implement validateEmail. Test cases: '[email protected]' → true,
'invalid' → false, '[email protected]' → false. Run the tests after.

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

先探索再实施

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

Read src/auth/ and understand how we handle sessions.
Then create a plan for adding OAuth support.

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

委派而非命令

就像委派给一位有能力的同事一样思考。给出上下文和方向，然后信任 Claude 来解决细节：

The checkout flow is broken for users with expired cards.
The relevant code is in src/payments/. Can you investigate and fix it?

你不需要指定读取哪些文件或运行哪些命令。Claude 会自己解决。

下一步

◆功能扩展

添加技能、MCP 连接和自定义命令

◆常见工作流

典型任务的分步指南