Claude Code
手册

序 上下文是最重要的资源

Preface

Claude Code 的官方最佳实践，开篇第一句讲的不是提示词。它讲的是一个约束。

原话是这样的：

这句话决定了这本书的写法。

Claude Code 的功能很多。比如 CLAUDE.md、Skills、MCP、Hooks。再比如 Plugins、子智能体、云端会话、定时任务。单独看，每个都像是一个独立的新特性。但把它们放在「上下文」这条线上，就会发现它们几乎都在做同一件事。

理解了这条线，你就不需要死记每个功能的用法，因为你知道它们为什么存在。

第二条线：给它一个验证的办法

官方文档还反复强调另一件事。给 Claude 一个它自己能运行的检查，比如测试、构建、截图对比。

没有检查，「看起来完成了」就是它唯一的信号。你就成了那个验证循环，每个错误都要等你发现。有了检查，它会自己跑、自己读结果、自己迭代。这是「你得盯着的会话」和「你能走开的会话」之间的分界。

全书五段

五段对应五个能验收的状态：

• 装上，并跑通一个真实任务。
• 日常用得顺，不用总是重新交代。
• 会用 Skills、MCP、Hooks、Plugins 扩展它。
• 能让多个 Agent 并行，能接进 CI。
• 能带着团队用起来，并且管得住成本。

怎么用这本书

关于内容来源

这是一份非官方社区手册。Anthropic 自己维护着官方中文文档，写得不差。但一百多篇按主题平铺，新人不知道从哪读起。这本书做的事，是把同一批内容按学习顺序重新组织，并补上「为什么」。

写这本书时我们发现，官方中文文档本身落后于英文版。比如中文版的模型配置页，在成稿时还写着几个月前的默认模型。所以本书凡是版本敏感的内容，都对照了英文文档、线上页面和官方更新日志。

三条编写纪律

价格只用官方定价页，未核实的不写。 Max 档的确切月价和各档的具体用量额度，官方页面没有给出明确数字。本书就不写数字。

命令逐字取自官方文档。 改过名的命令（比如 claude project purge 已改为 claude purge）按新名写。

不编造经历。 书里的判断和建议都有出处，「我建议」只用来表达判断，不用来虚构实测。

从第一个问题开始：它到底是什么。

§01 Claude Code 是在你代码库里干活的 Agent

Claude Code Is an Agent That Works Inside Your Codebase

先讲清它是什么、怎么转、能在哪里用。再立起贯穿全书的两条线，后面每一节都会挂回来。

1.1 它能自己动手，这是和聊天框的根本区别

设想你对一个聊天窗口说「修一下登录 bug」。它回你一段代码。剩下的活全归你：找文件、粘贴、跑测试、把报错再贴回去。

同样一句话交给 Claude Code，它会自己去搜相关文件，读代码，改，跑测试，看报错，再改。你在旁边看着，需要时插一句话。

官方把它叫作代理式编码环境（agentic coding environment）。它答完不会干等。它能读你的文件、跑命令、做修改。你看着、插话，或者干脆走开，它都会接着往下做。

用三个角色来记。行内补全是你的副驾，只看得见当前文件。聊天窗口是你的顾问，只看得见你贴给它的内容。Claude Code 是你的独立工程师，看得见整个项目，还能自己执行。

从现在开始，你是给方向、验收结果的人。它是动手的人。

1.2 代理循环：收集上下文、动手、验证，反复转

你给它一个任务，它会走三个阶段：收集上下文，采取行动，验证结果。这三个阶段会混在一起转。搜文件是在收集，改代码是在行动，跑测试是在验证。

循环转几圈，由任务决定。问一个代码库问题，可能只用到收集。修 bug 会把三步转很多圈。重构的大头在验证。每一步做什么，取决于上一步学到了什么。它能连着做几十个动作，边走边纠偏。

驱动循环的是两样东西。模型负责推理，工具负责动手。Claude Code 是套在模型外面的那一层，给它工具，并管理模型能看到的上下文。没有工具，模型只能回文字。有了工具，才叫 Agent。

这五类是基础工具。派生子智能体、向你提问这类编排工具另有一批，完整清单在官方的工具参考里。

举个例子。你说「把挂掉的测试修好」，它大概这样走：

• 先跑测试套件，看哪些挂了。
• 读报错输出。
• 搜相关源文件，再读进来。
• 改文件。
• 重新跑测试，确认修好。

每次工具调用的结果都会回到循环里，决定下一步。这就是它能自己纠错的原因。

你也在这个循环里。按 Esc 立刻叫停，正在跑的工具调用会被取消，Claude 等你下一条指令。直接打字再按 Enter 不会打断工具，它在当前动作结束后读到你的话，再调整下一步。

1.3 同一个引擎，七八个入口

每个入口连的都是同一个 Claude Code 引擎。仓库里的 CLAUDE.md、设置和 MCP 服务器，在本地各入口之间通用。变的只有两件事：代码在哪儿执行，你怎么跟它交互。

代码执行的位置只有三种。本地是你的机器，默认，能用上你全部的文件和工具。云端是 Anthropic 托管的虚拟机，或你所在组织自建的环境。Remote Control 是代码和文件留在本机，只拿浏览器当遥控器。

Desktop 支持 macOS 和 Windows。Ubuntu 与 Debian 版还在 beta。手机端不是独立产品。它是进云端会话的窗口，也能用 Remote Control 遥控本机会话。

再看你不在电脑前，或者要接别的系统时，还有这些入口：

• Remote Control：用手机或浏览器接管本机上跑着的会话，用 claude remote-control 启动。
• Channels：外部消息推进会话。来源有 Telegram、Discord、iMessage，或自建 webhook。
• Slack：旧版 Slack 机器人自 2026-10-05 起退役。接入 Claude Tag 的工作区里，它不再响应。Team 和 Enterprise 走 Claude Tag。它以组织共享身份运行 @Claude。Pro 和 Max 的个人用法，以官方 Slack 页为准。
• Chrome：操作你已登录的浏览器，测 Web 应用、填表单。需要直连的 Anthropic 套餐，支持 Chrome 与 Edge，WSL 不支持。
• GitHub Actions 与 GitLab CI/CD：把 Claude 跑进流水线。做 PR 审查和 issue 分诊，见 §11。
• Routines 与计划任务：按时间或事件触发。Routines 跑在云上，你的电脑关机也照常执行，见 §11。
• Agent SDK：用 Claude Code 的工具与权限能力，搭你自己的 Agent。

我的建议是先只选一个入口。终端或 VS Code 扩展，二选一，把主线学会再往外扩。引擎是同一个，换入口不用重学。

1.4 主线一：上下文是最重要的资源

序里引过官方《最佳实践》的开篇。它的意思是：context window 填充速度很快，随着填充，性能会下降。后文又补了一句：「context window 是最重要的资源。」

这里的「上下文」，指它当前能看到的全部内容：每条消息、读过的每个文件、每次命令的输出。官方估计，一次调试或一次代码库探索，就可能消耗数万 token。

满了会怎样？它可能开始「遗忘」前面的指令，或者犯更多错误。Claude Code 会自动处理：先清理较旧的工具输出，必要时再把整段对话做摘要。你的请求和关键代码片段会保留，早期的详细指令可能丢。所以要长期生效的规则，别指望留在对话里。

还有一点常被忽略。你没开口，上下文就已经被占了一部分。CLAUDE.md 在会话开始时全文加载，之后每次请求都带着。Skills 只放描述，MCP 只放工具名。自动记忆里 MEMORY.md 的前 200 行或 25KB 也会在启动时读入。先到哪个上限，就按哪个算。每个新会话都从一个全新的上下文窗口开始，不继承上次的对话。

下面这张表，就是全书的地图。后面几乎每个功能，都能回答一个问题：它怎样替你省上下文。

表里每一行，都是同一个思路的不同做法：别让不该占位置的东西占位置。§04 会把这条线写透。

1.5 主线二：给它一个能验证工作的方法

第二条线要短得多，但同样关键。官方的说法很直接。有没有一个它能自己运行的检查，决定了这是哪种会话。一种你得盯着，一种你可以走开。

道理很直接。Claude 觉得工作「看起来完成」就会停。没有可跑的检查，「看起来完成」是唯一的信号，于是你成了验证环节，每个错误都等你来发现。给它一个有通过或失败结果的东西，循环就自己闭合。它干活，跑检查，读结果，迭代，直到检查通过。

检查可以是任何它能在对话里读到信号的东西：

• 测试套件。
• 构建的退出码。
• linter。
• 对比输出和样本文件的脚本。
• 浏览器截图，拿去对照设计稿。

实现一个验证邮箱地址的函数

写一个 validateEmail 函数。
示例：user@example.com 为 true，
invalid 为 false，user@.com 为 false。
实现后运行测试。

差别就在最后一句。左边只能靠你读代码判断对错，右边它自己就能知道。这条线在 §03 会落到具体做法，到 §11 无人值守时分量最重。

1.6 这一节的结论

Claude Code 是一个读你代码库、跑你命令的 Agent。它按「收集、行动、验证」循环工作，你随时能插话。

入口很多，引擎只有一个。我的建议是先选终端或 VS Code，把两条线用熟：管住上下文，给它验证方法。

下一节先把它装起来、登录进去，再把账单的算法看明白。

§02 装上只要一条命令，账单要先看明白再放开用

Install, Sign In, and Read the Bill Before You Scale Up

十分钟内装好、登录、跑通第一个会话。再把订阅和 API 两种算账方式、模型的默认值和切换方法讲清楚，免得月底才发现额度没了。

2.1 先备好三样东西：终端、项目、能用的账号

终端随便哪个都行。项目我建议用你熟悉的真实项目，后面几节的练习都在里面做。账号这一项最容易踩空，先看清楚。

官方的说法很干脆：免费的 claude.ai 套餐不含 Claude Code。你需要下面三种之一：

• Pro、Max、Team、Enterprise 其中一种订阅。
• 一个 Claude Console 账号。
• 公司通过云厂商接入：
  • Amazon Bedrock。
  • Google Cloud 的 Agent Platform。
  • Microsoft Foundry。

系统要求如下：

• macOS 13.0 以上。
• Windows 10 1809 以上。
• Ubuntu 20.04 以上，或 Debian 10 以上。
• Alpine Linux 3.19 以上。
• 内存 4 GB 以上，x64 或 ARM64 处理器。

必须联网。所在的国家或地区，还要在 Anthropic 的支持名单里。

2.2 一条命令装好，不用先装 Node

官方推荐的是原生安装（Native Install）。一条命令，装完以后在后台自动更新。下面三行按你的系统选一行，命令逐字照抄。

curl -fsSL https://claude.ai/install.sh | bash

irm https://claude.ai/install.ps1 | iex

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

claude --version

Windows 上有两个细节。提示符显示 PS C:\ 是 PowerShell，只显示 C:\ 是 CMD，命令别用串。原生 Windows 推荐装 Git for Windows。这样 Claude Code 能用 Bash 工具。没装就改用 PowerShell。WSL 不需要。

想用别的装法也行，只是多半要自己更新。

Homebrew 有两个 cask。claude-code 跟稳定通道，通常晚大约一周，会跳过出过大问题的版本。claude-code@latest 发布即到。Linux 发行版还可以用 apt、dnf、apk，细节看官方 setup 页。

原生安装的更新不用你管，想立刻更新就跑 claude update。想改跟稳定通道，在 /config 里改 Auto-update channel。或者在 settings.json 里写：

{
  "autoUpdatesChannel": "stable"
}

默认是 "latest"。后面几节会用到不少新版本才有的功能，我的建议是保持默认。

2.3 第一次启动：在项目目录里敲 claude，登录一次就够

官方 quickstart 现在是 7 步。装好是第 1 步，第一次启动会话是第 2 步，登录就在这一步里完成。旧教程里登录单列一步，现在合并了。

cd /path/to/your/project   # 换成你自己的项目路径
claude

凭据存在本机，之后不用再登。macOS 存进加密的钥匙串，Linux 和 Windows 存在用户目录下的 .claude/.credentials.json。换账号或重新授权，在会话里输入 /login。退出登录输入 /logout，它还会重置首次启动状态，下次 claude 会把登录和设置重走一遍。

浏览器没弹出来，按 c 复制登录链接，自己粘进浏览器。浏览器没有跳回来，而是显示一串登录码，就把码粘贴到终端的 Paste code here if prompted 提示处。WSL2、SSH、容器里最常见，因为浏览器开在另一台机器上，够不到本机的回调服务。

2.4 装不上、登不上，按报错对号入座

先给一个起手式。claude doctor 不用开会话，只读地打印安装健康度、设置文件错误和修复建议。出任何怪事，我建议先跑它。

安装阶段的报错，对照下表。

第一行最常见，修法是两行。zsh 是 macOS 的默认 shell，写进 ~/.zshrc。

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc   # 这行是关键：把安装目录加进 PATH
source ~/.zshrc

Windows 上 claude.exe 在 %USERPROFILE%\.local\bin 下，加进用户 PATH 后同样要开新终端。还有个容易忽略的坑：只装了 VS Code 扩展的人，磁盘上没有 ~/.local/bin/claude。扩展自带一份私有的 CLI，不放进 PATH。要在终端里用，得另跑一遍安装命令。

连通性怎么测？这条命令返回 200 就说明网络没问题。

curl -sI https://downloads.claude.ai/claude-code-releases/latest

登录阶段的报错，对照这几条。

• OAuth error: Invalid code：登录码过期，或复制时被截断。重试，浏览器一打开就尽快完成。远程会话里浏览器可能开在错的机器上，把终端里的链接复制到本机浏览器。
• 登录后 403 Forbidden：Pro 或 Max 用户去 claude.ai/settings 看订阅是否有效。Console 用户确认账号有「Claude Code」或「Developer」角色。角色由管理员分配。公司代理也可能干扰请求。
• 订阅有效，却报 This organization has been disabled。官方的判断是，ANTHROPIC_API_KEY 环境变量盖住了订阅。常见于上一个项目或上一家公司，留在 shell 配置里的旧 key。
• 隔一阵又让你登录：登录令牌过期了，跑 /login。频繁发生就检查系统时钟，令牌校验依赖准确的时间。macOS 钥匙串被锁也会存不进凭据，claude doctor 能查出来。

第三条的解法是三步，永久生效还要去 ~/.zshrc、~/.bashrc 或 ~/.profile 里删掉那行 export。

unset ANTHROPIC_API_KEY   # 当前终端先取消
claude
# 进会话后输入 /status，确认用的是订阅账号

登录问题找不到原因时，用重置法。输入 /logout 彻底退出，关掉 Claude Code，再重新 claude 走一遍授权。官方说这能解决大多数情况。

2.5 账单怎么算：订阅是包月，API 是计量

先记住一句话。官方的说法是，Claude Code 按 API token 的消耗计费。订阅只是把一定用量打包进月费，超出限额就要等重置，或者另买用量。API 账号没有这层打包，用多少付多少。

订阅价格只用官方价格页的数字（核对于 2026-10-13）。

重点看 Max 的「倍数」（Team Premium 的倍数见 §12）。各档具体能用多少，价格页只给倍数，没有 token 数或消息数，官方文档也未说明。所以你没法提前算出一个月够不够，我的建议是先用起来，再看 /usage 的实测。另外，价格页除 Enterprise 外只标「$」，没写币种，不含税，方案可能调整。下单前以页面为准。

怎么看自己用了多少？输入 /usage。

• 订阅用户看套餐用量条，以及「归因」。它写明最近的用量里，多少份额来自哪些 Skill、子智能体、插件和 MCP 服务器。占到 10% 的行为也会标出来，比如长上下文、缓存未命中。按 d 或 w，在最近 24 小时和 7 天之间切换。
• API 用户看顶部的 Session 块：本次会话的 token 统计和美元数。这个数是本地按标准牌价估算的，可能和真实账单有出入。权威数字看 Console 的 Usage 页。

订阅用户注意，Session 块里的美元数对你的账单没意义，别拿它当预算。另外，数据来自本机的会话历史，别的设备和 claude.ai 网页上的用量不在里面。

额度用完了怎么办？输入 /usage-credits，前提是用 claude.ai 订阅登录，API key 登录不能用。Pro 或 Max 用户会被带到 claude.ai 的 Settings > Usage。在那里可以开关 usage credits，设月消费上限。Team 和 Enterprise 成员没有账务权限的话，它会发请求给管理员。

再给一个参考量级。官方给了企业部署的平均数据。每位开发者每个活跃日约 $13，每月 $150 到 250。90% 的用户每个活跃日低于 $30。这是企业部署的统计，估量级可以，别当成自己的账单。

2.6 选模型：默认是 Opus 5.5，随时用 /model 换

这里有一处和旧教程不一样。从 v2.1.280（9 月 22 日）起，默认模型都是 Opus 5.5。适用 Pro、Max、Team、Enterprise 和 Anthropic API。在此之前，Pro 和 Team Standard 默认的是 Sonnet 5。你在旧文章里看到「Pro 默认 Sonnet」，说的是那个旧版本。

云厂商接入的默认模型是这样：

• Bedrock 与 Claude Platform on AWS：默认也是 Opus 5.5。
• Google Cloud Agent Platform：默认也是 Opus 5.5。
• Microsoft Foundry 例外，默认是 Sonnet 4.5。

你不用背完整的模型名，用别名就行。

有两点要提醒。第一，新模型对 Claude Code 版本有下限：

• Opus 5.5 需要 v2.1.280。
• Sonnet 5.5 需要 v2.1.284。
• Haiku 5.5 需要 v2.1.293。

选不到就先 claude update。第二，别名会随时间指向更新的版本，要钉死某个版本，用完整模型名或对应的环境变量。

怎么切？官方给了几种方式，优先级从高到低是下面这样。

• 会话中：/model <别名或模型名> 立即切换，不带参数则打开选择器。
• 启动时：claude --model <别名或模型名>。
• 环境变量：ANTHROPIC_MODEL。
• 设置文件：settings.json 里的 model 字段。
• 新会话默认值：ANTHROPIC_DEFAULT_MODEL，需要 v2.1.236 以上。

claude --model opus      # 启动时指定
# 进会话后：
# /model sonnet          # 中途换到 sonnet

在选择器里，按 Enter 是切换并存为默认，按 s 只对这个会话生效。直接敲 /model sonnet 等同于按 Enter，也会存成默认。想知道当前用的是哪个，看 /status 或状态行（§04）。恢复旧会话时沿用当时保存的模型，不看你现在的设置。

顺带说两个旋钮。/effort 调整思考深度，低档更快更省，高档更深更贵，档位名称随模型不同，菜单里能看到。/fast 切换 fast mode，它不是另一个模型，是同一个 Opus 换了更快更贵的配置。Opus 5.5 上是每百万 token $8 / $40。Opus 5 和 4.8 是 $10 / $50。Sonnet 和 Haiku 不支持。订阅用户用它只能走 usage credits，不含在订阅限额里。

我的建议是，头一周别折腾，用默认值。觉得额度掉得太快，或者手上是琐碎活，再 /model sonnet。想试先规划后执行的分工，我会选 opusplan。

2.7 同一句话，在长会话里更贵

这一节要埋一颗种子。你可能以为额度只取决于问了几个问题，其实不是。Claude Code 每发一次请求，都会把整段对话一起发出去。会话越长，每个问题背后带的东西越多。

有提示缓存兜着，重复读历史按便宜的缓存价算。但缓存有保质期。订阅用户在套餐额度内是一小时，API key 默认五分钟。动用 usage credits 后，订阅也降为五分钟，细节见 §04。你离开去吃顿饭，回来的第一条消息会整段重新处理一遍。所以一个开了一整天的会话，哪怕只问一行字，也要消耗整段对话的用量。

这条线怎么管，是 §04 的主题。我先给判断：省额度的大头在别让会话无限变长，选哪个模型排在后面。

2.8 这一节的结论

装 Claude Code 就是一条命令，装完开新终端验证。登录在第一次 claude 时顺手完成，凭据存本机。装不上、登不上，多数是 PATH、shell 用串、网络或 ANTHROPIC_API_KEY 这几样，先跑 claude doctor。

账单要分清订阅和 API。订阅是包月加限额，具体额度官方没给数字。默认模型现在是 Opus 5.5，想省就换 sonnet。我认为这一节最该带走的是一句话：额度的消耗速度，取决于上下文有多长。

下一节，我们在真实项目里布置第一个任务，把「探索、规划、编码、提交」这套日常工作流走一遍。

§03 先探索再规划，再动手，每个任务都配一个验证方法

Your First Task and the Daily Workflow

从一个只读的问题开始，走通「探索、规划、编码、提交」的日常循环。再把最常用的十几个命令、走偏时的回退办法，以及让它自己验证的写法一次讲清。

3.1 第一个任务：先问，再改一行，再看 diff

第一次进项目，我的建议是别急着让它写功能。先问几个只读的问题，看它读得对不对。读错了，后面的活全是白干。

这个项目是做什么的？
入口文件在哪？
解释一下目录结构。

在主文件里加一个 hello world 函数

/diff

用一句清楚的说明提交我的改动

这四步正好对应官方 quickstart 第 3 到第 5 步。后面第 6、7 步是修 bug、重构、写测试、更新文档，换个说法就能用，不用另学。

3.2 探索、规划、编码、提交：官方推荐的四步循环

让它直接写代码，有时会写出一个解决错问题的方案。官方的办法是把「想清楚」和「动手」拆开，我认为这也是新手最容易省掉、又最该补上的一步。

探索和规划都在 Plan 模式里做

Plan 模式下，Claude 读文件、跑命令做探索、写计划，但不改你的源码。你批准计划之前，编辑一直被拦着。进入的方法有三种。

• 按 Shift+Tab，直到输入框下方显示 plan mode on
• 在提示词前加 /plan，比如 /plan 修一下登录 bug
• 启动时指定：claude --permission-mode plan

（Plan 模式）
读一下 /src/auth，搞清楚我们怎么处理会话和登录。
再看看密钥类的环境变量是怎么管的。

我想加 Google OAuth。哪些文件要改？会话流程是什么？给我一份计划。

计划出来后，按 Ctrl+G 可以在你的文本编辑器里直接改。我认为计划写偏了就自己动手删改，比对着聊天框反复纠正快得多。

批准计划，进入编码

计划就绪，Claude 会问你怎么继续。选项的措辞会随版本略有变化，大意是三种。

• Yes, and use auto mode：批准，并切到 auto 模式开干。auto 不可用时，这一项写作 Yes, auto-accept edits。
• Yes, manually approve edits：批准，但每处编辑都由你逐条过目。
• No, keep planning：留在 Plan 模式，告诉它哪里要改。

批准以后，会话退出 Plan 模式，Claude 开始动手。别忘了把验证方法一起交代，见 3.4。

按你的计划实现 OAuth 流程。给回调处理函数写测试，
跑完整套测试，有失败就修。

提交，顺手开 PR

用一句清楚的说明提交，然后开一个 PR

用 gh 或 glab 创建 PR 后，会话会和 PR 关联。以后想找回这个会话，运行 claude --from-pr 1234，换成你自己的 PR 号。官方的建议是，提交前自己审一遍 PR，并让 Claude 标出潜在的风险点。

3.3 提示词写具体，是少改几遍的捷径

Claude 能推断意图，但读不了你的心。官方总结了四种把提示词写具体的办法。下表每行的「具体说法」，是我按这四种思路改写的中文示例，你照着换成自己项目里的文件名就行。

重点看最后一列。我认为它们的共同点是少让 Claude 猜。猜错一次，你就要多一轮纠正，纠正的话还会留在上下文里（§04）。

给它材料也有几种顺手的方式。

• 用 @ 引用文件：解释一下 @src/utils/auth.js 的逻辑。文件内容会被带进对话。前提是没超过 Read 工具的上限。上限默认是 25,000 token，超过 256KB 的文本文件不会被带入。
• @ 引用目录：给的是文件清单，不是内容。
• 粘贴图片：复制粘贴或拖进输入框。快捷键是 Ctrl+V，iTerm2 用 Cmd+V，Windows 和 WSL 用 Alt+V。
• 管道：cat error.log | claude -p "解释这个报错"，直接把文件内容送进去。
• 感叹号：在行首输入 ! npm test，命令输出会进入对话，Claude 会接着回应，不用再补一句话。

模糊的提示词也有用处。你在探索，不知道该问什么时，一句「这个文件你会改进哪里」，可能挖出你没想到的东西。

3.4 给它一个验证方法，是这一节最值钱的一条

§01 讲过，Claude 觉得「看起来完成」就会停。没有可跑的检查，你就成了验证环节。我把这条放在这一节最前面，核心就一句话：每个任务，都附一个能得出通过或失败的检查。

表里最后一行的「根因」两个字很关键。没有它，Claude 可能给你一个让报错消失的补丁，而没有真正修好。

检查本身可以是测试套件、构建的退出码、linter、对比输出和样本的脚本，或者浏览器截图。再进一步，官方还列了几档「卡得多紧」的做法，后面几节会展开。

• 写在一条提示词里：让它跑检查并迭代，上表就是这种。
• 贯穿整个会话：用 /goal 设一个条件，由另一个评估器每轮复查，没达成就继续干。
• 当作确定性的闸门：用 Stop 钩子把检查跑成脚本，没过就不让这一轮结束，见 §09。
• 找第二个意见：让一个验证用的子智能体来挑错，见 §10。

还有一个习惯值得养。让它出示证据，而不是只说「搞定了」。贴出测试输出、跑过的命令和返回值、结果截图。看证据比你自己重跑一遍快，也适合你没盯着的会话。

3.5 十几个斜杠命令，够你过完第一周

输入 / 能看到所有可用的命令和 Skill，输入 / 加几个字母可以过滤。命令只在消息开头被识别。Claude 正在回答时你发命令，它会排队等这一轮结束，但 /status、/usage 这类会立刻执行。

这十五个里，我认为日常最该先背熟的是四个：/clear、/rewind、/plan、/diff。前两个管「出错怎么办」，后两个管「动手前后怎么看」。

再记几个键盘上的动作。

Claude 干活的时候，你照样可以打字发消息，按 Enter 会让消息排队。如果它还在调用工具，消息会在这些调用结束后送到它那里，用不着等整轮结束。

3.6 走偏了怎么办：Esc、/rewind、/clear 三层退路

官方有一句很值得记的话：对话是持久的，也是可逆的。走偏了不用硬扛，有三层退路，从轻到重。

• Esc：它刚开始往错的方向走，立刻打断，上下文保留，你说一句新方向。
• /rewind：已经改了一堆文件，回到某个检查点。
• /clear：对话本身被失败的尝试污染了，推倒重来。

检查点：每条提示词一个存档

每次你发一条开启新一轮的提示词，Claude Code 都会先拍一份代码快照。这份快照就是检查点。每个会话保留最近 100 个检查点的文件快照。检查点跟对话一起存，所以你关了终端、过几天恢复会话，照样能 /rewind。不过快照不会永远留着。默认在会话最后一次存快照约 30 天后被清理，回退到已清理的检查点可能失败。想留得更久，调 cleanupPeriodDays。

输入 /rewind，或者在输入框为空时连按两次 Esc，打开回退菜单。菜单列出你发过的每条提示词，选一个点，再选动作。

选了恢复对话，或者「从这里总结」之后，那条原始提示词会被放回输入框，你可以改一改再发。有了这个，你可以放心让它试一个有风险的做法，不行就退回去换一条路。

所以我的建议是，重要的节点用 git 提交，细碎的试错交给检查点。两者分工，各管一层。

改了两遍还不对，就别改第三遍

官方给了一个具体的线。同一个问题在一个会话里纠正超过两次，说明上下文里已经堆满了失败的尝试。这时候运行 /clear，带着你学到的东西重写一条更具体的提示词。一个干净的会话加更好的提示词，几乎总比一个攒了一堆纠正的长会话强。为什么，下一节细讲。

3.7 隔天接着干：别重新交代

Claude Code 把每次对话存在本地。任务跨了几天，接着干，不用重讲。

claude --continue   # 恢复当前目录里最近的那次会话
claude --resume     # 从列表里挑一个
# 会话里也可以输入 /resume

当前目录里还没有会话时，--continue 会打印 No conversation found to continue 然后退出。给会话起个好名字，比如 oauth-migration，用 /rename。把会话当分支用，每条工作线有自己的上下文，这是官方的建议。

想同时开两个任务互不干扰，用 worktree：claude --worktree feature-auth。仓库里至少要有一个提交。并行和隔离的做法放在 §10 讲。

3.8 这一节的结论

日常循环是四步：探索、规划、编码、提交。小改动跳过规划，大改动先进 Plan 模式。每个任务带上验证方法，让它自己判断对错。走偏了先 Esc，不行再 /rewind，还不行就 /clear。

你可能已经注意到，这一节反复出现「上下文被污染」「腾上下文」这样的话。我认为这是全书最该先吃透的一件事。

下一节，我们把它讲透。上下文窗口里到底装了什么？会话怎么一点点被填满？什么时候该清、该压缩、该开新会话？

§04 上下文是唯一稀缺的资源，先看清它被什么占着

Context Is the Only Scarce Resource

这是全书的主线节。先讲清上下文窗口里装了什么，一个任务怎么把它填满。再讲三种收拾办法、压缩之后丢什么、缓存为什么影响账单，以及怎么盯着它。

4.1 上下文是一张有限的工作台，桌上每样东西都在收费

官方《最佳实践》开篇就立了一条约束。Claude 的上下文窗口填得很快，而且随着填充，表现会变差。紧接着它给出结论：上下文窗口是最重要的资源。

窗口里装的是什么？整段对话、每个读过的文件、每条命令的输出，都在里面。还有 CLAUDE.md、自动记忆、已加载的 Skill 和系统指令。官方说，一次调试或一次代码库探索，就可能产生并消耗几万个 token。

这个约束牵着三件事一起走。

• 表现：窗口快满时，Claude 可能「忘掉」早先的指令，或者犯更多错误。
• 费用：Claude Code 每次请求都带上整段对话，token 成本随上下文变大而增长。
• 容量：接近上限时自动压缩，对话早期的详细指令可能丢失。

把它想成一张工作台。台面大小有限，这是第一层。开工前，台上已经摆好工具和说明书，这是第二层，对应启动时的加载。你每读一个文件、每跑一条命令，就往台上再堆一份材料，台面越满，越容易拿错，这是第三层。

收拾桌子有两种办法：整理成一页摘要，或者清空换一张新的。还有第三种：把要翻一大堆资料的活，交给隔壁房间的同事，只让他递一页结论回来。这一节讲的，就是这四件事。

台面到底多大？别记死数字。官方文档的说法是，下面这些模型默认就是 100 万 token 的窗口：

• Fable 系列。
• Sonnet 5 及以后。
• Haiku 5.5。
• Opus 4.7 及以后。

Opus 4.6 和 Sonnet 4.6 要用 [1m] 变体才有。想把窗口固定在 20 万，设环境变量 CLAUDE_CODE_DISABLE_1M_CONTEXT=1。你这个会话的实际窗口，用 /context 或状态行看。

4.2 开口之前，桌上已经摆好了东西

你还没打一个字，上下文里就已经有内容了。官方有一个交互演示，把一次会话里每一步的 token 数摆了出来。下表是演示里的启动部分。

七项加起来约 7,850 token，在演示用的 20 万窗口里不到 4%。重点看最后一行。系统提示你动不了，但演示里最大的一项，是你自己写的 CLAUDE.md。所以我会把「CLAUDE.md 有没有写胖」排在启动体检的第一位。

这里要说清楚：这些是官方演示里的示意值，不是你机器上的实测。输出样式、--append-system-prompt 也会往启动内容里加东西。项目里没有 CLAUDE.md 时，AGENTS.md 会顶替它的位置（见 §05）。你的真实占用，用 /context 看。

还有一条别忘了。每个新会话都从一个全新的窗口开始，上面这些在每次开新会话时重新加载一遍。

4.3 修一个小 bug，读文件占了近六成新增内容

演示接着往下走。你说「修复刷新 token 后返回 401 的 bug」，Claude 去读代码、改代码、跑测试。

这一轮新增约 11,800，加上启动的 7,850，会话涨到 19,685。重点看第一行。四个文件读下来 6,900，占新增部分的 58%。读文件加上命令输出（6,900 加 600 加 1,200），合计 8,700。Claude 自己写的分析、编辑和总结，加起来才 2,200。

最大的一块，你在终端里只看到一行字。我认为这是理解上下文最关键的一点，我的读法是先管「读」，再管「写」：涨得最快的是「读」，而「读」最不显眼。这也是为什么你需要 /context 这样的工具，肉眼看不到的才是大头。

还有几条进入上下文的路，容易被忽略。

• 路径规则：.claude/rules/ 里带 paths: 的规则，在 Claude 读到匹配文件时才加载，加载后留在对话里。
• 钩子：PostToolUse 钩子只有通过 hookSpecificOutput.additionalContext 返回的内容才进入上下文。普通的 stdout（退出码 0）只写进调试日志。
• 感叹号命令：你输入的 ! git status，命令和输出都会进入上下文。
• @ 引用：文件内容会被带入（限额见 §03）。引用目录只给文件清单。

官方在失败模式里点名过一种：没有范围的「调查一下」。Claude 会读上百个文件，把窗口填满。你给的范围越窄，它读得越少。

4.4 /clear、/compact、/rewind：三种收拾桌子的办法

我的结论是，/clear 的使用频率，应该比你以为的高得多。带重点的压缩，写法是这样。

/compact focus on the auth bug fix

你不手动压，Claude Code 也会在接近上限时自动压。官方的描述是，它先清掉较早的工具输出，再在必要时总结对话。你的请求和关键代码片段会保留，对话早期的详细指令可能丢失。1M 窗口的模型，默认大约在 967K token 处才压缩。想早点压，用 /autocompact 设一个触发点。

/autocompact 500k    # 窗口填到 50 万 token 就自动压缩
/autocompact auto    # 恢复为按模型调好的默认值

接受的范围是 10 万到 100 万 token。具体设多少，官方没有给推荐值，我也不给一个拍脑袋的数。

想让每次压缩都保住某些东西，在项目根的 CLAUDE.md 里写一段。

# Compact instructions

When you are using compact, please focus on test output and code changes

有一种极端情况要知道。单个文件或工具输出大到压缩完马上又塞满。Claude Code 试几次后会停止自动压缩并报错，而不是无限循环。遇到这个报错，问题出在那个超大的输入上，不是压缩本身。

五种办法怎么选，我给一份判断规则。

• 换到不相关的任务：/clear。
• 同一个任务，对话很长：在一个段落收尾时 /compact，写明要保留什么。
• 同一个问题改了两遍还不对：/clear，把学到的写进更具体的提示词（§03）。
• 想整段放弃：/rewind。
• 只想问个小问题：/btw。

4.5 压缩之后，哪些规则会丢

压缩不是无损的。它保留的是这些：

• 你的请求和意图。
• 关键技术概念。
• 看过和改过的文件，及重要代码片段。
• 错误和修法。
• 待办和当前进度。

它丢掉的是逐字的对话、完整的工具输出和中间推理。Claude 之后还能提到这些工作，但拿不到原文。

不同内容的下场不一样，取决于它当初是怎么加载的。

读完这张表，我得出一条规则。必须长期有效的东西，别放在对话里，也别放在会被压掉的位置。官方的说法是，持久的规则放进 CLAUDE.md，不要依赖对话历史。对话里你说过的「以后都用 pnpm」，压缩几次之后就可能没了。

4.6 缓存：中途换模型和歇一小时，为什么会变贵

你在 §02 见过一个说法，会话越长，同一句话越贵。原因藏在提示缓存里。

模型在两次请求之间什么都不记得。所以 Claude Code 每次都把完整上下文重发一遍，包括：

• 系统提示。
• 项目上下文。
• 每条历史消息和工具结果。
• 你的新消息。

好在每次请求的开头，和上一次几乎一模一样。API 按前缀去匹配最近处理过的内容。匹配上的部分按缓存价算，只有变化的部分全价处理。

匹配是精确的。前缀里任何位置变了，它后面的全部内容都要重算。所以 Claude Code 把请求排成三层，越不爱变的越靠前。

对话层变了，上面两层仍然命中缓存。系统提示变了，后面全部作废。下面是一张对照，哪些动作会让缓存失效，哪些不会。

失效的代价是什么？下一条回复变慢、变贵一次，之后新的前缀被缓存，恢复正常。所以我的建议很具体：会话一开始就把模型和 effort 选好，把 /compact 留给任务之间的自然断点。中途少做改动，命中率就高。这也是官方文档里的建议。

缓存还有保质期。每次命中缓存都会重置计时，你一直在干活，缓存就一直热着。歇得够久，下一条消息要把整段上下文重新处理一遍。这就是歇一会儿回来，第一条回复特别慢的原因。保质期不是定值。订阅账号在套餐额度内是一小时，开始动用 usage credits 后降为五分钟。用 API key 或云厂商时，默认五分钟。

Pro 和 Max 用户还有一个补救。恢复会话时有两个条件：超过约一小时没动，又超过 100,000 token。满足时 Claude Code 会弹出对话框，让你选「从摘要恢复」「原样恢复」或者「不再询问」。从摘要恢复等于立刻跑一次 /compact，之后每次请求带的是摘要而不是全部历史。代价是摘要没写进去的东西，Claude 就不记得了。

4.7 把大块读取挪出主上下文

清理是事后的办法。更好的办法是让大块的东西一开始就不进来。下表是全书地图里「分流」这一类的汇总，细节都在后面的章节。

子智能体值得多说一句，因为它最直观，我建议把它当成探索类任务的默认选项。官方演示里，子智能体为了研究会话超时，读了 6,100 token 的文件。回到主会话的只有一份约 420 token 的结果，外加一小段元数据。元数据含 token 数和耗时。主上下文省下了五千多。

它不是免费午餐。子智能体有自己的上下文。它也会加载自己的 CLAUDE.md 副本，并带上同样的 MCP 和 Skill。只是不带你的对话历史，也不带主会话的自动记忆。内置的 Explore 和 Plan 子智能体为了更小的上下文，会跳过 CLAUDE.md。官方也提醒过：子智能体自己的请求，照样消耗你的用量。它省的是主上下文，不是总用量。

4.8 盯着用量：/context、状态行、/usage

管理一个看不见的东西，第一步是让它可见。三个工具各管一块。

/context：看现在装了什么

输入 /context，得到一张彩色网格，按类别拆分当前用量。网格附带优化建议，比如哪些工具占得多、记忆是否膨胀、容量是否告急。它还会列出加载了哪些 CLAUDE.md 和自动记忆文件。输入 /context all 展开完整明细。想编辑那些文件，输入 /memory。

状态行：一直看着用量

状态行是终端底部一条可定制的栏。它运行你配置的 shell 脚本。Claude Code 把会话数据以 JSON 送给它。上下文百分比就在里面。最省事的做法是让 Claude 替你写。

/statusline show model name and context percentage with a progress bar

也可以手动写进 settings.json。下面是官方的最小例子，用 jq 取出模型名和上下文百分比。

{
  "statusLine": {
    "type": "command",
    "command": "jq -r '\"[\\(.model.display_name)] \\(.context_window.used_percentage // 0)% context\"'"
  }
}

两个细节。第一，context_window.context_window_size 告诉你当前窗口是多大。没有扩展上下文的是 20 万，有的是 100 万。所以百分比永远是相对你这个窗口的。第二，状态行读的是最近一次 API 响应的计数。/context 会再加上之后新增消息的估算。所以 /context 有时读数更高，这不是 bug。

Pro 和 Max 订阅用户还能把限额放进状态行。脚本里能读到 5 小时窗口和 7 天窗口的已用百分比。字段分别是 rate_limits.five_hour.used_percentage 和 rate_limits.seven_day.used_percentage，第一次 API 响应之后才会出现。

/usage：看额度是被什么吃的

§02 讲过 /usage。订阅用户在这里能看到用量的归因。哪些 Skill、子智能体、插件和 MCP 服务器占了多少份额，一目了然。占到 10% 以上的行为会被标出来。常见的就是长上下文和缓存未命中，每条还附一个降低的建议。这是上下文管理的结果检验：你清得勤不勤，这里看得出来。

再坦白说一件事。官方没有给出「用到百分之几就该清」的数字，所以我也不编一个。我的建议是按任务边界清，不按百分比清。一个任务做完，换下一个，就 /clear。

4.9 五个坏习惯，都是在糟蹋上下文

官方在《最佳实践》里列了几种常见的失败模式。把它们翻成上下文的语言看，每一种都对应桌面上多出来的一堆废料。

官方有一句话值得单独拎出来。一个干净的会话加更好的提示词，几乎总比一个攒了一堆纠正的长会话强。这是第二行的依据，也是 §03 里「改两遍不对就清」的依据。

有一点得公平地补上。官方也说，这些做法是起点，不是铁律。你深陷一个复杂问题、历史本身有价值的时候，就该让上下文积累。我认为这类取舍的标准只有一个：留下的东西，下一步用得上吗。用得上就留，用不上就清。

4.10 这一节的结论

上下文是工作台，台面有限，而且每样东西都在收费：既收表现的费，也收 token 的费。这一节给的是三个动作。

• 看见：用 /context 和状态行，知道桌上有什么。读文件和命令输出才是大头，它们在终端里最不显眼。
• 回收：任务之间 /clear，同一任务里在自然断点 /compact，走进死胡同就 /rewind。记住，压缩之后带 paths: 的规则要等再次匹配到文件才回来。必须长期有效的，放根 CLAUDE.md。
• 分流：探索交给子智能体，预处理交给钩子，专项说明交给 Skill，别让它们一开始就占着台面。

下一节讲 CLAUDE.md 和记忆。它是启动时上下文里你唯一能完全决定的那一块，写好了每次省口舌，写坏了每次都在交税。

§05 要反复交代的话写进 CLAUDE.md，每一行都得配得上它占的位置

CLAUDE.md and Memory: Stop Re-Explaining Everything

每个会话都从空白开始。这一节讲怎样把要反复交代的话固化下来。放在哪一层，哪些不该放。以及 Claude 自己记的笔记在哪里、怎么管。

5.1 每个会话都从空白开始，两套机制替你记住

设想你昨天告诉它「测试用 pnpm 跑」，今天新开一个会话，它不知道。官方的说法很直白：每个会话都从一个全新的上下文窗口开始。跨会话留下东西的，只有两套机制。

我的读法是先看「何时加载」这一行。两者都在每次会话开头进入上下文，所以它们是 §04 讲的「启动时就摆在桌上」的东西。写得越胖，每个会话都在多交一笔税。

还有一条必须先说清。官方的说法是，Claude 把这两者当作上下文，而不是强制执行的配置。CLAUDE.md 的内容是作为一条用户消息，跟在系统提示之后送给模型的。它不是系统提示的一部分。它会读，会尽量照做，但不保证严格遵守，尤其是含糊或互相矛盾的指令。

想无论 Claude 怎么判断都拦住某个动作，用 PreToolUse 钩子（§09）。或者用权限规则（§06）。

5.2 往 CLAUDE.md 里加一行之前，先问四个问题

官方的说法是，把 CLAUDE.md 当成写下你本来要反复交代的东西的地方。出现下面四种情况，就该加一行。

• Claude 第二次犯同一个错。
• 代码评审抓到了一件 Claude 本该知道的事。
• 你在对话里敲的纠正，和上个会话里敲的一模一样。
• 一个新同事要上手，也需要这条背景。

加什么，不加什么，官方给了一张清单。

每一行，问一句：删掉它，Claude 会犯错吗？不会，就删。这是官方给的检验标准。我认为它比任何长篇规则都管用，因为它直接对着 §04 的约束：每一行都在占位置。我自己的取舍原则只有一条，宁可少写一行，也不留一行可有可无的。

官方还给了几条判断依据，用来看文件是不是写胖了。

• 某条规则明明写了，Claude 还是不照做：文件多半太长，规则被淹没了。
• Claude 反复问 CLAUDE.md 里已经有答案的问题：措辞可能有歧义。
• 某一条总被跳过：只给那一行加强调，比如「IMPORTANT」。每行都强调，等于没有强调。

写法上，把指令写到能验证的程度。

好好格式化代码。
测试一下你的改动。
保持文件井井有条。

缩进用 2 个空格。
提交前运行 npm test。
API 处理函数放在 src/api/handlers/。

篇幅上，官方的目标是每个 CLAUDE.md 不超过 200 行。更长的文件消耗更多上下文，也会降低遵守率。超过时，启动和 /status 里都会有警告。

一份短的项目 CLAUDE.md 大概长这样，命令换成你自己项目里的。

# 构建与测试
- 构建：`npm run build`
- 只跑单个测试：`npm test -- path/to/file.test.ts`，别跑整套
- 改完一批代码后先跑 `npm run typecheck`

# 代码风格
- 用 ES modules（import/export），不用 CommonJS
- 缩进 2 个空格

# 约定
- 分支名用 feature/xxx 或 fix/xxx
- API 处理函数放在 `src/api/handlers/`

不想从空白开始，输入 /init。Claude 会分析代码库，生成一份带构建命令、测试说明和项目约定的起始文件。已有 CLAUDE.md 时，它只给改进建议，不覆盖。之后你只补它自己发现不了的东西。

文件用久了，难免过时和互相矛盾。两条出路。

• /doctor：建议删掉 Claude 能从代码里推出来的内容，比如目录布局、依赖清单、架构概述。保留踩坑记录和与默认值不同的约定。需要 v2.1.206 以上。
• /doctor prompt-audit：检查指令文件有没有过时或冲突的内容，比如为旧模型写的指令、指向不存在文件的引用。它出一份带建议的报告，你不点头它不改。需要 v2.1.283 以上。

把 CLAUDE.md 当代码对待：出问题时回头看，定期修剪，改完观察行为有没有变。把它检入 git，团队一起维护，这个文件会越用越值钱。

5.3 CLAUDE.md 放哪里：四层位置，拼接而不是覆盖

表是按加载顺序排的，从最宽到最具体。项目指令出现在用户指令之后，离你越近的越靠后读。

加载有几条规则，我一次说完。

• 启动时，从当前工作目录一路往上。每一级目录里的 CLAUDE.md 和 CLAUDE.local.md 都会加载。在 foo/bar/ 启动，就读 foo/bar/CLAUDE.md、foo/CLAUDE.md，以及它们旁边的 CLAUDE.local.md。
• 它们是拼接进上下文的，不互相覆盖。顺序从文件系统根目录排到工作目录。同一目录里，CLAUDE.local.md 排在 CLAUDE.md 之后。
• 工作目录之下的子目录里的 CLAUDE.md，启动时不读。等到 Claude 读、写或改那个子目录里的文件，才加载。而且只加载一次。
• 用 --add-dir 加进来的目录，默认不加载它们的 CLAUDE.md。要加载，启动时带上环境变量 CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1。
• 两条指令互相矛盾时，Claude 可能随便挑一条。用户层规则和项目层规则冲突时也一样，所以要保持一致。

怎么确认它真的加载了？运行 /context，看 Memory files 下面的列表。子目录里的 CLAUDE.md 不会出现在这个列表里，因为它是按需加载的。加载时终端里会出现一行带路径的 Loaded。

CLAUDE.md 里还能用 @路径 导入别的文件，比如 @README 或 @docs/git-instructions.md。相对路径以包含导入的那个文件为基准，最多嵌套四层，路径含空格要在空格前加反斜杠。想提到路径又不导入，用反引号括起来。第一次遇到工作目录之外的导入，会弹出审批对话框。

一个小技巧：块级的 HTML 注释（<!-- 给维护者的说明 -->）在内容注入前会被剥掉。给人看的备注写在这里，不花上下文。代码块里的注释会保留。

5.4 AGENTS.md：v2.1.277 起，没有 CLAUDE.md 时直接读它

如果你的仓库已经给别的编码 Agent写好了 AGENTS.md，不用再复制一份。默认行为看下表。

判断「有没有 CLAUDE.md」时，算数的有：工作目录及以上的 CLAUDE.md、.claude/CLAUDE.md、CLAUDE.local.md。不算数、会和 AGENTS.md 一起加载的有三样：

• 你的 ~/.claude/CLAUDE.md。
• 组织托管的 CLAUDE.md。
• .claude/rules/ 里的规则。

读到了，交互会话里会看到一行类似 no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md 的提示。AGENTS.local.md 和 AGENTS.override.md 不读。.agents/ 目录下的东西也不读。

这里有一个很容易踩的坑，我建议你现在就去检查自己的项目有没有中招。你的项目靠 AGENTS.md 干活。你为了放私人指令，新建了一个 CLAUDE.local.md。结果 Claude 就不再读 AGENTS.md 了。因为 CLAUDE.local.md 算数。解法是改设置。

输入 /config，找到 Project instructions，有四个值。

有些会话读不到 AGENTS.md。此时 Project instructions 设置也不会出现。常见原因有三个：

• 版本早于 v2.1.277。
• 用 /plugin 关了负责读取它的内置插件。
• v2.1.281 之前，走 Bedrock 或关了遥测的部分会话。

遇到这些，在 CLAUDE.md 里写一行导入就行。

@AGENTS.md

## Claude Code 专用说明
- Claude 特有的指令写在导入下面

以前为了让它读 AGENTS.md 而做的变通，现在可以清理了。

• CLAUDE.md 里写着 @AGENTS.md 或是指向它的符号链接：留着没问题，不会读两遍。
• CLAUDE.md 里只用文字叫 Claude「去读 AGENTS.md」。它得自己决定打开，才看得到。删掉这个 CLAUDE.md，或换成 @AGENTS.md 导入。
• 用 SessionStart 钩子打印 AGENTS.md：删掉，否则内容会多出一份。

想确认它读到了没有，运行 /memory，在列表里找 AGENTS.md 的路径。v2.1.280 之前，/memory 和 /context 不列出直接读取的 AGENTS.md。那种版本就直接问 Claude，它的项目指令是什么。

5.5 按路径加载的规则：只在碰到那类文件时才占位置

项目一大，CLAUDE.md 里总有些规则只对一部分代码有用。官方给的办法是 .claude/rules/ 目录。把规则拆成一个主题一个文件，放进去。

your-project/
├── .claude/
│   ├── CLAUDE.md           # 主要的项目指令
│   └── rules/
│       ├── code-style.md   # 代码风格
│       ├── testing.md      # 测试约定
│       └── security.md     # 安全要求

没有 paths 前置字段（frontmatter）的规则，启动时就加载，优先级和 .claude/CLAUDE.md 相同。带 paths 的才是按路径加载的规则。

---
paths:
  - "src/api/**/*.ts"
---

# API 开发规则

- 所有接口必须校验输入
- 用统一的错误响应格式
- 写 OpenAPI 文档注释

这样一来，这条规则只在特定时刻才进入上下文。时刻是 Claude 对匹配的文件用 Read、Write 或 Edit 工具时。用 cat、head 这类按单文件读取的 Bash 命令查看匹配文件，也算。paths 是规则文件里 Claude Code 唯一读取的前置字段，别的字段会被忽略。

paths 用 glob 写法匹配。比如 **/*.ts 匹配任意目录下的 TypeScript 文件，src/**/* 匹配 src/ 下所有文件。可以写多条，也可以用花括号展开扩展名，比如 src/**/*.{ts,tsx}。

个人的规则放在 ~/.claude/rules/，对你机器上所有项目生效，加载时先于项目规则。两边冲突，Claude 可能选任何一边，所以我建议两边保持一致。

规则和 Skill 怎么分？规则是每个会话加载，或在匹配文件被打开时加载。只在特定任务才需要的指令，我认为该放 Skill 里，用到才加载（§07）。

5.6 自动记忆：Claude 给自己写的笔记

CLAUDE.md 是你写的。自动记忆是 Claude 根据你的纠正和偏好，自己记下来的。它会存四类笔记，类型写在记忆文件的前置字段 type 里。

• user：你的角色、专长、工作偏好。
• feedback：你给它的纠正，以及你认可的做法。
• project：进行中的工作、截止日期、从代码和 git 历史里推不出来的决定。
• reference：项目之外的信息在哪里，比如问题追踪器、仪表盘。

它不记能从代码库里推出来的东西，比如架构、文件路径、调试的修法。它也不记 CLAUDE.md 里已经有的。也不是每个会话都存，它自己判断这条信息以后用不用得上。

自动记忆在本地会话默认开着。要开关，在会话里输入 /memory 用里面的开关，它会把 autoMemoryEnabled 写进你的用户设置。只想对一个项目关掉，在项目设置里写 "autoMemoryEnabled": false。环境变量方式是 CLAUDE_CODE_DISABLE_AUTO_MEMORY=1。

它存在每个项目自己的目录里：

~/.claude/projects/<project>/memory/
├── MEMORY.md           # 索引，每条记忆一行，每个会话都加载
├── user_role.md        # 一条记忆
├── feedback_testing.md # 一条记忆
└── ...                 # Claude 创建的其他主题文件

目录路径从 git 仓库推出来，同一个仓库的所有 worktree 和子目录共用一份。它只在本机，不会跟着你换电脑。想改位置，在 settings.json 里设 autoMemoryDirectory。

加载上有一条硬规则，和上下文直接相关。每个会话开头，只读入 MEMORY.md 的前 200 行或前 25KB。先到哪个算哪个。超出的部分不加载。主题文件不在启动时读，Claude 需要时用普通文件工具按需去读。所以 MEMORY.md 要像索引一样短。超出的部分下次加载就丢了，Claude Code 会提醒它精简。

这个 200 行和 25KB 的上限只管 MEMORY.md。CLAUDE.md 最大 4 MiB 都会完整加载，更大的则整份跳过。但「能加载」不等于「该这么长」，短的文件遵守得更好。

你会在界面上看到两种提示，说明 Claude 正在写或读那个目录：

• Saved 2 memories：它在写。
• Recalled 2 memories：它在读。

这些笔记是纯 markdown，你可以随时看、改、删。输入 /memory 能浏览和打开它们。它们不受会话清理的影响，只要你和 Claude 不删，就一直在。

还有两个边界。主会话的自动记忆不会加载进子智能体，子智能体可以有自己单独的记忆目录，见 §10。自动记忆只在本机，团队要共享的东西，写进检入仓库的 CLAUDE.md。

5.7 .claude 目录里还有什么：一张找文件的地图

CLAUDE.md 只是 .claude/ 目录里的一个文件。项目级的放在仓库的 .claude/ 下，全局的放在 ~/.claude/ 下，对所有项目生效。官方给了一张「想改什么，就改哪个文件」的对照。

两点要记住。第一，官方现在说，commands/ 和 skills/ 是同一套机制，新工作流用 Skills，同样用 /名字 调用，还能带附属文件。第二，下面这些该检入仓库、跟团队共享：

• CLAUDE.md、rules、settings.json。
• Skills、agents、.mcp.json。

个人的有 settings.local.json，以及全局的 ~/.claude.json 和自动记忆目录。这些不进仓库。

顺带提一个安全点。~/.claude 里还有 Claude Code 在会话中写下的数据，比如完整的对话记录。这些文件是明文，不加密，只靠系统的文件权限保护。工具读过的 .env 文件、命令打印出来的密钥，都会被写进对话记录。默认超过 30 天的记录会被清理，周期由 cleanupPeriodDays 控制，最小值是 1。想降低暴露面，缩短这个周期，或者用权限规则禁止读取凭据文件（§06）。

5.8 规则没生效，按这个顺序查

官方在排错里列了一串，我按由易到难重排了一遍。

• 先 /context，看 Memory files 里有没有那个文件。不在列表里，Claude 就看不到它。
• 文件放的位置是否被你的会话加载（见 5.3 的四层位置）。
• 指令够不够具体。「缩进 2 个空格」比「把代码排好」管用。
• 有没有互相冲突的指令。冲突可能出在 CLAUDE.md、子目录里的 CLAUDE.md 和 rules 之间。
• 有没有和 Claude Code 自带的指引打架。你的 CLAUDE.md 里写了提交或 PR 规则，就用 includeGitInstructions 关掉内置的，用 attribution 设署名文字。
• 子目录里的 CLAUDE.md 不会出现在 Memory files 里。它按需加载，加载时终端有一行 Loaded。测试新写的子目录文件，用 shell 创建它，别让 Claude 来写。再让 Claude 去读那个目录里的某个文件。

必须在某个时点执行的指令，比如每次提交前、每次改文件后，别指望 CLAUDE.md。写成钩子。钩子作为 shell 命令在固定的生命周期事件上运行，和 Claude 怎么判断无关。调试路径规则或懒加载的文件时，可以用 InstructionsLoaded 钩子记录哪些文件在什么时候、因为什么被加载。

指令在压缩后消失，原因见 §04。只在对话里说过的指令真的没了，写进 CLAUDE.md 才持久。AGENTS.md 没加载，先看 5.4 的三处。工作目录及以上有没有 CLAUDE.md？版本是不是 v2.1.277 以上？/config 里的 Project instructions 有没有被设成 claude-md 或 managed-only？

5.9 这一节的结论

CLAUDE.md 是把要反复交代的话固化下来，自动记忆是 Claude 自己存的笔记。两者都在每个会话开头加载，所以都占上下文，写得越短越灵。

• 该写：Claude 猜不到的命令、和默认不同的约定、项目特有的决定、常见的坑。
• 别写：读代码就能知道的、会变的、长篇大论的。每一行问一句，删了会出错吗。
• 放对位置：全局放 ~/.claude/，项目放仓库。只对一部分代码有用的，搬进带 paths 的规则。只在某类任务才需要的，搬进 Skill。
• AGENTS.md：v2.1.277 起没有 CLAUDE.md 时直接读。有 CLAUDE.local.md 时，记得改 Project instructions。

再记一点：它只是上下文，不是强制。真正能拦住动作的，是权限。

下一节讲权限模式。Claude 能碰什么，由你决定。

§06 权限模式：它能碰什么由你决定

Permission Modes: You Decide What It Can Touch

先搞清规则由谁执行，再看六种模式各放开到哪一步。结尾讲清楚，哪些场景一步都不能放。

6.1 规则由程序执行，不靠模型自觉

先把一件事说死。权限规则是 Claude Code 这个程序在执行，不是模型在自觉。你写在提示词或 CLAUDE.md 里的话，只影响 Claude 想做什么。改变不了程序放行什么。

这条直接挂回主线。CLAUDE.md 里写一句「别碰 .env」，是占上下文的一句请求，压缩之后可能就淡了。写成一条 deny 规则，不占上下文，也不会被压缩丢掉。该硬挡的事，别靠嘴说。

规则只有三种：allow 放行，ask 每次都问，deny 直接拒绝。判断顺序是 deny、ask、allow，第一个命中的说了算。所以 deny 里留不了例外：拒绝了 Bash(aws *)，再放行 Bash(aws s3 ls) 是没用的。任何一层设置里的 deny，别的层都放不开，托管设置在最上面（团队怎么下发见 §12）。

{
  "permissions": {
    "allow": ["Bash(npm test)", "Bash(npm run build)"],
    "ask":   ["Bash(git push *)"],
    "deny":  ["Read(./.env)", "Read(./secrets/**)"]
  }
}

写法就两种。Bash(npm run build) 匹配一条命令，带 * 就是一族命令。Read(./.env) 按路径匹配，用 gitignore 风格的通配。只写工具名不带括号，就是整个工具，把 Bash 放进 deny，Claude 连这个工具都看不到。

你平时点的「Yes, and don't ask again」其实也在写规则。Bash 命令的批准，会永久存进仓库根目录的 .claude/settings.local.json。文件修改的批准，只管到会话结束。输入 /permissions 能看全部规则和来源。

动手前，我建议先记住三个坑：

• .claudeignore 无效，要挡文件用 Read 的 deny 规则。
• Read 和 Edit 的 deny 只管内置文件工具和 cat、sed 这类认得的命令。Python 脚本自己去开文件，它拦不住，要在系统层面挡得开沙箱，见 6.6。
• Bash 规则不是安全边界。Bash(curl *) 拦不住 /usr/bin/curl，也拦不住 sh -c 套一层。它防手滑，防不了存心绕。

6.2 六种模式，先看一张表

规则是细粒度的开关，模式是整体基线。下表以官方 permission-modes 页为准。

重点看第一列的括号。default 在各个界面里都叫 Manual，命令行可以写 manual 当别名，Hooks 和 SDK 里仍用 default。

起始模式变了。从 Claude Code v2.1.283 起，终端和 VS Code 的会话以 auto 起步。所有套餐、所有提供商都一样，前提是模型支持。

版本上有个小出入。权限页写 v2.1.283，更新日志把「所有套餐和提供商」这一步记在 v2.1.284。两处差一个小版本，稳妥起见升到 v2.1.284 以上。更早的文档写的是只有 Pro、Max、Team 如此，已经过时。

例外有四种：

• 管理员设了 disableAutoMode。
• HIPAA 配置。
• claude -p 与 Agent SDK。
• 模型不支持时回落 Manual。

想改起始模式，优先级是 --permission-mode 参数、设置里的 permissions.defaultMode、内置默认。有个坑："auto" 写在项目的 .claude/settings.json 里不生效，要放用户级设置。

会话中用 Shift+Tab 切换。从 auto 按一次到 default。之后按 default、acceptEdits、plan 转圈。bypassPermissions 只有启动时带了对应参数，或在用户、托管设置里把 defaultMode 设成它，才会出现，dontAsk 永远不在循环里。输入框下方会写当前模式，比如 manual mode on。

6.3 前三档：Manual、acceptEdits、plan

Manual 最慢也最稳。写文件、跑命令都先问你，只有一组内置的只读命令（ls、cat、git status 这类）直接过。陌生代码库从这里起步。

acceptEdits 放开的是工作目录内的文件修改，外加 mkdir、mv、cp 这类文件系统命令。官方清单里连 rm 和 sed 都在，范围仅限工作目录，其余 Bash 命令照样要问。我的用法是：改动留到事后用 git diff 一次看完，就开它。

plan 让 Claude 只研究、只提方案，不动源码。方案出来后可以批准并切到 auto，批准但逐个确认修改，或留在 plan 里继续改。按 Ctrl+G 能在编辑器里直接改方案。规划读得越多，上下文涨得越快，打开 showClearContextOnPlanAccept 设置，批准列表会多一个「清掉规划上下文」的选项，见 §04。

# 一次会话从 plan 起步
claude --permission-mode plan

6.4 auto：让分类器替你点「同意」

auto 是这一节的重点，因为它现在是默认。我认为这个默认本身没问题，问题是很多人不知道它在背后拦什么、不拦什么。每个动作执行前，由另一个模型（分类器）审一遍。越权的、指向陌生基础设施的、看着像被恶意内容驱动的，直接拦下。

只读操作和工作目录内的文件修改不过分类器，开销主要来自 shell 命令和网络操作。分类器看得到你的消息、Claude 的工具调用和 CLAUDE.md 的内容。看不到工具返回的内容，所以网页里藏的恶意指令没法直接影响它。

默认拦下的东西，官方列得很长，挑四类：

• 下载并执行代码，比如 curl | bash。
• 把敏感数据发到外部地址，或把密钥提交进仓库。
• 生产环境部署和数据库迁移。
• force push，以及会丢未提交改动的 git reset --hard、git clean -fd。

默认放行的有四类：

• 工作目录里的本地操作。
• 装 lock 文件里已声明的依赖。
• 只读的 HTTP 请求。
• 往你正在干活的仓库推分支，名字像 production 的发布分支除外。

拦错了怎么办？被拦的动作会出现在 /permissions 的 Recently denied 标签里，按 r 手动批准重试。连续被拦 3 次或累计 20 次，auto 会暂停并改回逐个问你，阈值不能改。多次被拦通常说明分类器不了解你的基础设施，把受信的仓库和域名写进 autoMode.environment，或用 /auto-mode-setup 生成草稿。默认规则全文：

claude auto-mode defaults

有两件事别指望分类器。

口头边界会丢。你说「先别 push，等我看完」，分类器会照办。可它每次是从记录里重新读这句话的。上下文一压缩，这句话就可能没了。要硬保证，写 deny 规则。这又是主线：上下文里的话会被压缩掉，规则不会。

想在 auto 里保留人工检查点，用 ask 规则，比如 6.1 示例里的 Bash(git push *)。带内容范围的 ask 规则在分类器之前判断，永远会弹窗。另外，进入 auto 时，过宽的 allow 规则（整条 Bash(*)、Bash(python*) 这种）会被临时丢掉，窄规则照常生效。用意是别让一条宽规则把分类器架空。

6.5 两个极端：dontAsk 与 bypassPermissions

dontAsk 的逻辑是：本来会弹窗的，一律拒绝。照常能跑的有四类：

• 工作目录内的文件读取。
• 内置的只读 Bash 命令。
• 命中 permissions.allow 规则的调用。
• 被 PreToolUse 钩子批准的调用。

会话永远不会停下来等你，这正是 CI 要的。

# CI 里：只放行测试命令和读文件，其余全拒
claude -p "run the test suite" --permission-mode dontAsk --allowedTools "Bash(npm test)" "Read"

云端会话会忽略设置文件里的 dontAsk 和 bypassPermissions，防止仓库设置把云端会话带进免检状态。无人值守的权限和密钥怎么管，见 §11。

bypassPermissions 关掉所有提示和安全检查，启动参数是 --permission-mode bypassPermissions，--dangerously-skip-permissions 与它等价。中途进不去。以 root 或 sudo 运行会直接拒绝启动。deny 规则仍然有效，allow 规则在这个模式下没有作用。管理员能用 permissions.disableBypassPermissionsMode 整个关掉。

官方给它的适用范围只有一句：隔离容器、虚拟机、没有互联网的 dev container。它不防提示注入。我的建议是想少弹窗就用 auto，别碰它。

6.6 沙箱：模式管问不问，沙箱管碰不碰得到

权限模式回答「要不要先问你」。沙箱回答另一个问题：动作真跑起来之后，它能碰到什么。两者互补，我的建议是两层都用。

沙箱是内置的，输入 /sandbox 打开面板。macOS 不用装东西，Linux 和 WSL2 要先装两个依赖包，原生 Windows 不支持。面板里有两种模式：

• auto-allow：能放进沙箱的命令自动放行，不再问你。放不进去的，退回常规权限流程。
• regular permissions：沙箱照开，但命令仍按常规流程逐个问。

沙箱里的命令默认只能写工作目录和会话临时目录。deny 规则和带内容的 ask 规则，在 auto-allow 里照样生效。三处边界要知道。沙箱只管 Bash 和它的子进程，Read、Edit 这些内置文件工具走权限系统。沙箱里的命令默认继承你环境变量里的凭据，需要时用 sandbox.credentials 屏蔽。命令在沙箱里失败后，Claude 可以带 dangerouslyDisableSandbox 重试，这一次走常规权限流程，想堵死就把 allowUnsandboxedCommands 设为 false。

6.7 几条没有模式能越过的底线

第一类是受保护路径：.git、.claude、.vscode、.idea、.husky、.devcontainer，以及 .bashrc、.zshrc、.npmrc、.mcp.json、.claude.json 等文件。写它们，各个模式的处理不同：

• Manual 和 acceptEdits 下会问。
• auto 下交给分类器。
• dontAsk 下直接拒。
• 只有 bypassPermissions 放行。

settings 里的 allow 规则也预批不了。共同点是：改了它们，等于改了 Claude 自己的行为，或者下次命令会执行什么。

第二类是关键路径删除。目标是根目录、家目录、一级系统目录、你的工作目录及其上级的 rm 和 rmdir。没有任何 allow 规则或 PreToolUse 钩子的 "allow" 能批准。官方管它叫防模型出错的断路器。

另外，被显式 ask 规则命中的工具，任何模式下都不会被自动放行。MCP 里还有两类同样如此：组织设为 ask 的连接器工具，和标了 requiresUserInteraction 的工具。细节见 §08。

6.8 什么时候绝不能放开

前面讲的都是「怎么放」。这一节反过来，列出我认为一步都不该放的场景，每条都有官方文档依据。我的判断是，这几条宁可麻烦一点，也别图省事。

• 在你的真机上开 bypassPermissions。它不防提示注入，也不防它自己手滑。机器上有 SSH 密钥、云凭据、浏览器登录态，这个模式就是把它们全摆在桌上。只在隔离容器里用。
• 第一次打开别人写的仓库就放权。仓库自带的项目设置能带 Hooks、.mcp.json 服务器、env 块和辅助命令。交互会话里它们要等你接受信任对话框，而 claude -p 不弹这个对话框，直接当作已信任。陌生仓库先用 Manual，信任对话框别手快点掉。
• 让 auto 去碰生产。生产部署、迁移、force push，分类器默认会拦，但官方说了它不保证安全。碰生产的会话，把 git push 和部署命令写进 ask，不可逆命令写进 deny。
• 把关键边界只说在对话里。压缩之后它可能不在了，要硬保证就写规则。
• 无人值守时挂一条宽 allow。CI 里用 dontAsk 加精确的 --allowedTools，别写 Bash(*) 图省事。
• 沙箱域名放得过宽，或放行危险的 Unix socket。放行 /var/run/docker.sock 等于交出宿主机。

6.9 这一节的结论

权限的核心是一句话：规则由程序执行，要硬挡就写规则，别靠提示词。模式决定默认放开多少，沙箱决定放开之后能碰到多远，两层加起来才算有边界。

日常我的排法是这样：

• 陌生代码用 Manual。
• 信得过的改动用 acceptEdits 或 auto。
• 不确定做什么，先 plan。
• CI 用 dontAsk。
• bypass 只留给容器。

auto 是默认没错，但要知道它拦什么、不拦什么。

规则能管住它碰什么，却不能教它怎么做事。下一节讲 Skills：把重复的流程打包，只在需要时才进上下文。

§07 Skills：把重复流程打包，按需才进上下文

Skills: Package a Repeated Workflow and Load It Only When Needed

同一段流程你已经贴了第三遍，就该把它做成 Skill。这一节讲它是什么、为什么省上下文、怎么写、怎么不让它乱触发。

7.1 Skill 是一个带说明书的文件夹

Skill 的本体很朴素：一个文件夹，里面有一个 SKILL.md。文件分两段。上面是用 --- 包起来的 YAML 头，官方叫 frontmatter（前置字段）。它写这个 Skill 是干什么的、什么时候该用。下面是正文，写 Claude 照着执行的步骤。

两种触发方式。你自己输入 /skill-name，或者 Claude 看你的话和 Skill 的描述对得上，自己把它加载进来。文件夹名就是命令名。

官方给了一个判断标准。出现下面两种情况，就该做成 Skill：

• 你反复往对话里贴同一套指令、检查清单或多步流程。
• CLAUDE.md 里某一段已经长成了流程，而不是事实。

我的建议是以「第三遍」为线：同一段话贴到第三次，就动手。

以前的自定义命令已经并进 Skill 了。.claude/commands/deploy.md 和 .claude/skills/deploy/SKILL.md 都会生成 /deploy，用法一样，老文件继续有效。Skill 多出来的是支持文件、触发控制和自动加载。Claude Code 还自带一批 bundled Skills。比如 /doctor、/code-review、/batch、/debug、/loop，和你自己写的是同一种东西。

7.2 它省的是上下文：描述常驻，正文按需

这是 Skill 在本书里最重要的一点，直接挂回主线。

CLAUDE.md 每次会话都整份加载。Skill 不一样。会话开始时，进上下文的只是每个 Skill 的名字和一句描述。正文要等到用到时才读进来。官方的意思是，长篇参考资料在你需要之前几乎不花钱。

再往前一步。给 Skill 加 disable-model-invocation: true，连那一句描述都不进上下文，等你手动输入 /名字 才加载。三种配置的区别如下。

重点看第二行。部署、发消息、提交代码这类事，你不想让 Claude 因为「代码看着差不多了」就自己动手。关掉自动触发，既防误触，又让这个 Skill 零成本待命。

但正文一旦载入就留在会话里，之后每一轮都带着它，每一行都是持续的 token 开销。官方的建议是正文写精简，只说做什么，别讲为什么，和 CLAUDE.md 用同一把尺子量。我的做法是写完先删一遍，凡是删了也不影响执行的句子都不留。

会话被压缩时，每个已调用 Skill 的最近一次内容会被重新挂回摘要后面。数字上限和先丢哪个，见 §04。又大又重要的 Skill，压缩后重新调用一次。

描述列表本身也有预算：模型上下文窗口的 1%，超了就从你最少用的 Skill 开始截描述。单个 Skill 的描述加 when_to_use 合计最多 1,536 个字符，关键用途写在最前面。想看这笔账花在哪，运行 /doctor，它会估算描述列表占多少上下文、谁占得最多。/skills 列表里按 t 能按 token 数排序。

7.3 放在哪里，重名谁赢

Skill 放哪里，决定谁能用到它。

官方的位置表里还有三行。子目录里的 .claude/skills/ 启动时不加载。Claude 第一次读或改那个子目录里的文件时才载入。适合 monorepo 里每个包带自己的 Skill。用 --add-dir 或 /add-dir 加进来的目录，它里面的 Skill 会自动加载。但 additionalDirectories 设置只给文件访问权限，不加载 Skill。claude.ai 账号里启用的 Skill，从 v2.1.275 起会同步到终端。Skills 页写的是 v2.1.273，以更新日志为准。不想要就把 syncClaudeAiSkills 设成 false。

重名时企业盖过个人，个人盖过项目，你自己写的也会盖过内置的。插件里的 Skill 带命名空间，写成 插件名:Skill名，不冲突。anthropic-skills 和 claude-ai 这两个命名空间被官方保留，别拿来命名。改文件不用重启，Claude Code 会监视 Skill 目录。会话开始时不存在的顶层 Skills 目录例外，要重启一次。

7.4 写第一个 Skill：审一遍暂存区

下面做一个最小的 Skill：提交前把暂存区的 diff 读进来，按固定格式挑毛病。预计五分钟。我建议你的第一个 Skill 也从自己最常重复的那段流程里挑。

mkdir -p ~/.claude/skills/review-staged

预期结果：没有任何输出，目录建好了。

---
description: Review the staged diff before commit. Use when the user asks to check staged changes, review a diff, or prepare a commit.
---

## Staged changes

!`git diff --staged`

## Instructions

Review the diff above. List problems in three groups:
bugs, missing tests, risky changes.
If the diff is empty, say so and stop.

这里有一行是关键：!`git diff --staged`。Claude Code 会先在本机跑这条命令，把输出贴进正文，再交给 Claude。它读到的是真实的 diff，不是命令本身。

我暂存了什么？
/review-staged

预期结果：两种触发方式都应该得到一份按三组列出的问题清单。第一种靠描述匹配，第二种直接调用。

7.5 控制谁来触发，以及它能预批准什么

有副作用的流程要关自动触发，示例：

---
name: deploy
description: Deploy the application to production
disable-model-invocation: true
---

Deploy $ARGUMENTS to production:
1. Run the test suite
2. Build the application
3. Push to the deployment target
4. Verify the deployment succeeded

$ARGUMENTS 会被替换成你输入 /deploy staging 时跟在后面的内容。Claude 想自己调它会被拦下，所以多半是建议你自己去执行 /deploy。

allowed-tools 能让某些命令在这个 Skill 被调用的那一轮免弹窗，比如 allowed-tools: Bash(git add *) Bash(git commit *) Bash(git status *)。授权只管当轮，你发下一条消息就清掉，也不限制别的工具，其余工具仍受 §06 的权限设置管着。

有一个安全点要留意。Claude Code 对项目 Skill 的 allowed-tools 不看工作区信任。即使在你从没信任过的目录里跑 claude -p，只要 Skill 被调用，它声明的授权就生效。官方的提醒很直接：仓库里提交的 Skill，先看一眼它的 allowed-tools 再跑。

想限制 Claude 能调哪些 Skill，用权限规则：

• Skill 放进 deny，关掉所有 Skill。
• Skill(commit) 精确匹配，Skill(review-pr *) 前缀匹配。
• 改不了 SKILL.md 的共享 Skill，用设置里的 skillOverrides 设成 "name-only"、"user-invocable-only" 或 "off"。在 /skills 菜单里按空格切换。

7.6 让 Skill 保持小：支持文件和子智能体

Skill 文件夹里可以放更多文件。SKILL.md 只写概要和导航，详细的 API 文档、示例集放在 reference.md、examples.md，Claude 需要时才去读。scripts/ 里的脚本是被执行的，不是被读进上下文的。这样一个 Skill 可以带很多资料，平时只占 SKILL.md 那一点。

另一个省上下文的办法是 context: fork。Skill 内容变成子智能体的任务，在独立上下文里跑。看不到你的对话历史，跑完把结果交回来。适合调研、汇总这类读很多、回很少的活。它只对有明确任务的 Skill 有意义，纯规范说明交给子智能体会空手而归。子智能体见 §10。paths 字段则让 Skill 只在你处理匹配的文件时才自动加载。

7.7 和 CLAUDE.md、Hooks 怎么分工

三样东西都在解决「别每次重新交代」，区别在什么时候占上下文、能不能保证执行。

我的判断标准很简单。是一条每次都用得上的事实，放 CLAUDE.md。是一段只在特定任务里用的流程，做成 Skill。是「必须每次都发生」的规则，别指望 Skill 或 CLAUDE.md，它们说到底是请求。官方也提到，Skill 好像不管用时，可以用 Hooks 把行为确定性地压实。

7.8 不灵的时候怎么排

该触发没触发。我的判断是先怀疑描述，再怀疑别的。按顺序查：

1. 描述里有没有用户自然会说的词。
2. 问一句「What skills are available?」，看它在不在列表里。
3. 换个更贴近描述的说法。
4. 直接输入 /名字。

YAML 头写坏了，Skill 会以空元数据加载。/名字 还能用，但 Claude 没有描述可匹配。用 --debug 启动能看到解析错误。

不该触发却触发了。把描述写得更具体，或者加 disable-model-invocation: true。

描述被截短。Skill 太多，预算不够，描述被砍掉，关键词丢了，匹配就差。办法：把不常用的设成 "name-only"，调高 skillListingBudgetFraction，或把描述写短、关键用途放最前面。

触发了，效果不对。被触发只说明 Claude 找到了它，不说明它做对了。官方的测法是基线对比。挑几条真实的提示词，各跑两次，一次开着 Skill，一次关掉。都在新会话里跑，因为写 Skill 时留下的上下文会遮住说明里的漏洞。skill-creator 插件能自动跑这套流程：

/plugin install skill-creator@claude-plugins-official

它给每个测试用例开一个子智能体。它记录 token 和耗时、打分，并比较有无 Skill 的通过率。装好后若提示 Run /reload-plugins to activate.，照着执行一次。

7.9 分享之前，先想想谁会读它

分享有三条路：把 .claude/skills/ 提交进仓库，做成插件（见 §09），或者经托管设置在组织内下发。

别忘了云端会话和定时任务。云端会话读不到你本机的 ~/.claude/skills/，只加载提交进仓库的项目 Skill 和账号里启用的 Skill。routine 每次都是全新的远程会话。只放在本机个人目录的 Skill 会报找不到。要提交进仓库，或在 claude.ai 账号里启用。

还有安全。第三方 Skill 是一份别人写的指令。它可能带着会在你机器上执行的注入命令和预批准的工具。装之前读一遍 SKILL.md，重点看 !`…` 命令、allowed-tools 和 hooks。第三方插件的审查清单统一放在 §09。

7.10 这一节的结论

Skill 的价值在一句话里：把长流程从常驻上下文搬到按需上下文。描述常驻，正文按需，有副作用的干脆连描述都不放。

写 Skill 的顺序，我建议这样走。先在对话里把流程手动跑顺，再固化成 SKILL.md。先写得短，再用基线对比看有没有真的变好。用不上的 Skill 就删，每多一个，描述列表就多占一点预算。

Skill 能教它怎么做事，但它够不着公司的工单系统、数据库和监控。下一节讲 MCP：给 Claude 接上外部系统，以及这条线上同样要付的上下文成本。

§08 MCP：接上外部系统，但每个服务器都要占上下文

MCP: Connect External Systems, and Mind the Context They Cost

这一节讲怎么把工单系统、数据库、监控接进来，怎么认证，以及接得越多越要算清的上下文账。

8.1 什么时候该接一个 MCP 服务器

MCP 全称 Model Context Protocol。它是一个开放标准，让 Claude Code 能连上你的工具、数据库和 API。官方给的判断标准很实在。你发现自己总在把另一个系统里的数据复制进对话，比如工单、监控面板，就该接一个 MCP。接上之后，Claude 直接去读、去操作那个系统，不用靠你粘贴。

典型用法有四种：

• 按工单描述把功能写出来，再开 PR。
• 查 Sentry 上的错误趋势。
• 用只读账号查数据库。
• 根据设计稿改模板。

先泼一盆冷水。接 MCP 不是免费的，每个服务器都要占上下文，也要多一份信任。能用 gh、aws、gcloud、sentry-cli 这类命令行工具搞定的事，官方自己都说命令行更省上下文。因为它们不会给 Claude 增加逐个工具的清单。我的建议是：先问一句命令行能不能做，不能再接 MCP。

8.2 添加服务器：两条命令覆盖大多数情况

服务器分两种。一种托管在远端，用 URL 连。一种跑在你本机，是一个子进程。对应两条命令：

# 远程服务器（官方推荐，兼容面最广）
claude mcp add --transport http notion https://mcp.notion.com/mcp

# 本机进程（stdio）：-- 之后的内容原样交给服务器
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable -- npx -y airtable-mcp-server

我的建议是新手先用 HTTP 远程服务器，再碰 stdio。最常见的坑是 stdio 命令里的 --。它把 Claude 自己的选项（--transport、--env、--scope）和服务器的启动命令隔开。漏了它，服务器自己的参数会被当成 Claude 的选项解析，报错很莫名。

其他几种情况，对着下表选：

SSE 那一行要注意：早期文档写的是 --transport sse，线上现在改成了表里的写法，以线上为准。JSON 配置里有 url 却没写 type，会被当成 stdio 服务器加载失败，要补 "type": "http"。服务器名只能用字母、数字、连字符和下划线。

claude mcp list           # 列出所有服务器，并显示连接状态
claude mcp get notion     # 看某个服务器的详情
claude mcp remove notion  # 删除

会话里输入 /mcp 能看同样的信息，还能重连、认证。list 的状态有这几种：

• ✔ Connected：能用了。
• ! Needs authentication：服务器连得上，但要登录，见 8.4。
• ✘ Failed to connect 或 ✘ Connection error：没连上，见 8.7。
• ⏸ Pending approval：项目里 .mcp.json 的服务器，你还没批准，运行 claude 进交互会话去批。

想练手，官方 quickstart 用文档自家的搜索服务器，不要认证：

claude mcp add --transport http claude-code-docs https://code.claude.com/docs/mcp
claude mcp list
claude

预期结果：add 打印一行 Added HTTP MCP server ...，list 里出现 ✔ Connected。进会话后问下面这句：

Use the claude-code-docs server to look up what MCP_TIMEOUT does

工具调用会带上服务器名，这就是答案来自 MCP 的证据。

8.3 三个作用域：只给自己，还是给整个团队

同一个服务器，可以加在三个地方，区别在谁能用。

我的判断是只有团队真要共用才用 project。重点看存放位置。MCP 的 local 作用域存在 ~/.claude.json，不是 .claude/settings.local.json，两个名字都叫 local，别混。用 --scope project 或 --scope user 切换，作用域添加时就定死了，要改就删掉重加。重复定义时只用优先级最高的一份，不合并字段。顺序是 local、project、user、插件、claude.ai 连接器。

共享的 .mcp.json 里不要写死密钥。它支持 ${VAR} 和 ${VAR:-默认值} 展开：

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": { "Authorization": "Bearer ${API_KEY}" }
    }
  }
}

每人在自己的环境变量里放 API_KEY，配置文件就能安心提交。改了 .mcp.json 要重启会话才生效。

8.4 认证：浏览器登录，或者带一个令牌

远程服务器返回 401 或 403，Claude Code 就把它标成需要认证。支持 OAuth 2.0 的，流程是：

也可以不进会话，在终端直接做：claude mcp login sentry（v2.1.186 起），清除凭据用 claude mcp logout sentry。SSH 上检测不到浏览器时，命令会打印授权链接。你在本机打开，再把重定向后的完整地址贴回来。也可以加 --no-browser 强制这样做。

不走 OAuth 的服务器，比如 GitHub 的远程服务器，用访问令牌：

claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer YOUR_GITHUB_PAT"

claude mcp add 只保存配置，不验证令牌，写错了也显示 Added，所以加完要跑一遍 /mcp 确认 connected。复制令牌时带上的首尾空白会让认证莫名失败，claude mcp list 会给出警告。

两点补充。claude -p 这类非交互运行弹不出 OAuth 流程，需要认证的服务器要先在交互会话里登录好。另外，用 claude.ai 订阅登录，claude.ai 里配好的连接器会自动出现在 /mcp 里。不用再加一遍。用 API key 或 Amazon Bedrock 等方式登录则不会加载。Gmail、Google Calendar 这类连接器，要回 claude.ai 设置里连。

8.5 上下文账：工具描述也在吃你的窗口

这一节挂回主线，也是 MCP 最容易被忽略的成本。

官方在 quickstart 里写得直接。每个连上的服务器，它的工具名和服务器说明（instructions）会加载进每一次会话。接得越多，会话一开始就先少一块空间。

好消息是默认已有优化。工具搜索（tool search）默认开启。启动时只加载工具名和服务器说明。完整的工具定义，等 Claude 真要用时再按需取。Claude Code 对单个服务器也没有固定的工具数上限，实际上限是你的上下文预算。

但这个优化有前提：

• ANTHROPIC_BASE_URL 指向非官方主机时，工具搜索自动关闭。因为多数代理不转发它需要的 tool_reference，所有工具定义会预先加载。
• 设了 ENABLE_TOOL_SEARCH=false 同样是预先加载。工具搜索还要求模型支持 tool_reference。官方列的是 Sonnet 4.5、Haiku 4.5、Opus 4.5 及之后的模型。
• 描述和说明有长度上限。v2.1.296 起默认从 2,048 提到 4,096 个字符。经工具搜索加载的描述，从 v2.1.295 起截到 16,384 个字符。

用 /context 能看到谁占了多少。下面是我按性价比排的省法：

子智能体那一行值得细说。它的定义文件里有个 mcpServers 字段，内联声明的服务器只在子智能体运行期间连接，结束就断开。官方的意思是：想让某个服务器的工具描述不进主对话，就在这里定义，别放进 .mcp.json。子智能体拿到工具，主对话没有。

另一笔账是输出。MCP 工具的返回结果同样进上下文。单次输出超过 10,000 个 token 会警告，默认上限 25,000 个 token，可用 MAX_MCP_OUTPUT_TOKENS 调高。我的建议是别急着调。输出大说明查得太宽，该让查询带条件，比如加 LIMIT、按时间过滤，而不是放开限额把窗口填满。

8.6 安全：每个服务器都是一份你得信任的代码

MCP 的安全问题可以归成三类。

第一，服务器本身。官方的提醒很短也很重。接之前先确认你信任它。会去抓外部内容的服务器，还可能让你暴露在提示注入风险下。Anthropic 会按上架标准审核 Directory 里的连接器。但不对任何 MCP 服务器做安全审计。stdio 服务器是跑在你机器上的进程，等于执行一段别人的代码，更要看来路。

第二，工具返回的内容。服务器返回的文本会进入 Claude 的上下文，里面藏的恶意指令可能影响它的行为。缓解办法是 §06 讲的权限规则、沙箱和最小权限。官方示例连数据库时特意让你用只读账号，原因就在这里。

第三，别人仓库里带的配置。项目里的 .mcp.json 可以声明服务器，克隆来的仓库可能带着你没见过的服务器。交互会话里 Claude Code 会先问你批不批准。仓库自己提交的批准设置，在未信任的文件夹里会被忽略。但 claude -p 和云端会话没法弹窗，会直接加载项目级服务器。想拦住某个服务器，写进 disabledMcpjsonServers，任何模式下都有效。headersHelper 是会被当成任意 shell 命令执行的脚本，接受了文件夹的信任对话框才会运行。

权限规则里怎么写 MCP：mcp__puppeteer 匹配整个服务器，mcp__puppeteer__puppeteer_navigate 精确到一个工具。注意，Tool(param:value) 这种带参数的规则，在设置文件里对 MCP 工具无效。带括号的 mcp__ 规则会被跳过，只能用命令行的 --disallowedTools。

还有两条保险。服务器可以把某个工具标成 anthropic/requiresUserInteraction，它每次都必须弹窗，auto 和 bypass 模式也一样。组织管理员能把 claude.ai 连接器里的某个工具设为 ask 或 blocked。这两类也是 §06 讲的底线，任何模式下都不会被自动放行。

8.7 连不上的时候，按这个顺序排

先用 /mcp 或 claude mcp list 看状态，再对症。

• No MCP servers configured。多半是在另一个项目里加的，local 作用域只对那个项目有效。回当前项目重加，或加 --scope user。也可能配置文件放错了路径，Claude Code 只读 ~/.claude.json 和项目根的 .mcp.json。
• Failed to connect。先看状态后附的失败详情，往往直接点名缺的头或被拒的令牌。远程服务器用 curl -I URL 判断：404 或 405 说明服务器活着，401 或 403 要认证，没响应查网络。stdio 服务器就把配置里的命令直接在终端跑一遍看真实报错。
• 启动超时。默认 30 秒，stdio 服务器第一次跑常因 npx 下载包而超时。用 MCP_TIMEOUT=60000 claude 放宽，单位毫秒。
• 已连接但没有工具。多半缺环境变量，比如 API key，用 --env KEY=value 或 .mcp.json 的 env 字段补上。
• 改了 .mcp.json 没生效。启动时才读，退出重开。以前拒绝过该服务器的，用 claude mcp reset-project-choices 重置批准记录。
• Server already exists。同名同作用域重复添加，先 claude mcp remove。

8.8 这一节的结论

MCP 的核心取舍，一句话。它把外部系统接进来。同时把外部系统的工具说明和返回内容，也接进了你的上下文。多一个服务器，多一份开销，多一份要信任的代码。

我的做法是这样：

• 能用命令行，就用命令行。
• 确实要接，先用 local 作用域试。确认值得，再升到 project 或 user。
• 密钥放环境变量，不进 .mcp.json。
• 用不上的服务器及时关。
• 只在某类任务里用的，放进子智能体里。

MCP 让 Claude 够得着更多系统。但「每次都必须发生」的事，比如保存前跑格式化、禁止改某些文件，靠它也靠不住。下一节讲 Hooks：把这类确定性规则从提示词里拿出来，交给程序执行。

§09 Hooks 管死规则，Plugins 管整套分发

Hooks for Rules That Must Always Hold, Plugins for Shipping a Whole Setup

先讲怎么用 Hooks 把「每次都必须发生」的事交给程序。再讲插件怎么把 Skills、MCP、Hooks 打成一包。最后单独讲第三方插件怎么审。

9.1 「每次都必须发生」的事，不该靠提示词

你在 CLAUDE.md 里写「改完文件必须跑格式化」。大部分时候它会照办，有时候它忘。这不怪模型，提示词本来就是请求，不是命令。

Hooks 解决的就是这类事。官方的定义很短。Hooks 是你定义的 shell 命令。Claude Code 在生命周期的特定节点去跑它。它让某些动作总是发生，而不是靠模型选择要不要做。

这又是主线。规则写进提示词，占上下文，还会被压缩冲淡。写成钩子，它跑在程序里，不占提示词，也不依赖模型记性。该确定的事，从上下文里搬出来。

先划清分工，别用错工具：

• CLAUDE.md 放事实，见 §05。
• Skill 放流程，按需加载，见 §07。
• Hooks 放规则，必须发生的事用它。
• 权限规则放「能不能碰」，见 §06。钩子和它是搭档。PreToolUse 钩子在任何权限模式检查之前触发，连 bypassPermissions 也拦得住。反过来，钩子返回 allow 越不过 deny 规则。钩子能收紧限制，不能放宽到规则之外。

9.2 第一个钩子：每次改完文件自动格式化

钩子配置在设置文件里的 hooks 块下。放哪个文件，决定谁能用：

重点看第二行：团队要遵守的钩子提交进 .claude/settings.json，克隆下来就有。Skill 和子智能体的头部也能定义钩子。前者在 Skill 被调用后生效，后者只在该子智能体运行期间生效。

第一个目标：Claude 每改完一个文件，自动跑 Prettier。我建议第一个钩子就选这种后果小、见效快的。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

两处关键。PostToolUse 是「工具调用成功之后」，matcher 写 Edit|Write 只在这两个工具后触发。命令从 stdin 读到 Claude Code 传来的 JSON。用 jq 取出文件路径，交给 Prettier。

钩子成功时对话里什么都不显示，看文件变没变，或用 claude --debug。要先装好 jq。

9.3 常用事件与五种钩子类型

事件很多，完整列表在官方 Hooks 参考页。日常用得到的就这几个：

另外还有 Notification（弹桌面通知）、PermissionRequest（自动批准特定请求，匹配器务必收窄）、ConfigChange（审计配置改动）等。官方文档近期还新增了 PreModelSwitch 和 PostModelSwitch 两个事件，围绕模型切换触发。

钩子有五种类型。command 跑 shell 命令，最常用。http 把事件 POST 给一个 URL，适合接团队的审计服务。mcp_tool 调用已连接 MCP 服务器上的工具。prompt 让一个模型做一次判断。默认是后台功能用的 Haiku 级小模型。适合「任务都完成了吗」这种要靠判断力的事。agent 起一个能读文件的子智能体来验证，官方标注为实验性。规则能用确定性命令写清，就别用 prompt 钩子。它每次都调模型，慢，花 token，还可能判断偏差。

9.4 拦住危险操作：PreToolUse 加退出码 2

我的看法是，规则类钩子一律放 PreToolUse。标准写法是这样。Claude Code 把事件数据以 JSON 传到脚本的 stdin，里面有 tool_name 和 tool_input。脚本用退出码回话：

• 退出 0：钩子没意见，但这不等于批准，权限流程照走。
• 退出 2：拦下动作，stderr 里的原因交给 Claude 当反馈，它据此换个做法。
• 其他退出码：多数事件下是非阻塞错误，动作照常往下走。

下面是保护敏感文件的脚本，改自官方指南示例，存为 .claude/hooks/protect-files.sh：

#!/bin/bash
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

for pattern in ".env" "package-lock.json" ".git/"; do
  if [[ "$FILE_PATH" == *"$pattern"* ]]; then
    echo "Blocked: $FILE_PATH matches protected pattern '$pattern'" >&2   # stderr 成为给 Claude 的反馈
    exit 2                                                              # 退出码 2 就是拦截
  fi
done
exit 0

然后 chmod +x .claude/hooks/protect-files.sh，并注册到 PreToolUse，匹配器同样用 Edit|Write：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-files.sh" }
        ]
      }
    ]
  }
}

预期结果：让 Claude 往 .env 加一行注释，执行前被拦下，Blocked: 那句话交给 Claude。路径用 $CLAUDE_PROJECT_DIR，不怕当前目录变了。

写之前先知道几件事：

• 钩子自己出错，默认是放行的。脚本崩了、jq 没装，只显示一条 hook error，动作照常执行。v2.1.295 给 command 和 http 类钩子加了 onFailure: "block"。想做「出错就拦」的硬规则，先到 Hooks 参考页确认它的确切行为。
• 同一事件的多个钩子并行跑。一个钩子 deny 拦不住兄弟钩子执行，别指望靠它抑制另一个钩子的副作用。
• if 字段是尽力而为的过滤。它用权限规则语法（如 Bash(git *)）决定钩子要不要启动，解析不了命令时照跑。要硬性允许或拒绝，用 §06 的权限规则。
• PostToolUse 撤销不了，工具已经执行完了，要拦只能在 PreToolUse。
• Stop 钩子别死循环。连续拦截 8 次没进展，会被强行放行。脚本里读 stop_hook_active，为 true 就退出 0。

钩子没触发，按顺序查：

1. /hooks 里它在不在对的事件下。
2. 匹配器区分大小写。
3. 手动喂一段 JSON 试脚本：echo '{"tool_name":"Bash","tool_input":{"command":"ls"}}' | ./my-hook.sh，再看 echo $?。
4. 有没有 chmod +x。
5. JSON 有没有多余逗号。

钩子命令以你的全部用户权限运行，能删能改你账号下的任何文件。写的时候给变量加引号，检查路径里有没有 ..。交互会话里所有设置文件里的钩子，都要等你接受工作区信任对话框才会运行。而 claude -p 不弹对话框，直接当作已信任，仓库里提交的钩子照跑。

还有一类用法：用钩子把上下文补回来。压缩会丢对话细节。用 SessionStart 钩子加 compact 匹配器，压缩后重新打印项目约定。stdout 的纯文本会被加入上下文。别塞太多，每个字都在占窗口。

9.5 插件：把一整套打成一包

Skill、钩子、MCP 服务器都能单独用，不需要插件。插件是把它们打包的方式。它是一个目录，里面有 Skills、子智能体、Hooks、MCP 服务器等组件。Claude Code 把它作为一个单元安装和加载。

用不用插件看一条。想把几样东西作为一整套分发给别人，装到很多项目里，或发版本化的更新，就做插件。只在自己一个项目里用，不需要。

典型的目录长这样：

my-plugin/
├── .claude-plugin/
│   └── plugin.json        # 清单：名字、描述、版本等
├── skills/review/SKILL.md # 变成 /my-plugin:review
├── agents/reviewer.md     # 子智能体
├── hooks/hooks.json       # 钩子，格式与设置文件里的 hooks 块相同
└── .mcp.json              # MCP 服务器

清单只放在 .claude-plugin/plugin.json，其他组件目录放在插件根目录，别塞进 .claude-plugin/。插件里的 Skill 带命名空间，调用时写成 /插件名:Skill名。开发时不需要市场，直接加载目录：

claude --plugin-dir ./my-plugin

改完不重启，运行 /reload-plugins。创建的完整步骤、清单字段和各组件写法这里不展开，请看官方的 plugins/create、plugins/components 和 plugins/manifest-reference。

9.6 上下文账：启用的插件，每轮都在占窗口

别把插件当成「装了不用就没事」。官方概览页写得清楚：启用的插件是每次会话的一部分，不只是用到它的会话。

• 插件里有三类东西，Claude 能自行调用：Skill、子智能体和命令。它们的名字和描述，每一轮都在上下文里，哪怕这个会话没用到。这些 token 算进用量，也挤占窗口。正文仍是用到才加载。
• 插件的 MCP 服务器随会话一起跑，开销按 §08 的工具搜索算；钩子在对应事件上触发。
• 它运行的一切，都以你的身份运行。

三个办法管住这笔账。安装前，在 /plugin 的 Marketplaces 标签里点开插件。官方市场的插件会显示 Context cost 估算。安装后，Installed 标签里有 Not used recently 分组。它列出你可以关掉的。想停用又不卸载，在 /plugin 里禁用，或运行 claude plugin disable。

9.7 市场与安装：一个目录、两条命令

市场（marketplace）不是应用商店。它是一个带 .claude-plugin/marketplace.json 的仓库或目录，列出有哪些插件、各从哪里取。先添加市场，再按「插件名@市场名」安装。Anthropic 的官方市场，在你第一次启动交互式终端会话时自动添加。除非托管设置禁了。它和 claude.com/marketplace 那个网站不是一回事。

# 在会话里
/plugin                                          # 打开插件管理器，Discover 标签可浏览
/plugin marketplace add anthropics/claude-code   # 添加一个市场（owner/repo 格式）
/plugin install plugin-name@marketplace-name     # 安装，并选择作用域
/reload-plugins                                  # 让改动在当前会话生效

# 在 shell 里，不需要进会话
claude plugin install plugin-name@marketplace-name

安装时选作用域：

• user：你所有项目。
• project：这个仓库的所有协作者。写进提交的 .claude/settings.json，每人仍要在自己机器上安装。
• local：只有你、只在这个仓库。

云端会话不加载你本地设置里的插件。

想让团队自动拿到同一个市场，在项目的 .claude/settings.json 里写 extraKnownMarketplaces，成员信任该文件夹后就会加上。从 v2.1.195 起，只靠项目设置启用、来自外部源的插件，要等成员自己装了才加载。官方市场大多默认开自动更新，社区和第三方默认关。安装的完整细节、依赖和排错，请看官方 plugins/install 页。

9.8 第三方插件的安全审查

这一节单独拿出来，因为插件是本书里信任成本最高的扩展形式。官方的说法没有留余地：不管来自哪一档市场，装上的插件都能以你的用户权限运行代码。Anthropic 不控制插件里有哪些 MCP 服务器、文件或其他软件。也无法保证它们按预期工作。

Claude Code 按名字把市场分三档：官方（如 claude-plugins-official），社区（如 claude-community），以及其余所有的第三方。官方和社区的名字只认来自 github.com/anthropics/ 仓库的市场，同事或公司发布的都算第三方。第三方不等于不能用，等于要你自己审。

装之前，按下表过一遍。官方有专门的 plugins/security 页讲审查，这张表是我从已读文档里提炼的最小版本，以官方页为准。

表后补三条，都是我的建议。

• 先在隔离环境里试：一次性的容器或虚拟机，权限模式用 Manual。看它到底做了什么，再决定装不装到真机。
• 团队用，走白名单：管理员用托管设置里的 strictKnownMarketplaces 限制可添加的市场。不设就不限制，空数组是彻底锁死（官方市场也被挡），给列表就是白名单。它按市场匹配，不看里面的条目。要挡 command 来源，另设 disableCommandPluginSources，详见 §12。
• 别在没审过的仓库里无人值守地跑：给 claude -p 加 --bare，细节见 6.8。

9.9 这一节的结论

两件事记住。第一，必须发生的规则写成钩子，不写进提示词。它不占上下文，不会被压缩冲淡，也不靠模型记性。第二，插件是分发手段，也是信任边界。打包方便，装别人的就要审，装上之后每轮都在占你的窗口。

我的顺序是：先把规则落到钩子，把流程落到 Skill，自己用顺了再打成插件。别一上来就装一堆别人的包。

到这里，单个会话里能做的扩展都讲完了。下一节讲子智能体与并行：把读得多的活丢进别的上下文，让主会话保持干净。

§10 子智能体把探索关进别的上下文，主会话才不会被填满

Subagents and Parallel Work

§04 讲过，上下文越满，Claude 越容易跑偏。这一节讲怎么把吃上下文的活派出去，再讲几件事同时跑时，怎么让它们互不踩脚。

10.1 搜索和日志关进别的窗口，只把结论带回来

跑一遍测试套件，终端能吐出几千行。读十几个文件找一个调用点，每个文件都会进你的上下文。这些东西你多半只看一眼，之后再不引用，却一直占着位置，直到你 /compact 或 /clear（见 §04）。

子智能体就是为这类活准备的。官方的说法是，每个子智能体在自己的上下文窗口里运行。它有独立的系统提示词、工具权限和权限设置。它干完活，只把摘要交回来。过程里读过的文件、跑出的日志，都留在它那个窗口里。

它起步时是干净的。它看不到你的对话历史，看不到你调用过的 Skill。也不知道 Claude 已经读过哪些文件。它拿到的只有这些：

• 自己的系统提示词。
• Claude 写的那段委派说明。
• CLAUDE.md 和 git 状态快照（Explore 和 Plan 例外）。
• skills 字段列出的 Skill 全文。

从现在开始，你是下单的人，子智能体是外包的人。外包的人只看得到订单，所以订单要写全。

用子智能体跑完整的测试套件，只报告失败的用例和它们的报错，不要贴通过的部分

这句提示词挂着主线的两头。「只报告失败」保护主会话的上下文。「失败的用例和报错」是验收标准，你不看过程，也知道活干成没有（第二条主线，见 §03）。

重点看后两行。输出多、结论短的活，收益最大。

10.2 内置的三个先认全，Claude 会自己派

你不配置，Claude 也会按任务描述决定要不要委派。官方内置的有好几个，最常出场的是这三个。

有两个细节影响你怎么写提示词。第一，Explore 和 Plan 跳过你的 CLAUDE.md 和 git 状态，为的是又快又省。所以「忽略 vendor/ 目录」这类规则，要写进给 Claude 的任务里。第二，从 v2.1.198 起 Explore 沿用主会话的模型，不再固定用 Haiku。主会话跑 Fable 时是例外。订阅、Console 和 LLM 网关下，Explore 改用 opus 别名指向的 Opus。想让探索便宜，自己建一个叫 Explore 的子智能体，写上 model: haiku，它会覆盖内置的。

只想去掉 Explore 和 Plan，设 CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1（v2.1.198 起）。

10.3 自己写一个，一个 Markdown 文件就够

子智能体是带 YAML frontmatter 的 Markdown 文件。正文就是它的系统提示词。你可以让 Claude 替你写，也可以自己写。/agents 从 v2.1.198 起不再有创建向导，只提示你去看文件位置。

---
name: test-runner
description: 跑测试并只汇报失败项。改完代码后主动使用。
tools: Bash, Read, Grep
model: haiku
---

你负责跑测试。运行项目的测试命令，只汇报失败的用例、
报错原文和最可能的出错文件。通过的用例不要提。

只有 name 和 description 必填。Claude 全靠 description 决定派谁，所以一个子智能体只管一件事，描述要能和别的区分开。所有描述合计超过 15,000 token，启动时会警告。

同名时托管设置优先级最高，插件最低。插件里的子智能体不支持 hooks、mcpServers、permissionMode（见 §09）。

调用有三档：

• 话里点名，Claude 自己决定派不派。
• 用 @ 从候选里选，保证它出场。
• 整个会话都以它的身份运行，用下面的命令。

claude --agent code-reviewer   # 主线程直接套上这个子智能体的工具限制和模型

10.4 模型怎么定：环境变量不再压过一切

让子智能体用便宜模型，是省钱的主要办法。按官方价格页，每百万 token 的输入价如下。Haiku 5.5 是 $0.10（提示词在 100K 内），Opus 5.5 是 $4。差 40 倍。

这里有一处旧说法已经失效。很多资料写 CLAUDE_CODE_SUBAGENT_MODEL 优先级最高，现在它只排第三，后面只剩主会话的模型。v2.1.251 之前它排第一，压过其他所有设置。现在的顺序是：

这个变量只是个默认值。想让所有子智能体统一用一个模型，要再加一个变量（v2.1.257 起）：

{
  "env": {
    "CLAUDE_CODE_SUBAGENT_MODEL": "haiku",
    "CLAUDE_CODE_SUBAGENT_MODEL_FORCE": "1"
  }
}

打开 _FORCE 后，定义里的 model 被忽略，Claude 也不能临时指定模型。但 fork 和用 model: inherit 的 Skill 子智能体，仍跟着主会话。验证办法：子智能体运行时敲 /tasks，它那一行会写出所用模型（v2.1.243 起）。

10.5 前台、后台、fork，以及它们的上限

前台子智能体会卡住主会话，权限提示直接问你。后台的和你并行，需要权限时，提示冒到主会话里并写明是谁在问。你同意它才继续，按 Esc 只拒这一次。交互会话里 fork 模式默认开（v2.1.232 起）。此时 Claude 派出的子智能体基本都在后台跑。Ctrl+B 能把正在跑的任务转到后台。

fork 是特殊的一种：它继承整段对话，不从零起步。副任务需要大量背景时，用 /subtask（v2.1.212 起）。fork 的系统提示词和工具与主会话一致，能复用提示缓存。同样背景下比新起的子智能体便宜。fork 不能再 fork。

/subtask 给目前改过的解析器补单元测试

• 同时运行 20 个时再派，会报 Concurrent subagent limit reached，用 CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS 调整
• 子智能体默认最多再派三层，用 CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH 调整，设 1 即关闭嵌套
• 每次调用都新建实例。想接着干，让 Claude 恢复它，历史完整保留

权限有条要记牢。主会话在 bypassPermissions、acceptEdits 或 auto 模式时，子智能体沿用同一模式，自己写的 permissionMode 被忽略。主会话在 default、dontAsk 或 plan 时，才按子智能体自己的设置跑。唯独 bypassPermissions 例外：主会话也是该模式才生效（v2.1.267 起，模式见 §06）。子智能体之间互发的消息，不算你的批准。

10.6 并行改同一个仓库，每个会话要有自己的 worktree

上下文隔离不等于文件隔离。两个会话同时改一个目录，会互相覆盖。解法是 git worktree：同一份仓库历史，各有各的工作目录和分支。

claude --worktree feature-auth   # 在 .claude/worktrees/feature-auth/ 建 worktree，分支叫 worktree-feature-auth

换个终端、换个名字再跑一次，就是第二个隔离会话。不写名字，Claude 会起一个。几个要点：

• 把 .claude/worktrees/ 加进 .gitignore
• 新 worktree 是全新检出，依赖要重装。.env 这类被忽略的文件，列进项目根的 .worktreeinclude（写法同 .gitignore）就会自动复制
• 退出时，干净的未命名 worktree 自动删除，有改动则问你保留还是删除。-p 非交互模式不做清理
• 子智能体想要独立 worktree，定义里写 isolation: worktree。或对 Claude 说「让子智能体用 worktree」

10.7 agent view：把后台会话收进一个屏幕

开七八个终端标签，你很快记不清谁在等你。claude agents 打开的 agent view 把所有后台会话放在一屏：谁在跑、谁在等你、谁做完了。官方仍标它为 research preview，界面和快捷键可能变。

claude attach 和 claude logs 从 v2.1.290 起可用名字代替 ID。

这里有两个坑。第一，权限提示和沙箱提示不能靠在 peek 里回复来回答，消息只会排队，必须按 → 进入后回答。第二，每个会话独立消耗订阅额度。官方的说法是，并行十个，额度消耗约为单个的十倍。

文件隔离是自动的：派发的会话改文件前，先进入自己的 worktree。它做完会提交，有远程就推分支，但不会推 main，不会强推，不会合并。你的 CLAUDE.md 若写明提交由你来做，它就把 git 留给你。在 agent view 里删会话，Claude 建的 worktree 一起删，先提交再删。会话跑在本机，关机即停。

10.8 agent teams：协调成本高，先用别的

agent teams 让多个会话组队。一个当组长，队友各有独立上下文，能互相发消息，共用任务清单。它是实验功能，默认关闭，要设 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 才开。

适合的场景是多角度并行审查，或带着互相竞争的假设排查 bug。建议从 3 到 5 个队友起步，每人分 5 到 6 个任务。任务太小，协调成本盖过收益。太大，队友跑太久没人检查。

限制有两条要记。teams 不给队友分 worktree，所以任务按文件划分，别让两个人碰同一个文件。进程内队友不能随 /resume 和 /rewind 恢复，一个会话只能有一个队伍，队友不能再带队友。

官方还有动态工作流和云端的 Projects，本书不展开。选哪种，官方给了三问：谁来协调？工人之间要不要对话？任务碰不碰同一批文件？

10.9 这一节的结论

并行的办法有五六种，选择顺序其实很短。能用子智能体解决的，不开 teams。要同时改同一个仓库，每个会话一个 worktree。要同时盯多件互不相关的事，用 agent view。

所有办法背后是同一件事：把吃上下文的活放到别的窗口，只让结论回到你面前。每个并行的窗口也都在单独烧 token。

下一节 §11 把这套东西搬到你不在场的地方：CI 里、定时任务里。那时没人能点「同意」，权限和密钥就成了头等大事。

§11 能走开的会话，靠验证方法和权限边界兜底

CI and Unattended Runs

前面各节都假设你坐在旁边。这一节讲你走开之后。命令行怎么跑，GitHub Actions 怎么接，云端怎么定时。审查怎么自动化，权限和密钥怎么管。

11.1 claude -p 是所有自动化的底座

加上 -p（或 --print），Claude Code 就以非交互方式运行：读提示词，干完活，打印结果，退出。成功时退出码是 0，失败时非 0，脚本可以直接据此分支。

claude -p "总结这个项目" --output-format json | jq -r '.result'   # json 输出带会话 ID 等元数据，正文在 result 字段

重点看 --bare。它跳过 Hooks、Skills、插件和 MCP 服务器。自动记忆和 CLAUDE.md 也不自动发现。官方推荐脚本和 SDK 调用都用它，还说将来会成为 -p 的默认值。

这条直接挂回主线。CI 里最怕的是「这台机器上结果不一样」，原因往往是某人 ~/.claude 里的钩子，或项目 .mcp.json 里的服务器。--bare 把上下文收窄到你用参数明说的那些，每台机器吃进去的东西一样。

用 --bare 要换认证方式：它不读 OAuth 凭据、系统钥匙串和 CLAUDE_CODE_OAUTH_TOKEN，要设 ANTHROPIC_API_KEY 或用 apiKeyHelper。另外，坏掉的 --mcp-config 条目会被静默跳过，运行照常结束。要让 CI 在这时失败，就检查 system/init 事件里的 mcp_server_errors（v2.1.219 起）。

11.2 GitHub Actions：让 @claude 在仓库里干活

GitHub Actions 集成跑的是官方的 anthropics/claude-code-action。在 PR 或 issue 评论里写 @claude，它就分析代码、改代码、推提交。给它一个 prompt，它也能在任意 GitHub 事件上自动跑。

不用向导也行：装 App，加 ANTHROPIC_API_KEY 或 CLAUDE_CODE_OAUTH_TOKEN 密钥，复制官方示例工作流。下面是响应 @claude 的最小版本。

name: Claude Code
on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]
jobs:
  claude:
    if: contains(github.event.comment.body, '@claude')   # 没提到 @claude 就不启动 runner
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
      issues: write
      id-token: write   # 默认的 GitHub App 认证需要
      actions: read     # 让它能读 PR 上的 CI 结果
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 1
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

它按有没有 prompt 分两种模式。没有 prompt 是交互模式，等触发词，结果以评论回到 PR。有 prompt 是自动化模式，不等人，结果默认只进工作流日志。下面的定时报告是自动化模式的例子，注意模型名和工具白名单都写在 claude_args 里。

name: Daily Report
on:
  schedule:
    - cron: "0 9 * * *"
jobs:
  report:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      issues: read
      id-token: write
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: "总结昨天的提交和未关闭的 issue"
          claude_args: |
            --model claude-opus-5-5
            --allowedTools "mcp__github__list_commits,mcp__github__list_issues"

示例里的模型名是 claude-opus-5-5。旧资料里常见 claude-opus-4-8，官方示例已经换掉了。

踩坑集中在四处：

• 纯文本 prompt 默认没有 shell 和 GitHub API，要用 --allowedTools 逐个授予
• 触发者须有仓库写权限，机器人账号默认被拒，要列进 allowed_bots
• 用默认 GITHUB_TOKEN 提交，GitHub 不会触发后续 CI，别给 Action 传这个 token
• 定时工作流只从默认分支跑，公开仓库 60 天没动静会被停掉

省钱的办法：请求写具体，CLAUDE.md 保持简短（它每次运行都要读，§05）。再配 --max-turns、工作流超时和并发控制。

11.3 云端定时：routines、云端会话和 /loop 别混用

routines 的每次运行都是一个云端会话。这是官方现在的叫法（文档标题是 Use Claude Code in the cloud）。入口 claude.ai/code 没变，旧文章里多半叫它网页版。你也可以直接用 claude --cloud "任务描述" 起一个。它在云端克隆你的 GitHub 仓库，不是你本地的检出，所以先把提交推上去。

routine 是一份存好的配置：一段提示词、若干仓库、一组连接器，外加触发器。触发器有三种，可以叠加：

• 定时：每小时、每天、工作日、每周，或某个时刻跑一次。想要自定义 cron，在命令行用 /schedule update。整点会晚几分钟启动，挑 9:07 比 9:00 好
• API：向它专属的 /fire 地址发 POST，带持有者令牌。令牌只显示一次，存进告警系统的密钥库
• GitHub：PR、发布等仓库事件触发，每个事件一个独立会话

在命令行里，/schedule 每天早上 9 点审查 PR 就能对话式创建，API 触发器只能在网页上加。routines 仍是 research preview。

有两点要提前知道。第一，API 带来的 text 会被包进一个标明「不可信数据」的块，Claude 默认不照做。所以保存的提示词要明说「处理 payload 里描述的告警」，它才会动手。第二，运行列表里的绿色只代表会话正常启动和退出，不代表任务成功。要打开转录自己看，这就是第二条主线在云端的样子。

更轻的是 /loop。/loop 5m 检查部署是否完成 在当前会话里按间隔重复跑，只在 Claude Code 开着且空闲时触发，7 天后自动过期。它是会话的附属品，不是调度系统。

11.4 自动审查有三档，按改动大小选

本地的 /code-review 默认审分支上领先上游的提交加未提交改动，也可传文件、PR 号或分支。--fix 直接改工作区，--comment 把发现贴到 PR。它跑在子智能体里（§10），不会撑满你的对话。

托管的 Code Review 只给 Team 和 Enterprise。它也是 research preview。一批 agent 并行审查，再有一步核实过滤误报。结果按严重程度标成 Important、Nit、Pre-existing。关键一点：它不批准也不拦截 PR，检查结果永远是 neutral。想用它卡合并，就在自己的 CI 里读检查结果的严重度计数：

gh api repos/OWNER/REPO/check-runs/CHECK_RUN_ID \
  --jq '.output.text | split("bughunter-severity: ")[1] | split(" -->")[0] | fromjson'   # 返回各严重度的计数

调教它，改仓库里的 REVIEW.md。可以做这几件事：

• 重新定义什么算 Important。
• 限制 Nit 的条数。
• 列出不用审的路径。
• 加上本仓库的必查项。

官方说，同样的规则写在这里，比塞进很长的 CLAUDE.md 更可靠。它按 token 计费，走独立的 usage credits。「每次推送都审」会让费用乘以推送次数。管理设置里可以设月度上限。

ultrareview 要用 claude.ai 账号登录。下面这些用不了，此时退回本地审查：

• Bedrock、Agent Platform、Foundry。
• 开了零数据保留的组织。

Pro 和 Max 各有 3 次一次性免费。之后走 usage credits，启动前的对话框会给估价。脚本里用 claude ultrareview，别用 claude -p '/code-review ultra'，后者发起云端审查就退出，拿不到结果。退出码 0 是完成，1 是失败或超时（默认等 45 分钟）。

11.5 无人值守时，权限和密钥要提前定死

没人在旁边点「同意」，每个本会弹窗的动作只有两种下场：被拒，或者被放行。哪种由你事先写的规则决定。

权限：选一个模式，再写窄白名单

模式的完整对照见 §06。无人值守时，我只看这几个：

• dontAsk：本会提示的一律拒绝，白名单和只读操作照常。锁死的 CI 首选。
• acceptEdits：自动写文件，其他 shell 命令仍需白名单。改代码类任务用。
• auto：后台分类器审查每个动作。长任务、可信环境用。
• bypassPermissions：只在隔离容器或虚拟机里用。

有一个陷阱：没人指定模式时，-p 会用内置起始模式，它可能是 auto。所以要显式传 --permission-mode。再配一个 --permission-prompts none（v2.1.259 起）。所有会弹窗又没被规则解决的请求直接拒绝，并告诉 Claude 别重试。运行不会卡在一个没人回答的提示上。

claude --bare -p "跑测试并修复失败项" \
  --permission-mode dontAsk \
  --allowedTools "Bash(npm test *),Read,Edit" \
  --max-turns 15 --max-budget-usd 5   # 边界、轮数、花费，三道闸都设上

白名单里 Bash(npm test *) 的星号前面要有空格，否则 Bash(npm test*) 还会匹配到别的命令。还要记住，Bash 规则不是安全边界。真正的围墙是容器、沙箱和网络出口（见 §06）。

云端 routines 没有权限模式选择器。会话自主运行 shell 命令、用仓库里的 Skills、调用你加的连接器。它能碰什么，由三样东西定：选的仓库，环境的网络和变量，加的连接器。创建时你已连接的连接器默认全部带上，用不到的要主动删掉。默认环境的网络是 Trusted 白名单，别图省事改成 Full。

密钥：能不放就不放，放也别放进仓库

• 绝不提交进仓库。用 GitHub Secrets，在工作流里写 ${{ secrets.ANTHROPIC_API_KEY }}。工作流只授予它需要的权限
• 两种凭据。API 密钥来自 Console。订阅令牌用 claude setup-token 生成，有效期一年，设成 CLAUDE_CODE_OAUTH_TOKEN，只能发模型请求。令牌绑在生成它的那个人的订阅上，全组织共用请用 API 密钥
• 最好不存长期密钥。Action 支持工作负载身份联合。用工作流的 GitHub OIDC 令牌，经 Console 的服务账号换取访问权。要给工作流 id-token: write
• routine 的 API 令牌每条 routine 一个，只能触发它自己。可在同一对话框重新生成或吊销
• 公开仓库的 fork PR，GitHub 本来就不给密钥。所以审查只对同仓库分支上的 PR 生效。别为了让它跑起来而绕开这条

密钥之外还有不可信的文本。PR 描述、issue 正文、告警内容都是别人写的，进了提示词就可能带指令。routines 把 text 包成「不可信数据」就是在防这个。你自己的流水线同理，别让带写权限的 Claude 去处理陌生人的输入。

11.6 走开之前，先写好怎么验收

第二条主线在这一节兑现。你盯着的会话，验收靠你的眼睛。你走开的会话，验收只能靠机器可读的东西：

• 测试和构建命令，写进提示词和 CLAUDE.md，让它自己跑到通过为止
• 退出码和 --json-schema 结构化输出，让下游脚本判断成败
• routine 的转录，回头抽查，不看绿灯

没有这些，走开的会话就是没人复核的猜测。

11.7 这一节的结论

自动化的最小配方只有四件事：

• -p 加 --bare 固定上下文。
• 窄白名单加 --permission-mode 划边界。
• 密钥放对地方。
• 验收条件写成机器能读的。

其余的 Actions、routines、审查，都是把这四件事搬到不同的触发点。

下一节 §12 离开单个会话，看组织怎么统一设置、监控用量、控制成本。

§12 带团队用：设置统一了，用量看得见了，成本才管得住

Rolling Out Claude Code to a Team

一个人用顺手，不等于一个团队用得稳。这一节讲组织级设置、MCP 管控、用量监控、成本控制和推进顺序。它也是全书的最后一节。

12.1 先选账号类型，它决定后面有哪些管控手段

官方默认推荐 Claude for Teams 或 Enterprise。Claude Code 和 claude.ai 同一份按座位订阅，不用自己运维。API 优先的团队走 Claude Console。要沿用云的合规和账单，走 Bedrock、Agent Platform 或 Foundry。

有个坑容易漏。下面这些都需要 claude.ai 账号。只靠 Console 密钥或云厂商凭据用不了（见 §11）：

• 云端会话、routines。
• Code Review、Remote Control。
• Chrome 扩展。

价格不含税，受用量限制，官方可随时调整。还有个变化会让旧预算失效。从 v2.1.280（9 月 22 日）起，默认模型由 Sonnet 改成了 Opus 5.5。Pro 和 Team Standard 都受影响，见 §02。API 每百万 token 的输入/输出价如下。Opus 5.5 是 $4/$20，Sonnet 5.5 是 $2/$10。测算若建立在「默认是 Sonnet」之上，要重算。

12.2 托管设置把规矩放在开发者改不了的地方

托管设置的优先级高于开发者本地的任何配置。官方给了四种下发方式，优先级从高到低：

1. 服务端托管：claude.ai 管理后台，客户端启动时拉取，每小时刷新。
2. plist 或注册表策略。
3. 系统路径下的 managed-settings.json。
4. Windows 的 HKCU 注册表。

HKCU 不提权就能写，别当强制手段。

没有 MDM 的团队选服务端托管。它要 Teams 或 Enterprise 计划。还要 Owner 或 Primary Owner 角色。有 MDM 时端点托管更强，因为文件在系统层受保护。但它到不了 Anthropic 托管环境里的云端会话，两种都要配。下面是官方示例的核心：禁读密钥文件，禁用绕过权限，权限规则只认托管设置。

{
  "permissions": {
    "deny": ["Bash(curl *)", "Read(./.env)", "Read(./.env.*)", "Read(./secrets/**)"],
    "disableBypassPermissionsMode": "disable"
  },
  "allowManagedPermissionRulesOnly": true
}

Bash(curl *) 拦不住 /usr/bin/curl 或 sh -c。要不依赖命令文本的网络管控，用沙箱的 allowManagedDomainsOnly（见 §06）。数组类设置会跨来源合并，开发者能往里加，不能删托管的条目。上线前要知道的约束：

• 全组织统一，暂不支持按组配置
• 默认失败放行：拉取失败就用缓存，从没拉过则不带策略启动。要失败即退出，设 forceRemoteSettingsRefresh: true，代价是连不上 api.anthropic.com 时没人能启动
• 需要用户批准：涉及 shell 命令、Hooks 的设置会弹确认框。拒绝则 Claude Code 退出
• 不是安全边界：不受管的设备上，用户不用管理员权限就能绕过
• Console 密钥收不到：它属于另一个组织。CI 里用公司 Console 密钥的作业拿不到策略（见 §11）。换成授权给该组织的 CLAUDE_CODE_OAUTH_TOKEN，或在机器上放托管文件

验证有两个入口。/status 的 Setting sources 一行应出现 Enterprise managed settings。claude doctor 的 Managed settings (remote) 一行会说明拉取成功、失败还是被跳过（v2.1.248 起）。

该锁什么，官方 admin-setup 页有完整清单。第一批我会下发这几类：

• 权限与沙箱：allowManagedPermissionRulesOnly、permissions.disableAutoMode、sandbox.network.allowedDomains。真正的围墙是沙箱，拒绝 WebFetch 只拦住抓取工具，Bash 放行时 curl 照样出得去
• 插件与 Hooks：strictKnownMarketplaces、disableCommandPluginSources（不设时跟随 allowManagedHooksOnly）、allowManagedHooksOnly（见 §09）
• 模型与来源：availableModels、allowedProviders（v2.1.285 起）、minimumVersion。模型白名单直接决定成本上限

12.3 MCP 要管，因为它既是风险也是上下文开销

默认谁都能给自己的 Claude Code 接任意 MCP 服务器。每个服务器既是一份要信任的代码，又占上下文（见 §08）。管 MCP 一举两得。

细节有三处。managed-mcp.json 是独立文件，不能走服务端托管，要靠 MDM 放进系统路径。managedMcpServers 只收 https:// 的 http 和 sse 服务器。请求头谁能读托管设置谁就读得到，所以用共用凭据或让用户走 OAuth。被挡掉的服务器会从 /mcp 里直接消失，用户没有任何提示，上线限制前先通知大家。

12.4 监控用量：仪表盘看趋势，OpenTelemetry 看明细

重点看最后一行。走云厂商接入时，官方仪表盘看不到这部分用量。官方的说法是，只有 OpenTelemetry 能做到一件事。它能把每人的 token 和成本，近实时流进你自己的系统。仪表盘的贡献指标刻意保守，是低估值。

用托管设置给全员下发，开发者设的冲突端点会被自动删掉，没人能把数据改道。项目和本地 settings 里的遥测变量自 v2.1.282 起被忽略，仓库没法擅自开启：

{
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_LOGS_EXPORTER": "otlp",
    "OTEL_EXPORTER_OTLP_PROTOCOL": "grpc",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "http://collector.example.com:4317"
  }
}

验证方法：在后端查 claude_code.session.count，会话一开始就发。常用的还有 claude_code.token.usage 和 claude_code.cost.usage，它们能按 skill.name、plugin.name、agent.name 拆开，你能看到哪个 Skill、插件、子智能体在烧钱。成本指标是估算，正式账单以提供商为准。

隐私默认收紧。提示词只记长度，要内容设 OTEL_LOG_USER_PROMPTS=1。工具参数默认不记，审计 MCP 要设 OTEL_LOG_TOOL_DETAILS=1。原始文件内容不进指标和事件。user.email 只发到你的端点，不发给 Anthropic。云端会话读不到开发者本机的配置，要把变量写进服务端托管设置的 env。另外别把收集器令牌放进云环境变量，用这个环境的人都读得到。

安全审计可以盯 tool_decision、permission_mode_changed、mcp_server_connection 和 managed_settings_resolved 这几类事件。Claude Code 只吐原始事件流，告警要交给你的 SIEM。

12.5 成本要有数字、有上限，还要人人会省

先要个参照。官方给的企业部署数字：平均每人每活跃日约 $13，每人每月 $150 到 $250。90% 的用户每活跃日低于 $30。估自己的团队，官方建议先用小范围试点建基线。

Teams 和 Enterprise 的用量从座位额度里扣。按滚动五小时和每周两个窗口重置。与 claude.ai 聊天、Cowork 共用，超出部分走 usage credits。合同价和标价不同的话，用 modelPricing 托管设置填入费率（v2.1.243 起）。它只改显示的数字，不改 Anthropic 收的钱。

真正省钱的是开发者每天的习惯。官方《管理成本》列的办法，正好对应前面各节：

五行的共同点只有一个：让进入上下文的东西更少。token 成本和上下文大小成正比，管住上下文，就管住账单。

并行和自动化要另外算账。官方给的数字是：agent teams 的 token 用量，约为普通会话的 7 倍。前提是队友在 Plan 模式（§10）。Code Review 和 ultrareview 走独立的 usage credits。它们不占座位额度（§11）。

开发者来问限额时，先分清三类。「session limit」或「weekly limit」是座位窗口用完了，换模型救不了。只点名某个模型的限额例外。「spend limit」类提示是 usage credits 到了你设的上限，去管理设置里调。上下文或 auto-compact 警告不是限额，是该清上下文了。

12.6 推进顺序：先试点，再收紧，再铺开

下面的顺序是我根据官方几页文档排的，不是官方流程。

12.7 全书收束：两条线，其实是同一件事

这本书从头到尾只说了两件事。

第一条，上下文是最重要的资源。窗口会满，满了就会变笨。所以：

• CLAUDE.md 把反复要说的话固化下来（§05）。
• Skills 按需加载（§07）。
• 子智能体把探索关进别的窗口（§10）。
• /clear 和 /compact 回收空间（§04）。
• Hooks 把必须发生的事移出提示词（§09）。

到了这一节，同一条线变成了账单：管住进入窗口的东西，就是管住 token，也就管住了成本。

第二条，给它一个能验证工作的方法。测试、构建、截图，是你盯着的会话和你能走开的会话之间的分界（§03）。下面这些，都是把「验证」从你的眼睛挪到机器上：

• CI 里的退出码和结构化输出。
• 云端任务的转录抽查。
• Code Review 的严重度计数（§11）。

到了团队层面，托管设置、沙箱和监控是同一个道理的组织版。不靠每个人自觉，靠系统替你复核。

规模变了，原理没变。一个人在终端里，是你读 diff、跑测试。几个会话并行，是每个窗口只装自己的活，各有验收条件。CI 里，是固定上下文加退出码。整个团队，是统一的底线加遥测和仪表盘。你不必把书里的功能全用上。挑你最疼的那一个，给下一个会话放一条验证方法，再看窗口里装了什么。

现在，回到仓库，开一个会话。

附录 A 提示词与命令速查

Prompts and Commands Cheat Sheet

按任务查，不按字母查。每行末尾的「→ §0N」指向正文里讲透它的那一节。

A.1 好提示词的六个共同点

官方提示词库有五十多条提示词，骨架其实只有六种。记住它们，比背模板管用。

• 描述结果，不描述步骤。说你要什么，让它自己去找文件。→ §03
• 给它检查自己工作的办法。同一句话里写上「运行测试」「对比截图」，它才会迭代而不是交差。→ §03
• 指向参考。点名一个现成的文件或写法，让新代码和旧代码长得一样。→ §03
• 给可量化的目标。性能和覆盖率问题，写清指标和阈值，完成与否才没有争议。→ §03
• 直接给材料。把报错、日志、计划输出粘进去，或者用 @ 引用文件。它读的是原文，不是你的转述。→ §04
• 说明答案的形态。格式、长度、读者，都可以在提示词里直接点明。→ §03

给公共 API 加限流，并确保现有测试仍然通过
把 bundle 体积压到 200KB 以下，告诉我你删了什么
构建为什么失败？@build.log

这三句都没有文件路径，也没有步骤。它们都带着一个能验证的结果，或者一份原始材料。

A.2 常用提示词

下表改写自官方提示词库，保留原意，花括号处换成你自己的内容。加粗的五条是官方标为「从这里开始」的。

A.3 斜杠命令

命令只在消息开头才会被识别，名称后面的文字当作参数。Claude 正在回答时发的命令会排队，等这一轮结束再跑。不是每个命令对每个人都显示，要看平台、套餐和环境。

最常用的十五个，已在 §03 3.5 列过：/help、/init、/plan、/diff、/rewind、/resume、/clear、/compact、/context、/btw、/model、/usage、/permissions、/rename、/doctor。下表只收其余的。

A.4 命令行启动

A.5 键盘与输入前缀

附录 B 术语表

Glossary

读文档、报错和社区文章时最常撞见的词。按主题分组，不按字母排，每条末尾标出正文里讲它的那一节。

英文名全部保留，因为官方文档、界面和报错里出现的都是英文。本书统一译法有三处。subagent 叫子智能体，cloud session 叫云端会话，hook 叫钩子。Skill 一律写英文。如果你读到别处的「网页版」「子代理」「技能」，说的是同一个东西。

B.1 会话与代理循环

B.2 上下文与记忆

全书的主线在这一组。我的建议是先把前三条弄懂，后面的功能几乎都能挂回来。

B.3 权限与安全

B.4 扩展能力

B.5 运行方式与设备

B.6 已经改名的说法

旧文章里的词还在流传。搜官方文档时用右边的新名字。

附录 C 排错

Troubleshooting

按你看到的现象查。只收读者最常撞上的几十条，每条给出多半是什么原因、先做什么。

C.1 先跑这几条诊断

先让它自己体检一遍，比读报错快。

• /doctor：会话里体检安装、设置和上下文占用，你确认后才修。
• claude doctor：claude 起不来时在 shell 里跑，只读。
• /status：看版本、模型、账号，以及当前到底在用哪种凭据。登录类问题先看它。
• claude --safe-mode：关掉所有自定义项再启动。问题消失，凶手就在插件、MCP、钩子或 CLAUDE.md 里。→ §09
• /feedback：都不行，就把问题连同会话上下文报给 Anthropic。

C.2 装不上、找不到命令

最常见的四条已经在 §02 2.4 逐条讲过，按报错原文对号入座就行：

• command not found: claude，或 Windows 的 not recognized：安装目录不在 PATH 里。
• syntax error near unexpected token '<'、403、App unavailable in region：安装地址返回了网页或错误码。
• Windows 上 irm is not recognized、&& is not valid：PowerShell 与 CMD 的命令用串了。
• Failed to fetch version：网络挡住了下载地址。

下面两条是 §02 没有写的。

C.3 登不上、反复让登录

其余登录报错，都在 §02 2.4 的登录阶段清单里，按原文找：OAuth error: Invalid code、403 Forbidden、Request not allowed、Not logged in · Please run /login、OAuth token has expired。登录问题找不到原因，就用重置法：/logout，关掉 Claude Code，再重新 claude。

C.4 限额与服务端错误

Claude Code 遇到临时故障会自动重试，最多约 10 次，之后才报错。你看到的已经是重试过的结果。

C.5 上下文满了、越用越卡

C.6 用着不对劲

C.7 还是不行，求助时带上什么

先去官方 GitHub 仓库的 issues 里搜。要提新 issue，我的建议是带齐四样：

• 操作系统和 claude --version。
• 你跑的那条命令原样。
• 完整的报错原文。
• claude doctor 的输出。

问题出在账号本身，比如登录死循环、订阅不被识别，就别折腾安装了。登录 claude.ai，点左下角头像，选「Get help」联系支持。

附录 D 版本时间线与参考来源

Timeline and Sources

Claude Code 是周更产品。这里列出本书素材镜像之后的变化，以及每一类事实的出处。

D.1 镜像之后的版本时间线

本书的官方文档镜像抓取于 2026-08-26，当时官方周报只到 Week 28。下表补齐了此后到成稿日的变化。W29 至 W37 有官方周报。W38 至 W41 官方没有发布周报（对应页面不存在）。这几周的摘要是根据官方更新日志逐条整理的。

带 * 的四周为根据更新日志整理的非官方摘要。成稿时最新版本是 v2.1.296（2026-10-09）。

D.2 本书的素材构成

D.3 写作中发现的已失效说法

拿镜像和线上现状逐条比对，共发现 15 处已失效。影响最大的几条，本书一律按右栏写：

D.4 未能核实、需要你自己确认的

• Max 档的确切月价。定价页卡片只写「From $100」。对比表里的 $100 / $200 是附带的 API 额度，不是订阅价
• 各套餐的具体用量额度。官方页面只给倍数关系（如 Max 为 Pro 的 5 倍或 20 倍），没有绝对数字
• 非美元地区的价格。定价页只给美元

D.5 编写纪律

D.6 免责声明

本书为非官方社区手册，与 Anthropic 无隶属关系，不代表官方立场。

内容仅供学习参考。在公司代码库中使用 Claude Code 前，请遵守你所在组织的安全与合规规范。

产品功能、套餐与价格以 Anthropic 官方最新说明为准。文档：code.claude.com/docs。定价：claude.com/pricing。