Claude Code

一句话理解：Claude Code 的核心不是“会写代码的模型”，而是一套围绕代码仓库搭建的 Harness——用文件、搜索、终端和 Git 获取上下文与行动能力，用测试和构建验证结果，用权限模式、沙箱、Hooks 和检查点把自主性控制在可接受的范围内。

Claude Code 是 Anthropic 推出的 Coding Agent，也是学习 Agent 系统设计最好的样本之一：它把本课程几乎所有模块——上下文管理、工具、MCP、Skills、Subagent、Hooks、权限、沙箱、会话与记忆——都做成了用户看得见、可以配置的功能。

本文按 2026 年 9 月的官方文档拆解。产品迭代很快，具体命令与配置项请以 官方文档 为准。我们关注的不是功能清单，而是 每个功能背后的设计决策。

本模块每一课都用同一个框架拆解产品：八个维度对应「评估 Agent 产品的 8 个问题」，它们之间的关系如下：

它是什么、在哪里用

Claude Code 能读代码库、编辑文件、运行命令并接入开发工具。官方文档列出的使用界面包括：终端 CLI、VS Code 与 JetBrains 插件、桌面应用、浏览器中的 claude.ai/code，以及 Slack、GitHub Actions、GitLab CI/CD 等集成；开发者还可以通过 Agent SDK 用同样的工具和能力构建自己的 Agent。

官方文档特别强调：不同界面连接的是同一个底层引擎，因此仓库里的 CLAUDE.md、设置和 MCP Server 在各个界面上都生效。这本身就是一个设计决策——配置跟着仓库走，而不是跟着界面走。

按官方文档，把这些界面、共用的引擎与控制机制画成一张架构图：

用八个问题拆解

1. 它完成什么 Job？

在代码仓库中完成开发任务：理解代码、修 Bug、实现功能、写测试、处理合并冲突、提交 commit 与 PR。官方文档把它的工作方式描述为三个交织的阶段：收集上下文、采取行动、验证结果，并根据上一步学到的东西决定下一步。

Job 的边界非常清晰：产出是仓库里的代码变更，而代码变更天然可以被 diff、测试和回滚。这正是「办公 Agent 与 Coding Agent」中说的“天然反馈闭环”。

2. 它能调用哪些工具？

官方文档将内置工具分为五类：

类别	能做什么
文件操作	读文件、编辑代码、创建与重命名文件
搜索	按模式找文件、用正则搜索内容
执行	运行 Shell 命令、启动服务、跑测试、使用 Git
Web	搜索网页、抓取文档
代码智能	编辑后查看类型错误、跳转定义、查找引用（需要安装代码智能插件）

此外还有派生 Subagent、向用户提问等编排类工具。扩展方式有四种：Skills（可复用的工作方法）、MCP（连接外部服务，如 Jira、Slack、Google Drive）、Hooks（在特定事件执行确定性脚本）、Subagents（委派子任务）。

设计上值得注意的一点：终端是一个“万能工具”——用户能在命令行做的事它都能做。这带来了极强的能力，也是为什么 Claude Code 需要一整套权限与沙箱机制。

3. 它拿得到什么上下文？

在项目目录中启动后，它可以访问：项目文件、终端、当前 Git 状态（分支、未提交变更、提交历史）、CLAUDE.md、自动记忆，以及你配置的扩展。

几个关键的上下文设计：

• CLAUDE.md：放在项目中的 Markdown 文件，每次会话开始时读取，用来写代码规范、架构决策、常用命令。它是“持久指令”的载体。
• 自动记忆（auto memory）：Claude 在工作中自动保存学到的内容；官方文档说明会话开始时加载 MEMORY.md 的前 200 行或前 25KB（以先到者为准）。
• 按需加载：Skills 在会话开始时只加载描述，使用时才加载全文；MCP 工具定义默认延迟加载，通过工具搜索按需载入。这正是「渐进式披露」的实现。
• 自动压缩：接近上下文上限时，先清理较早的工具输出，再在必要时总结对话。可以在 CLAUDE.md 中写“Compact Instructions”控制压缩时保留什么，也可以用 /context 查看上下文占用。
• Subagent 隔离：Subagent 在自己的上下文窗口中工作，结束后只把摘要返回主会话，保护主上下文不被探索性的工具输出淹没。

4. 它在哪里执行？

官方文档列出三种执行环境：

环境	代码在哪里运行	适用场景
Local	你的机器	默认，完整访问本地文件、工具与环境
Cloud	Anthropic 托管的虚拟机，或组织自己运营的自托管环境	卸载长任务、处理本地没有的仓库
Remote Control	你的机器，通过浏览器控制	用 Web 界面操作，但执行与文件留在本地

本地执行时，Bash 沙箱可以在操作系统层面限制命令能访问的文件和网络域名（macOS 使用 Seatbelt，Linux 与 WSL2 依赖 bubblewrap）。在沙箱边界内的命令可以自动放行，越界的命令回到正常的权限流程。

此外还有定时执行能力：在云端运行的 Routines、桌面应用的本地定时任务，以及会话内重复执行提示的 /loop。

5. 它如何决定下一步？

由模型在 Agent Loop 中动态决定：修一个失败测试时，它可能先跑测试、读错误、搜索相关文件、阅读代码、修改、再跑测试。官方文档强调用户也在循环中——可以随时按 Esc 中断，或直接输入纠正意见，Claude 会在当前动作完成后读取并调整。

对于复杂任务，计划模式（Plan） 让它先只读探索、提出计划，而不修改源文件；用户认可后再执行。这是「规划与任务拆解」在产品中的体现：把“想清楚”和“动手做”分成两个可审阅的阶段。

多 Agent 方面，自定义 Subagent 用带 YAML frontmatter 的 Markdown 文件定义（项目级放在 .claude/agents/，用户级放在 ~/.claude/agents/），可以限制 tools、指定 model、permissionMode、maxTurns，甚至用 isolation: worktree 在独立的 Git worktree 中工作。内置 Subagent 包括只读的 Explore、计划模式使用的 Plan，以及通用的 general-purpose。

6. 它如何验证结果？

验证主要依赖代码世界的外部信号：运行测试、构建、Lint，查看类型错误。官方文档中的典型示例就是“写测试、运行、修复失败”。这些信号是程序给出的，而不是模型自评，因此非常可靠。

产品层面还提供了把验证“固化”的手段：

• Hooks：在 PostToolUse 等事件上运行脚本，例如每次编辑后自动格式化，或提交前运行 Lint。
• CI 集成与代码审查：通过 GitHub Actions、GitLab CI/CD 自动审查 PR 与处理 Issue。

7. 什么时候需要人确认？

这是 Claude Code 设计最细致的部分。首先是 权限模式：

模式	行为
default（界面上显示为 Manual）	首次使用每类工具时询问
acceptEdits	自动接受文件编辑和常见文件系统命令，其他命令仍询问
plan	只读探索并提出计划，不编辑源文件
auto	由后台分类器审查动作，拦截有风险的动作而不是询问用户
dontAsk	所有本应询问的调用都自动拒绝，只运行已预先允许的动作
bypassPermissions	跳过权限提示；官方建议只在容器或虚拟机等隔离环境中使用

其次是 权限规则：在设置文件中配置 allow、ask、deny 规则，评估顺序固定为 deny → ask → allow，更具体的 allow 规则无法覆盖 deny 规则。设置有多个层级，组织管理员下发的 managed settings 优先级最高，其他层级无法覆盖。

最后是 Hooks 作为确定性闸门：PreToolUse Hook 以退出码 2 结束即可阻止工具调用；但 Hook 返回“允许”也无法绕过 deny 规则。这正是「程序校验优先」原则：模型的决定要经过程序和策略的检查。

8. 失败如何恢复？

• 检查点：每次编辑文件前自动快照，按两次 Esc 可以回退。官方文档明确指出，检查点只覆盖文件变更，数据库、API、部署等远程副作用无法通过检查点撤销——这类动作只能靠权限模式与规则来控制。
• Git：代码变更本身在版本控制中，可以 diff、撤销、开分支。
• 会话恢复与分叉：会话以 JSONL 文件保存在本地，可以用 --continue、--resume 恢复，或用 --fork-session 分叉出新会话尝试另一种方案。
• 防止失控循环：如果单个文件或工具输出过大，导致压缩后上下文立刻又被填满，自动压缩会在几次尝试后停止并报错，而不是无限循环。

可借鉴的设计决策

设计决策	Claude Code 的做法	迁移到业务 Agent
持久指令跟着工作空间走	CLAUDE.md 放在仓库里，所有界面共用	业务规则与 SOP 放在版本化的 Skill 与配置中，而不是散落在各个入口的 Prompt 里
能力强的工具配强约束	终端几乎无所不能，因此有权限模式、规则、沙箱三层控制	高风险写入工具必须有分级、规则与隔离，而不是只靠 Prompt 提醒
自主性是用户可调的	从 Manual 到 auto 再到 bypass，按场景切换	为不同角色和任务提供不同自主性档位，默认保守
先计划再执行	计划模式只读探索并产出计划	高影响任务先输出“处置计划”供审阅，再进入执行
上下文按需加载	Skill 描述常驻、全文按需；MCP 工具延迟加载；Subagent 隔离探索	大量工具与知识场景下，用渐进式披露控制上下文和成本
确定性逻辑插在生命周期上	Hooks 在工具调用前后执行脚本，deny 规则优先	在“写入前”插入程序校验，在“写入后”插入读回验证
坦诚说明回滚边界	文档明确检查点不覆盖远程副作用	在 UI 中区分“可撤销”与“不可撤销”动作，后者走审批

常见误区

• “Claude Code 效果好，是因为模型强。” 同一个模型放在没有测试、没有权限设计的环境里，效果会差很多。Harness 与反馈闭环同样关键（参见「模型与 Harness」）。
• “bypassPermissions 能提高效率，可以默认开。” 官方文档明确只建议在隔离环境中使用。效率应该通过沙箱与精细规则获得，而不是关闭检查。
• “有检查点就不怕出错。” 检查点只能恢复本地文件，已经推送的代码、调用过的 API、执行过的数据库变更都无法撤销。

设计要点

• 为强能力工具设计多层控制：模式、规则、沙箱、Hooks。
• 区分可回滚动作与不可回滚动作，并在产品文档与 UI 中写清楚。
• 把团队约定写进随工作空间版本化的文件，而不是依赖每次对话。
• 用计划阶段降低高影响任务的风险。
• 用 Subagent 隔离探索性工作，保护主上下文。

练习

在一个你熟悉的小仓库中使用 Claude Code（或同类 Coding Agent），用 45–60 分钟：

1. 用 /init 或手写一份 CLAUDE.md，写清构建、测试命令和两条代码规范。
2. 让它在计划模式下为一个小功能提出计划，审阅后再执行。
3. 配置一条 deny 规则（例如禁止 git push），观察它尝试时的表现。
4. 按本文的八个问题，写下你观察到的与文档描述不一致或更细节的地方。

延伸阅读

• How Claude Code works：Agent Loop、工具、执行环境、上下文与检查点。
• Configure permissions：权限模式、规则语法与优先级。
• Configure the sandboxed Bash tool：文件系统与网络隔离。
• Hooks reference：生命周期事件与阻断机制。
• Create custom subagents：Subagent 的定义与配置。

下一步

下一课「Codex」拆解另一款主流 Coding Agent，重点看它在沙箱、云端环境与自动审查上的不同选择。