← 套装首页 Claude Code 实战指南 · 卷〇

Claude Code 实战指南：从上手到用好（橙皮书套装 · 卷〇）

Orange Book Series · 卷〇 · 2026-08-24 · 核验版本 2.1.241

第 0 章 · 10 分钟装上并跑通第一件事

Claude Code 实战指南：从上手到用好（橙皮书套装 · 卷〇 · 样章）

0.1 这一章只干一件事

让你在自己的电脑上，用十分钟完成「装好 → 登录 → 让它读你的项目 → 让它改一个文件」的完整闭环。读完这一章你应该手里有一次真实的、经过你批准的文件修改——这是后面所有章节的地基。

本章所有命令与界面行为均对照官方 quickstart 文档核验（2026-08-24），标注【官方文档】；版本相关说明对照官方 changelog 页核验，标注【官方 CHANGELOG】。

0.2 安装：一条命令（推荐原生安装）

官方推荐原生安装器，不依赖 Node.js，且能后台自动更新【官方文档】：

# macOS / Linux / WSL
curl -fsSL https://claude.ai/install.sh | bash

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

包管理器也可以：macOS 用 brew install --cask claude-code（注意 Homebrew 装的不自动更新，要自己 brew upgrade），Windows 用 winget install Anthropic.ClaudeCode（同样不自动更新）【官方文档】。想钉住旧版或走 npm 老路，npm install -g @anthropic-ai/claude-code 仍然可用。

装完验证：

claude --version
# 输出版本号 + (Claude Code)，例如：2.1.241 (Claude Code)

0.3 登录与启动

在你的项目目录里直接敲 claude，首次会引导你在浏览器里完成登录。账号类型四选一：Claude 订阅（Pro / Max / Team / Enterprise，推荐）、Console（API 预付费）、企业云平台（Bedrock / Google Cloud / Foundry）、组织自建网关【官方文档】。凭证会保存，之后不用再登；要换账号，在会话里敲 /login。

cd /path/to/your/project
claude

启动后你会在输入框上方看到版本号、当前模型和工作目录。敲 /help 看全部命令。

0.4 第一件事：让它读懂你的项目

直接用人话问。Claude Code 会自己去读需要的文件，你不用手动喂上下文【官方文档】：

这个项目是干什么的？
main 入口在哪？
解释一下目录结构

0.5 第一改：权限弹窗是你的方向盘

现在让它真改点东西：

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

它会找到合适的文件并展示改动，然后停下来问你——这就是权限弹窗。看清楚它要改什么，再选 Yes。这个「每次写文件、跑命令前问你」的机制是 Claude Code 的安全底座，第 3 章会专门讲透。

一个要知道的新事实：首个会话之后，Pro / Max / Team 计划的终端与 VS Code 会话默认进入 auto 模式——一个 AI 分类器替你审每个动作，多数编辑和命令不再弹窗；其他计划默认 Manual 模式。任何时候按 Shift+Tab 可以切换当前会话的权限模式【官方文档】。auto 模式不是免检——它有官方公布的 17% 漏放率，第 3 章细讲。

0.6 每天必用的五条命令

命令干什么
claude启动交互会话
claude "修一下构建报错"一次性任务
claude -c继续当前目录最近一次会话
/clear清空当前对话历史
/exit 或 Ctrl+D 两次退出

输入框里的三个高频符号：/ 唤起命令与技能列表、@ 引用文件（新版还可以 @另一个会话，第 11 章讲）、! 进入 shell 直通模式；Esc 打断当前回合【官方文档】。

0.7 本章验收

五个勾都打上，第 1 章见——我们将拆开你刚用过的这台机器，看看循环、工具、权限和 context 是怎么让你刚才那十分钟成为可能的。

本章信息保鲜期。 安装命令与默认权限模式是变动较快的区域。本章核验于 2026-08-24（Claude Code 2.1.241）；若你读到时界面行为不符，以 官方 quickstart 与 changelog 为准。

第 1 章 · 终端里的 Agent：使用者的心智模型

阿舟图解：把它当远程同事——说清楚目标、上下文、验收标准

Claude Code 实战指南：从上手到用好（橙皮书套装 · 卷〇）

1.1 一个循环，三个阶段

你给 Claude Code 一个任务，它不是「想好了再做」，而是进入一个循环：收集上下文 → 采取行动 → 验证结果，三个阶段混在一起滚动推进【官方文档】。问一个问题，可能只转半圈（只收集上下文）；修一个 bug，它会把三阶段反复转上几十次——跑测试、读报错、搜文件、改代码、再跑测试，每一步的结果决定下一步做什么。

这个循环里有两个角色：负责推理的模型和负责行动的工具。Claude Code 本身是套在模型外面的「harness」——它提供工具、管理上下文、给执行环境，把一个大语言模型变成一个能干活的 agent【官方文档】。

你也在这个循环里。任何时候按 Esc 可以立刻打断它——正在跑的工具会被取消，它停下等你指示；甚至不用打断，直接敲一行纠正发出去，它读完当前动作的结果后就会调整方向【官方文档】。「对话」不是修辞，是这个工具的真实交互形态：第一次没做对不用重来，继续说就行。

1.2 工具：它会什么，由工具表决定

没有工具的模型只能输出文字。Claude Code 的内置工具大致分五类【官方文档】：

类别能干什么
文件操作读文件、改代码、建新文件、重命名重组
搜索按模式找文件、正则搜内容、探索代码库
执行跑 shell 命令、起服务、跑测试、用 git
Web搜网页、抓文档、查报错信息
代码智能编辑后看类型错误、跳定义、找引用（需装对应插件）

之外还有编排类工具：派生 subagent、向你提问等。这解释了新手最常困惑的一件事——「它为什么不会做 X」多半是工具表里没有 X，而不是模型不够聪明。反过来，你装一个 MCP server 或 Skill，本质就是往这张表里加行（第 6–8 章）。

注意一个版本变化：Todo/Task 系列工具在 Opus 4.8、Sonnet 5、Fable 5、Mythos 5 及更新模型上已默认移除（v2.1.233），旧教程里「让 Claude 先写 todo 再干活」的流程在这些模型上不成立了；真要找回，设 CLAUDE_CODE_ENABLE_TODO_TOOLS=1【官方 CHANGELOG】。

1.3 它能碰到什么：权限边界

你在哪个目录敲 claude，它就能访问【官方文档】：你的项目文件（目录及子目录）、你的终端（任何你能跑的命令它都能跑）、你的 git 状态（当前分支、未提交改动、最近提交）、你的 CLAUDE.md 和自动记忆、以及你配置的扩展。

「任何你能跑的命令它都能跑」这句话的另一面是：它的爆炸半径就是你的爆炸半径。这就是为什么有权限系统——每次写文件、跑命令前的询问是底线。四种权限模式，Shift+Tab 循环切换【官方文档】：

模式行为
Auto分类器后台审每个动作，拦下危险的；Pro/Max/Team 的终端与 VS Code 会话默认模式
Manual改文件、跑命令前都问你
Accept edits改文件和 mkdir/mv 这类文件命令不问，其他命令仍问
Plan只探索、出计划，不动源文件

对信任的日常命令（如 npm test、git status），可以在 .claude/settings.json 里加白名单免除重复询问【官方文档】。权限规则的组织层级与写法见第 3 章和附录 B。

1.4 Context：它每回合「记得」什么

Context window 里装着：对话历史、读过的文件内容、命令输出、CLAUDE.md、自动记忆、已加载的 skill、系统提示【官方文档】。装得太满时它会自动压缩——先清旧的工具输出，再摘要对话；你的请求和关键代码片段会保留，但对话早期的细节指令可能丢失。所以持久的规矩要写进 CLAUDE.md，不要指望它「记住你三周前说过的话」。

三个立刻能用的习惯：

压缩救不了所有情况：如果单个文件或工具输出大到每次摘要完立刻又塞满，它会停止自动压缩并报错（thrashing），这时该重开会话而不是硬撑【官方文档】。

1.5 会话、分叉与后悔药

每个会话是独立的新 context——新会话不带旧会话的对话历史。会话以明文 JSONL 存在 ~/.claude/projects/ 下，因此可以续（claude -c / claude -r）也可以分叉（--fork-session 或 /branch 复制历史到新会话，原会话不动）【官方文档】。

文件改动自带后悔药：Claude 改文件前会做快照（checkpoint），改坏了按 Esc 两次回滚，或直接让它 undo。checkpoint 独立于 git，续会话后仍可用；但它只管文件——对数据库、API、部署这类远程副作用无能为力，那些靠权限模式管【官方文档】。

想在同一代码库上平行推进多条线：用 git worktree 开多个目录，每个目录一个会话【官方文档】。更进一步的跨会话协作是 2026 年的新大陆，见第 11 章。

1.6 一句话总结

Claude Code = 模型（推理）+ 工具表（能力边界）+ 权限（安全边界）+ context（工作记忆），套在一个随时可打断的三阶段循环里。后面每一章，都是在教你调教这四样东西中的一样。

1.7 本章验收

本章信息保鲜期。 权限默认值与工具表是活跃变动区（如 v2.1.232 的 fork 默认化、v2.1.233 的 Todo 工具移除）。本章核验于 2026-08-24（2.1.241）；行为不符时以官方 How Claude Code works 与 changelog 为准。

第 2 章 · CLAUDE.md：给它一张你项目的地图

Claude Code 实战指南：从上手到用好（橙皮书套装 · 卷〇）

2.1 为什么需要它

第 1 章说过：每个会话都是全新的 context，对话早期的话会被压缩冲掉。CLAUDE.md 就是对抗遗忘的正式机制——你在磁盘上写给它的长期指令，每个会话启动时自动进 context【官方文档】。

一个常被误解的事实：CLAUDE.md 的内容是作为一条 user message 在系统提示之后注入的，不是系统提示的一部分【官方文档】。它是「强烈建议」而不是「强制执行」——写得太泛、太长、自相矛盾，它就可能不照做。要硬性拦截某个动作，正确工具是 PreToolUse hook（第 7 章），不是往 CLAUDE.md 里写「永远不要」。

2.2 四个层级与加载顺序

层级位置给谁用
组织策略macOS: /Library/Application Support/ClaudeCode/CLAUDE.md；Linux/WSL: /etc/claude-code/CLAUDE.md；Windows: C:\Program Files\ClaudeCode\CLAUDE.mdIT/DevOps 统一下发，个人无法排除
用户级~/.claude/CLAUDE.md你所有项目的个人偏好
项目级./CLAUDE.md 或 ./.claude/CLAUDE.md团队共享，进版本库
本地级./CLAUDE.local.md（记得加 .gitignore）只属于你的本项目偏好

加载规则三条【官方文档】：

大 monorepo 里别的团队的 CLAUDE.md 老被带进来？用 claudeMdExcludes 按 glob 排除【官方文档】。

2.3 写出它真会照做的指令

官方给的四条经验法则【官方文档】：

什么时候该往里面加东西？官方判据：它第二次犯同一个错；code review 抓到它本该知道的事；你把上个会话纠正过的话又敲了一遍；新同事也需要同样的背景才能上手【官方文档】。

起步不用从零写：跑 /init，它分析你的代码库生成初稿（已有文件则提改进建议而非覆盖）；设 CLAUDE_CODE_NEW_INIT=1 可开交互式多阶段流程。从 Cursor/Copilot 搬家？/init 会读 .cursor/rules/、.github/copilot-instructions.md，v2.1.213 起还有 /import 一次性导入其他 agent 的配置【官方文档】【官方 CHANGELOG】。

2.4 模块化的两把刀：@import 与 rules

@import：在 CLAUDE.md 里写 @docs/git-instructions.md 就把那个文件并进来，可递归、最深 4 层；相对路径相对的是「写 import 的那个文件」而非工作目录；想只提路径不导入，用反引号包起来。注意：import 进来的内容启动时全部加载，省不了 context，只省组织。解析到工作目录外的 import 会弹批准框（防别人往共享项目里塞文件）【官方文档】。

仓库已有 AGENTS.md？CLAUDE.md 不读它，但一行 @AGENTS.md 即可让两边共用一份指令，下面再补 Claude 专属段落；或者直接 symlink【官方文档】。

.claude/rules/：把指令按主题拆成多个 md 文件。带 paths: frontmatter 的规则只在它读到匹配文件时才加载——这是真正省 context 的模块化方式【官方文档】：

---
paths:
  - "src/api/**/*.ts"
---
# API 开发规则
- 所有 endpoint 必须做入参校验
- 使用统一错误响应格式

个人通用规则放 ~/.claude/rules/（先于项目规则加载，项目规则优先）；跨项目共享一套规则用 symlink 链进各项目的 .claude/rules/【官方文档】。

2.5 自动记忆：它自己做的笔记

CLAUDE.md 是你写的，auto memory 是它写的——默认开启。它把值得跨会话记住的东西分四类存档：user（你的角色与偏好）、feedback（你给过的纠正）、project（代码里推不出来的项目动态）、reference（项目外的信息去哪找）；代码里能推出来的东西它不记【官方文档】。

机制要点【官方文档】：

想让它记什么，直接说「记住：这个项目用 pnpm 不用 npm」；想写进 CLAUDE.md，说「把这条加到 CLAUDE.md」。

2.6 本章验收（含一个本机对照实测）

本章信息保鲜期。 记忆系统是 2026 年迭代最快的区域之一（rules、自动记忆、/import 均为近几个小版本引入）。本章核验于 2026-08-24（2.1.241）；行为不符时以官方 memory 文档与 changelog 为准。

第 3 章 · 权限与工作流：让它放手干，但不出圈

阿舟图解：权限层层过闸——能自动过的自动过，拿不准的停下来问人

Claude Code 实战指南：从上手到用好（橙皮书套装 · 卷〇）

3.1 权限系统的全貌：模式 × 规则 × 提示

Claude Code 的每次工具调用要过三道闸：权限模式决定默认姿态，allow/ask/deny 规则做细粒度放行与拦截，都不命中时弹出提示问你。三者叠加，构成「默认保守、逐条开闸」的体系【官方文档】。

规则的优先级一句话记牢：deny > ask > allow。deny 是铁闸，连 bypassPermissions 模式都越不过它；它也不会再问你——直接拒绝【官方文档】。

3.2 六种模式，什么时候用哪种

模式行为适用场景
default（界面称 Manual）首次用某工具做某事时逐次询问日常开发的默认
acceptEdits文件编辑自动放行，其余仍询问你已盯过它的计划，进入批量改码阶段
plan只读分析，先出实施计划给你批，批准后才开始动手大改、陌生代码库、需求还不稳
auto（Auto Mode）由分类器模型自动判定每个动作的风险并放行/询问长任务无人值守；Anthropic 公布的内部数据：约 93% 动作被批准，提示率从 17% 降到 0.4%（见第 5 章成本讨论）
dontAsk不询问；命中 deny 之外但未 allow 的动作直接拒绝CI、自动化脚本——它自己当自己的看门人
bypassPermissions全部放行（deny 规则除外）仅限一次性容器/沙箱；官方界面直接标注「use with caution」

切换方式：会话内按 Shift+Tab 循环切换，或 /permissions 里选；启动时用 --permission-mode 指定；团队可经 managed settings 用 permissions.defaultMode 统一定默认【官方文档】。

3.3 规则语法：精确到参数级别

规则写作 Tool 或 Tool(specifier)，放在 settings 的 permissions.allow / ask / deny 数组里【官方文档】：

{
  "permissions": {
    "allow": [
      "Bash(npm run test:*)",
      "Read(//src/**)",
      "WebFetch(domain:docs.anthropic.com)"
    ],
    "deny": [
      "Bash(curl:*)",
      "Read(./.env)",
      "Read(~/.*)"
    ]
  }
}

要点【官方文档】：

3.4 提示框里藏着的四个功能

弹出的批准框不只是 Yes/No【官方文档】【官方 CHANGELOG】：

3.5 常见工作流组合

把模式串成一天的节奏，是这一章真正想交付的东西：

一个务实建议：先把 deny 清单写好再谈放权。Read(./.env)、Bash(git push --force:*)、Bash(rm -rf:*) 这一类铁闸进 settings.json（团队共享）或 settings.local.json（个人），之后开 auto/acceptEdits 才睡得着。

3.6 本章验收

本章信息保鲜期。 权限系统是近几个小版本改动密集区（auto 模式、Ctrl+E 风险解释、规则按仓库根归属均为近期引入）。本章核验于 2026-08-24（2.1.241）；行为不符时以官方 permissions 文档与 changelog 为准。

第 4 章 · Prompt 与上下文工程：管好它唯一的稀缺资源

阿舟图解：上下文是行李箱——空间有限，只带对完成任务有用的

Claude Code 实战指南：从上手到用好（橙皮书套装 · 卷〇）

4.1 一切技巧的总前提：context 是会贬值的资产

官方最佳实践页开篇就点明：绝大多数技巧源于同一个约束——context window 填满得很快，而且性能随填充度下降。每一轮对话、每一次文件读取、每一条命令输出都在占用它；一个调试会话轻松烧掉几万 token。快满时它会开始「忘记」早期指令、犯更多错【官方文档】。

所以本章所有内容都是同一个主题的不同侧面：让进入 context 的每个 token 都值回票价。用 /context 随时看占用；想持续盯着，可以配自定义 status line【官方文档】。

4.2 给它一个能自己跑的验收标准

这是官方列的第一条实践，也是回报最高的一条：给它一个可以自行运行、能读出成败信号的检查——测试套件、构建退出码、linter、截图对比。没有检查，「看起来做完了」就是它唯一的停机信号，你就成了人肉验收回路；有了检查，它会自己干活、跑检查、读结果、迭代到通过【官方文档】。

差好
「实现一个邮箱校验函数」「写 validateEmail：user@example.com 为 true，invalid 为 false，user@.com 为 false。实现后跑测试」
「把 dashboard 弄好看点」「[贴设计截图] 实现这个设计。完成后截图与原图对比，列出差异并修掉」
「构建挂了」「构建报这个错：[贴错误]。修复并确认构建通过。治根，别压制报错」

检查可以多硬，分四档【官方文档】：同一条 prompt 里要求它跑并迭代；设为 /goal 条件由独立评估器每轮复检（第 10 章）；写成 Stop hook 做确定性拦截（连续拦 8 次后系统会强制放行）；或让验证 subagent 用全新 context 反驳结论。另外让它出示证据（测试输出、命令回显、截图）而不是口头宣布成功——审证据比自己重跑快得多。

4.3 探索 → 计划 → 实现 → 提交

官方推荐的四阶段工作流【官方文档】：

但别教条：改 typo、加日志、改变量名这类一句话能说清 diff 的活，直接让它做。计划的开销只在「方案不确定、改动跨多文件、代码你不熟」时才值回来【官方文档】。

4.4 写具体：引用文件、点出范例、描述症状

它能推断意图，但读不了你的心。官方的对照表【官方文档】：

差好
「给 foo.py 加测试」「给 foo.py 写测试，覆盖用户登出的边界情况。不要用 mock」
「ExecutionFactory 的 API 为啥这么怪？」「翻 ExecutionFactory 的 git 历史，总结它的 API 是怎么演变成这样的」
「加个日历组件」「看首页现有组件怎么写的，HotDogWidget.php 是好例子。照这个模式做日历组件，可选月份、可前后翻页选年份。只用代码库已有的依赖」
「修登录 bug」「用户反馈会话超时后登录失败。查 src/auth/ 的认证流，重点看 token 刷新。先写一个能复现的失败测试，再修」

富内容输入同样重要【官方文档】：用 @ 引用文件（它先读再答）；直接粘贴/拖入截图；给文档 URL（常用域名进 permissions 白名单）；cat error.log | claude 把数据管进去；或干脆让它自己用 Bash/MCP 去取。模糊 prompt 不是禁区——探索期一句「这个文件你会怎么改？」反而能捞出你想不到的视角。

4.5 纠偏要早，context 要狠

最好的结果来自紧反馈回路【官方文档】：

压缩是自动的（接近上限时触发），但你可以更主动：/compact 专注 API 改动 带指令压缩；在 CLAUDE.md 里写「压缩时务必保留改动文件清单和测试命令」定制保留项；不需要留在历史里的随口一问用 /btw——答案不进对话历史，白问【官方文档】。

注意 checkpoint 的边界：只跟踪它用编辑工具做的改动，Bash 命令和外部进程改的代码不在快照内——它不是 git 的替代品【官方文档】。

4.6 把脏活外包给 subagent

既然 context 是根本约束，「读一大堆文件」的调研就不该发生在主会话里。一句「用 subagent 调查 X」，它在独立 context 里翻完代码只把结论摘要带回来【官方文档】。同理，实现完成后让一个全新 context 的 reviewer subagent 只看 diff 和你的验收标准挑缺口——它没被「写出这段代码的推理过程」污染，判断更独立。内置 /code-review 就是这个模式的成品（正确性审查）。提醒一句：被要求「找缺口」的 reviewer 总会找出点什么，指示它只报影响正确性和既定需求的问题，否则你会被拖进过度工程【官方文档】。

4.7 五个典型翻车模式

模式症状处方
大杂烩会话一个会话里塞三件不相干的事无关任务之间 /clear
反复纠正改了又错、错了再改两次失败后 /clear + 重写更好的初始 prompt
CLAUDE.md 过度规定写太长，真正重要的规则被淹没狠删；它不做指令也能做对的事就删掉或改写成 hook
信任-验证缺口实现看着像样但边界全漏永远提供可跑的验证；验证不了就不交付
无限探索「调查一下」不给范围，读了几百个文件限定范围，或交给 subagent

4.8 本章验收

本章信息保鲜期。 最佳实践页随版本持续更新（/btw、rewind 总结、/batch 等均为较新条目）。本章核验于 2026-08-24（2.1.241）；以官方 best-practices 页为最终口径。

第 5 章 · 省钱：prompt caching、模型选择与看不见的烧钱点

Claude Code 实战指南：从上手到用好（橙皮书套装 · 卷〇）

5.1 先有个数：别人花多少

Claude Code 按 token 计费（订阅套餐则吃额度）。官方公布的企业部署平均值：每活跃开发日约 $13，每人每月 $150–250，90% 的用户每活跃日低于 $30。个体差异极大，取决于模型选择、代码库规模、是否跑多实例与自动化【官方文档】。

自查工具：/usage 看当前会话 token 与本地折算金额（订阅用户看的是套餐用量条）；订阅用户还能看到归因分解——skills、subagents、插件、各 MCP server 各占百分之几，以及「长 context」「cache miss」这类占近期用量 10% 以上的行为标记。/insights 则生成一份 HTML 报告分析你的工作方式与摩擦点【官方文档】。

5.2 prompt caching：为什么有时慢且贵

每一轮请求都要重发完整 context（系统提示 + 项目上下文 + 全部历史 + 新消息）， caching 靠前缀精确匹配复用已处理部分——缓存命中的 token 按缓存读费率计费，约为标准输入费率的 10%【官方文档】。请求被组织成三层：

层内容何时变化
系统提示核心指令、工具定义、输出风格工具集变化、Claude Code 升级
项目上下文CLAUDE.md、自动记忆、rules会话启动、/clear、/compact 后
对话你的消息、它的回复、工具结果每一轮

前缀任何一处变动，其后全部重算。所以「哪些动作会炸掉缓存」直接等于「哪些动作贵」【官方文档】：

反过来这些动作安全：编辑仓库文件、会话中途改 CLAUDE.md（改动不生效也不炸缓存，下个 /clear 才加载）、改输出风格（同理）、切权限模式（opusplan 除外）、调用 skills 和命令、/recap、/rewind（截回已缓存的旧前缀，比 compact 便宜）、派生 subagent（父缓存不动）【官方文档】。

实操口径：会话开场就定好模型和 effort，把 /compact 留给任务之间的自然间歇，走错路用 /rewind 而不是 compact。

5.3 缓存寿命与「离开一会儿回来变慢」

缓存条目在闲置后过期：订阅套餐默认 1 小时 TTL；API key 与云厂商默认 5 分钟（1 小时 TTL 的缓存写入更贵，可用 ENABLE_PROMPT_CACHING_1H=1 开启；订阅额度耗尽转用 usage credits 时也会自动降回 5 分钟）。每次命中重置计时器，所以持续工作缓存一直热；离开超过 TTL，回来第一轮全量重算——这就是「走开一下回来变慢」的原因【官方文档】。

Pro/Max 恢复一个搁置很久的大会话时，它会提议从摘要恢复而非携带全量历史——接住这个提议【官方文档】。

5.4 八条经过官方背书的省 token 策略

  1. 任务之间 /clear：无关任务的陈旧 context 在之后每条消息上持续收租。先 /rename 再 clear，以后还能 /resume 找回【官方文档】
  2. 选对模型：Sonnet 胜任大多数编码任务且更便宜，Opus 留给复杂架构决策与多步推理；简单 subagent 任务在配置里写 model: haiku【官方文档】
  3. 削 MCP 开销：工具定义默认 deferred 已省不少；能用 CLI（gh/aws/gcloud/sentry-cli）就别挂 MCP——CLI 零工具清单开销；/mcp 关掉不用的 server【官方文档】
  4. 装 code intelligence 插件（强类型语言）：精确符号跳转替代 grep+读多个候选文件；语言服务器在编辑后自动报类型错误，省一轮编译【官方文档】
  5. 用 hook 预处理：别让它读一万行日志找错——PreToolUse hook 先 grep 出 ERROR 行，几万 token 变几百【官方文档】
  6. 把 CLAUDE.md 里的专项指令搬进 skills：CLAUDE.md 每会话必载，skills 按需加载；CLAUDE.md 目标 200 行以内【官方文档】
  7. 调 extended thinking：思考 token 按输出计费。简单任务用 /effort 降档；固定思考预算的模型可用 MAX_THINKING_TOKENS 压预算（自适应推理模型忽略非零预算，用 effort 级别）【官方文档】
  8. 啰嗦操作外包给 subagent：跑测试、抓文档、处理日志的冗长输出留在 subagent 的 context，主会话只收摘要【官方文档】

5.5 看不见的烧钱点：没人也在花

会话闲置时仍有这些后台消耗【官方文档】：

长会话用量爬升的两大主因：全量历史每轮都发（缓存命中也只是 10% 费率而不是 0）；缓存过期后的首轮全量重读【官方文档】。

agent teams 单独记一笔：teammate 跑 plan 模式时用量约为普通会话的 7 倍（每个成员独立 context）。控制法：teammate 用 Sonnet、团队保持小、spawn prompt 写聚焦、用完即关【官方文档】。

auto 模式也有成本维度：分类器替你审批后，Anthropic 公布的内部数字是约 93% 动作自动批准、提示率从 17% 降到 0.4%——省的是你的时间和长任务的中断成本，而不只是 token【官方博客】。

5.6 本章验收

本章信息保鲜期。 计费结构、TTL 默认值与归因分解都是高频变动区（usage credits、goal check-in 等均为近期版本引入）。本章核验于 2026-08-24（2.1.241）；金额以 claude.com/pricing 与 Claude Console 为准。

第 6 章 · Skills：把你的经验封装成它的能力

Claude Code 实战指南：从上手到用好（橙皮书套装 · 卷〇）

6.1 什么时候该写一个 skill

判据很简单：同一段指令、清单或多步流程，你粘贴第二次的时候；或者 CLAUDE.md 里某一节从「事实」长成了「流程」。与 CLAUDE.md 的本质区别是加载时机：CLAUDE.md 每个会话必载，skill 的正文只在被调用时才进 context——几百行的参考资料平时几乎零成本【官方文档】。

Skills 遵循开放的 Agent Skills 标准，可跨工具使用；Claude Code 在标准之上扩展了调用控制、subagent 执行、动态 context 注入等能力【官方文档】。旧的 .claude/commands/*.md 自定义命令已并入 skills，老文件照常工作，同名时 skill 优先。

6.2 最小可用 skill 与存放位置

一个 skill 就是一个目录加一个 SKILL.md：YAML frontmatter 告诉它何时用，正文是执行指令。目录名就是命令名【官方文档】：

~/.claude/skills/summarize-changes/SKILL.md
---
description: 总结未提交的改动并标出风险。当用户问改了什么、
  想要 commit message 或要求 review diff 时使用。
---

## 当前改动

!`git diff HEAD`

## 指令

用两三条要点总结上面的改动，然后列出注意到的风险
（缺失的错误处理、硬编码值、需要更新的测试）。
diff 为空就说明没有未提交改动。

其中 !`git diff HEAD` 是动态 context 注入：Claude Code 先执行命令、用输出替换该行，再把内容交给模型——它看到的是真实 diff 而不是命令本身【官方文档】。

位置路径作用域
企业级managed settings 目录组织内所有用户
个人级~/.claude/skills/<name>/SKILL.md你所有项目
项目级.claude/skills/<name>/SKILL.md本项目（进版本库共享）
插件级<plugin>/skills/<name>/SKILL.md插件启用处，命令带 plugin:skill 命名空间

同名冲突按来源裁决：企业 > 个人 > 项目；任意层级都能盖过同名内置 skill（但不接管其别名）。嵌套子目录的 .claude/skills/ 在它读到该目录文件时才加载，重名时以目录限定名出现（如 apps/web:deploy）。skill 目录可以是 symlink——跨项目共享一套 skill 就靠它【官方文档】。

改动热加载：编辑已有 skills 目录里的 SKILL.md 当前会话即生效；新建顶层 skills 目录需重启【官方文档】。

6.3 内容分两类：参考型与任务型

反向也有：user-invocable: false 表示只准它自动加载、不对你暴露命令，适合「旧系统背景知识」这类没有动作意义的纯知识【官方文档】。

正文要克制：skill 一旦加载，内容在会话剩余轮次里一直占 context，每行都是重复开销。写「做什么」，别叙述「为什么」；大参考文档拆成附属文件按需读，SKILL.md 控制在 500 行内【官方文档】。

6.4 常用 frontmatter 速查

字段作用
description它决定何时自动加载的唯一依据（与 when_to_use 合并后 1,536 字符截断）；关键场景写最前
disable-model-invocationtrue = 只能人手动触发；同时阻止预载进 subagent、阻止定时任务以它为 prompt 触发（v2.1.196+）
user-invocablefalse = 只准它自动用，你从 / 菜单看不到
allowed-tools调用当轮免批准这些工具（下一条消息即失效，只放行不收紧）
disallowed-toolsskill 激活期间从可用池移除这些工具
model / effortskill 激活期间临时换模型/推理档位，当轮生效不落盘
context: fork在 fork 出的 subagent context 里运行（默认后台；background: false 改同步等待，v2.1.218+）
pathsglob 限定只在操作匹配文件时自动加载（与 path rules 同格式）
hooksskill 被调用时注册、会话内持续的 hooks

参数用 $ARGUMENTS（整体）、$ARGUMENTS[0]/$0（按位）、或 frontmatter arguments: 声明命名参数。一条消息开头可以连叠多个 skill：/write-tests /fix-issue 123，尾随文本作为参数传给每一个（最多展开 1+5 个）【官方文档】。

6.5 三个高阶模式

动态注入：!`command` 在行内执行并替换；还可以用 ${CLAUDE_SKILL_DIR}、${CLAUDE_PROJECT_DIR}、${CLAUDE_SESSION_ID} 等变量引用随 skill 打包的脚本。配合 allowed-tools: Bash(${CLAUDE_SKILL_DIR}/scripts/render.sh *) 即可让自带脚本免批准运行【官方文档】。

fork 执行：context: fork 让 skill 在独立 context 跑——调研类 skill 的标配，主会话只收结论。可再配 agent: 指定 subagent 类型【官方文档】。

claude.ai 同步：在 claude.ai 为你的账号启用 skill 后，Cowork 与云端会话自动获得；本机其他会话需先跑一次 CLAUDE_CODE_SYNC_SKILLS=1 claude -p "..." 下载到 ~/.claude/skills/synced/。注意同步版在本机不执行 !` 命令、不附加 @ 引用文件（安全考虑）；上传到 claude.ai 的 skill 只允许标准六字段 frontmatter，多一个字段就硬报错【官方文档】。

6.6 生命周期与排错

6.7 本机验证示例

亲手验证「动态注入」与「目录名即命令名」（约 5 分钟）：

mkdir -p ~/.claude/skills/diff-risk
cat > ~/.claude/skills/diff-risk/SKILL.md <<'EOF'
---
description: 总结未提交改动并标出风险。
---

## 当前改动
!`git diff HEAD --stat`

用三条要点总结改动并列出风险；diff 为空就说明工作区干净。
EOF
# 进任意 git 仓库，改一个文件，然后：
claude   # 启动后输入 /diff-risk，或直接问「我改了什么？」

预期：它返回的统计与实际 git diff HEAD --stat 输出一致——证明注入的是命令执行结果而非模型臆测。

6.8 本章验收

本章信息保鲜期。 Skills 是当前迭代最快的功能面之一（fork 后台控制、堆叠调用、同步规则均为近几个小版本引入）。本章核验于 2026-08-24（2.1.241）；以官方 skills 文档为最终口径。

第 7 章 · Hooks：把「永远要」变成真的永远

Claude Code 实战指南：从上手到用好（橙皮书套装 · 卷〇）

7.1 为什么需要 hooks

CLAUDE.md 是「建议」，模型可以选择不听；hooks 是确定性脚本，在生命周期固定点位自动执行，零例外。凡是「每次都必须发生」的事——编辑后跑 lint、拦截对 migrations 目录的写入、提交前格式化——都应该写成 hook 而不是 CLAUDE.md 里的祈使句【官方文档】。

一个 hook 的三层结构：事件（什么时候触发）→ matcher（过滤条件，如只对 Bash 工具）→ handler（跑什么：shell 命令、HTTP 端点、MCP 工具、LLM prompt 或 subagent，共五种类型）【官方文档】。

7.2 事件地图：三种节奏

其余常用事件：PreCompact/PostCompact（压缩前后）、Notification（发通知时——接企业微信/钉钉提醒就在这里）、SubagentStart/Stop、InstructionsLoaded（CLAUDE.md 或 rules 进 context 时）、PermissionRequest/PermissionDenied、ConfigChange、FileChanged（盯指定文件变化）、WorktreeCreate/Remove、TeammateIdle（agent team 成员将闲置时）【官方文档】。

7.3 写一个真 hook：拦截 rm -rf

配置写在 settings JSON 的 hooks 字段（各层级位置见第 3 章）；脚本从 stdin 读 JSON，用退出码与 stdout 回话【官方文档】：

// .claude/settings.json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "if": "Bash(rm *)",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh", "args": [] }
        ]
      }
    ]
  }
}
#!/bin/bash
# .claude/hooks/block-rm.sh（需 chmod +x；解析 JSON 需要 jq）
COMMAND=$(jq -r '.tool_input.command')
if echo "$COMMAND" | grep -q 'rm -rf'; then
  jq -n '{
    hookSpecificOutput: {
      hookEventName: "PreToolUse",
      permissionDecision: "deny",
      permissionDecisionReason: "Destructive command blocked by hook"
    }
  }'
else
  exit 0   # 无裁决：走正常权限流程（注意：沉默 ≠ 批准）
fi

要点解读【官方文档】：

7.4 高频配方

五种 handler 类型里，command 之外还有：http（POST 到内网校验服务，响应体同 JSON 协议）、mcp_tool（调已连接 MCP server 的工具）、prompt（发单轮 prompt 让模型裁决，默认用快模型）、agent（派 subagent 带 Read/Grep/Glob 验证后裁决，实验性）【官方文档】。

需要异步？async: true 后台跑不阻塞；asyncRewake: true 在脚本 exit 2 时把它叫醒看失败输出【官方文档】。

7.5 安全与治理

7.6 本机验证示例

不用开 Claude Code 也能先验证 hook 脚本逻辑（脚本协议就是 stdin JSON → stdout JSON）：

mkdir -p /tmp/hook-test/.claude/hooks && cd /tmp/hook-test
# 写入 7.3 的 block-rm.sh 并 chmod +x，然后直接喂测试输入：
echo '{"tool_name":"Bash","tool_input":{"command":"rm -rf /tmp/x"}}' \
  | .claude/hooks/block-rm.sh
# 预期输出 permissionDecision: "deny"
echo '{"tool_name":"Bash","tool_input":{"command":"ls -la"}}' \
  | .claude/hooks/block-rm.sh; echo "exit=$?"
# 预期：无输出，exit=0（放行给正常权限流程）

再进 Claude Code 实际触发一次：让它执行 rm -rf /tmp/build-test，应被 hook 拒绝并显示「Destructive command blocked by hook」。

7.7 本章验收

本章信息保鲜期。 Hook 事件与字段在快速增加（FileChanged、PostToolBatch、asyncRewake 等均为近期新增）。本章核验于 2026-08-24（2.1.241）；事件全集与 JSON schema 以官方 Hooks reference 为准。

第 8 章 · MCP：给它接上你的工具和数据

Claude Code 实战指南：从上手到用好（橙皮书套装 · 卷〇）

8.1 什么时候该接一个 MCP server

判据：你正在从别的工具往对话里复制粘贴数据——issue 跟踪器、监控面板、数据库、设计稿。接上之后它直接读那个系统并动手，不再依赖你喂快照【官方文档】。MCP 是开放标准，server 不绑定 Claude Code；官方收录的连接器可在 Anthropic Directory 浏览，其中的远程 server 都能直接用 claude mcp add 接入。

安全前提：只接你信任的 server——会抓取外部内容的 server 带来 prompt injection 风险【官方文档】。

8.2 四种传输与添加命令

传输命令形态何时用
HTTP（推荐）claude mcp add --transport http notion https://mcp.notion.com/mcp云服务；支持 OAuth；唯一推荐用于远程
SSE（已弃用）claude mcp add --transport sse asana https://mcp.asana.com/sse只暴露 SSE 的老服务
stdio（本地进程）claude mcp add --transport stdio db -- npx -y @bytebase/dbhub --dsn "..."需要本机系统访问的工具/脚本
WebSocketclaude mcp add-json events '{"type":"ws","url":"wss://..."}'需要服务端主动推送的场景；不支持 OAuth

stdio 的两个坑【官方文档】：server 命令必须放在 -- 之后（否则 server 自己的 --port 之类会被 Claude Code 当成自己的参数解析）；--env 与 server 名之间要夹至少一个别的选项，否则名字会被读成键值对。Claude Code 会给 stdio server 的进程环境注入 CLAUDE_PROJECT_DIR（稳定项目根）。

从别的客户端的教程抄配置？URL → 远程；npx -y xxx → stdio；mcpServers JSON 块 → claude mcp add-json <name> '<内层对象>'（注意：有 url 没 type 的条目必须补 "type":"http"，否则被当作 stdio 而报错跳过）【官方文档】。

8.3 三个作用域与团队协作

scope存哪给谁
local（默认）~/.claude.json 按项目路径归档只有你自己、只在当前项目
project项目根 .mcp.json，进版本库全团队同一份配置
user~/.claude.json你所有项目

同名 server 多处定义时按 local > project > user 取最高优先的一份整体生效，字段不跨层合并。.mcp.json 支持 ${VAR} 与 ${VAR:-default} 环境变量展开——团队共享配置、密钥不进版本库就靠这个【官方文档】。

项目级安全闸：交互会话首次使用 .mcp.json 里的 server 前要批准；未信任文件夹里，签入版本库的 enableAllProjectMcpServers/enabledMcpjsonServers 一律忽略（v2.1.196 起），server 停在「Pending approval」。非交互 claude -p 与云会话无法弹批准框，直接加载——克隆陌生仓库后先看它的 .mcp.json 再跑 -p【官方文档】。

8.4 日常管理与排障

8.5 权限、hook 与插件里的 MCP

8.6 本机验证示例：手写一个 stdio MCP server 并打通协议

stdio server 的本质是「stdin/stdout 上说 JSON-RPC 的进程」，不用装任何 SDK 也能手写并离线验证协议握手：

cat > /tmp/mini-mcp.py <<'EOF'
import json, sys
def reply(i, result):
    sys.stdout.write(json.dumps({"jsonrpc":"2.0","id":i,"result":result})+"\n"); sys.stdout.flush()
for line in sys.stdin:
    msg = json.loads(line)
    m = msg.get("method")
    if m == "initialize":
        reply(msg["id"], {"protocolVersion":"2025-06-18",
            "capabilities":{"tools":{}},
            "serverInfo":{"name":"mini","version":"0.1"}})
    elif m == "tools/list":
        reply(msg["id"], {"tools":[{"name":"hello",
            "description":"Say hello","inputSchema":{"type":"object","properties":{}}}]})
    elif m == "tools/call":
        reply(msg["id"], {"content":[{"type":"text","text":"hello from mini-mcp"}]})
    # notifications（无 id）不回复
EOF
# 验证握手与工具发现（注意 initialize 后要发 notifications/initialized）：
{ echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"t","version":"0"}}}';
  echo '{"jsonrpc":"2.0","method":"notifications/initialized"}';
  echo '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'; } | python3 /tmp/mini-mcp.py

预期看到两行 JSON 回复：initialize 的 capabilities 与 tools/list 里的 hello 工具。协议通了之后，把它接进 Claude Code 只需一条：

claude mcp add --transport stdio mini -- python3 /tmp/mini-mcp.py
# claude mcp get mini 确认 ✔ Connected，/mcp 里应能看到 1 个工具

8.7 本章验收

本章信息保鲜期。 MCP 子系统近期迭代密集（v2 runtime、发现缓存、自动转后台、channel 均为近几个小版本引入）。本章核验于 2026-08-24（2.1.241）；协议细节以官方 MCP 参考与 modelcontextprotocol.io 为准。

第 9 章 · Subagents 与插件：把能力打包分发出去

Claude Code 实战指南：从上手到用好（橙皮书套装 · 卷〇）

9.1 Subagent：独立 context 的专科医生

什么时候定义一个：同类任务反复派生、且每次都带同一套指令。subagent 在自己的 context window 里跑，带自己的系统提示、工具集与权限，主会话只收结论——省 context（第 4、5 章）、强制约束（限制工具）、控制成本（路由到 Haiku）三件事一次到位【官方文档】。

内置的先认脸：Explore（只读代码搜索，v2.1.198 起继承主会话模型、API 上封顶 Opus）、Plan（plan 模式调研员）、general-purpose（全能兜底）。这三个会跳过 CLAUDE.md 与 git status 以保持轻量（仅 Explore/Plan）；自定义 subagent 默认都加载【官方文档】。

9.2 写一个自定义 subagent

一个 markdown 文件：frontmatter 配能力，正文就是系统提示。放在 .claude/agents/（项目级，进版本库共享）或 ~/.claude/agents/（个人级）。v2.1.198 起 /agents 不再开向导，直接让它帮你写文件即可【官方文档】：

---
name: security-reviewer
description: 审查代码安全漏洞。改完认证/输入处理相关代码后主动使用。
tools: Read, Grep, Glob, Bash
model: sonnet
memory: project
---
你是资深安全工程师。审查代码时关注：
- 注入类漏洞（SQL/XSS/命令注入）
- 认证与授权缺陷
- 代码中的密钥与凭据
给出具体行号与修复建议。审查中发现的反复出现的模式写入你的记忆目录。

关键字段【官方文档】：

字段作用
name / description必填。description 是它决定何时委派的唯一依据
tools / disallowedTools白名单 / 黑名单；支持 mcp__<server> 整服务器粒度。两者同设时先扣黑名单
modelsonnet/opus/haiku/全量 ID/inherit（默认继承主会话）
permissionMode独立权限模式；父会话是 auto 时此项被忽略（分类器同一套规则评估）
skills启动时把指定 skill 全文预载进 context
memoryuser/project/local 持久记忆目录，跨会话积累知识（推荐 project，可进版本库）
isolation: worktree在临时 git worktree 里跑，改动隔离；无改动自动清理
hooks只在该 subagent 存活期间生效的 hooks（Stop 自动转为 SubagentStop）
maxTurns / background / effort轮次上限 / 强制后台 / 推理档位

两个易踩的坑：后台 subagent（默认）的内置工具会被裁到只读+读写核心集；tools 列表全部拼错/不存在时 subagent 直接启动失败并报出无法解析的条目（v2.1.208 起，之前是带零工具空跑）。文件改动会被监视热加载，但新建的 agents 目录要重启会话才被监视【官方文档】。

9.3 插件：把 skills/agents/hooks/MCP 打成一个包

判断标准：只在 .claude/ 里自己用 → standalone；要分享给团队或社区、要版本化 → 插件。插件就是带 .claude-plugin/plugin.json 清单的目录，组件目录一律在插件根（最常见错误就是把 skills/ 塞进 .claude-plugin/ 里）【官方文档】：

my-plugin/
├── .claude-plugin/plugin.json   # 只有清单进这个目录
├── skills/<name>/SKILL.md      # 命令变成 /my-plugin:<name>
├── agents/*.md                  # 自定义 subagents
├── hooks/hooks.json             # 事件钩子
├── .mcp.json                    # 捆绑 MCP servers
├── .lsp.json                    # 语言服务器（代码智能）
├── monitors/monitors.json       # 后台监视器
├── bin/                         # 启用期间加入 Bash PATH
└── settings.json                # 默认设置（当前仅 agent 等少数字键）

本地开发测试用 claude --plugin-dir ./my-plugin（也接受 .zip；--plugin-url 测远程包），改完 /reload-plugins 热加载；提交社区市场前跑 claude plugin validate ./my-plugin 本地预检【官方文档】。

分发路径：自建 marketplace（一个 git 仓库即可，团队内部用私有仓库）→ /plugin marketplace add <org/repo> → /plugin install xxx@marketplace。Anthropic 维护两个公开市场：claude-plugins-official（官方策划）与 claude-community（社区审核制，经 claude.ai 或 Console 表单提交，审核通过后钉在特定 commit SHA、CI 自动跟随你的新提交）【官方文档】。

安全须知：插件 subagent 的 hooks/mcpServers/permissionMode 字段会被忽略（防捆绑提权）；项目级插件的组件经 workspace trust 闸；企业可用 managed settings 强制启用/禁用插件【官方文档】。

9.4 从 standalone 迁移到插件

官方推荐路径【官方文档】：建插件目录与清单 → 把 .claude/commands|agents|skills 拷到插件根 → hooks 从 settings.json 搬进 hooks/hooks.json（格式相同）→ --plugin-dir 测试 → 删掉 .claude/ 里的原件（项目/个人级同名定义优先于插件，不删会盖过插件版；skills 因命名空间不同会两份并存）。

9.5 本机验证示例

验证「插件结构 + 命名空间 + frontmatter 可解析」，不需要任何安装：

mkdir -p /tmp/my-plugin/.claude-plugin /tmp/my-plugin/skills/hello
cat > /tmp/my-plugin/.claude-plugin/plugin.json <<'EOF'
{ "name": "my-plugin", "description": "demo", "version": "1.0.0" }
EOF
cat > /tmp/my-plugin/skills/hello/SKILL.md <<'EOF'
---
description: Greet the user warmly.
---
Greet the user named "$ARGUMENTS" warmly.
EOF
# 1) 清单合法 2) frontmatter 可解析：
python3 -c "import json; json.load(open('/tmp/my-plugin/.claude-plugin/plugin.json')); print('manifest ok')"
python3 -c "
import re
s = open('/tmp/my-plugin/skills/hello/SKILL.md').read()
m = re.match(r'---\n(.*?)\n---', s, re.S)
assert m and 'description:' in m.group(1), 'frontmatter missing'
print('frontmatter ok')"
# 3) 有 claude CLI 时实测加载（命令应为 /my-plugin:hello）：
#    claude --plugin-dir /tmp/my-plugin

有 CLI 的机器上再跑 claude plugin validate /tmp/my-plugin，预期 ✔ Validation passed。

9.6 本章验收

本章信息保鲜期。 插件与 subagent 子系统迭代密集（记忆、隔离、监视器、社区市场均为近几个小版本引入/变更）。本章核验于 2026-08-24（2.1.241）；以官方 subagents 与 plugins 文档为最终口径。

第 10 章 · 无人值守：/goal、/loop 与定时任务

Claude Code 实战指南：从上手到用好（橙皮书套装 · 卷〇）

10.1 让会话自己跑下去的三种方式

区别在于「谁启动下一轮」【官方文档】：

方式下一轮何时开始何时停
/goal上一轮结束时；或后台工作挂着时 check-in 到期评估模型判定条件达成 / 不可能达成；或出现必须你修的错误；或你 /goal clear
/loop时间间隔到点你叫停，或它判断活干完了
Stop hook上一轮结束时你的脚本或 prompt 说了算

/goal 本质是一个会话级的 prompt 型 Stop hook 封装；与 auto mode 互补——auto mode 消除每工具提示，/goal 消除每轮提示。两者叠加才是完整的无人值守【官方文档】。

10.2 /goal：条件驱动的自治循环

用法一句话：/goal test/auth 下全部测试通过且 lint 干净。设置即开工，不需要另发 prompt；状态栏显示 ◎ /goal active 与已运行时长。每轮结束后，条件与对话被发给一个小快模型评估器（API 上默认 Haiku），返回三种裁决：未达成（带着理由继续下一轮）、达成（清除并记录）、不可能达成（清除并记录失败原因）【官方文档】。

写好条件的三个要点【官方文档】：

运行机制里你该知道的【官方文档】：

10.3 会话外的调度：Routines 与桌面定时任务

/goal 和 /loop 都要有一个开着的会话。想「笔记本合上也照跑」，用调度【官方文档】：

典型配方：夜间 backlog 整理（定时 + issue 连接器）、告警分诊（监控工具调 API 触发，自动开修复草稿 PR）、PR 例行评审（GitHub 触发器 + 团队清单）、文档漂移巡检（每周扫已合并 PR）【官方文档】。

10.4 成本与护栏提醒

无人值守 = 没人盯着烧 token。回收前几章的护栏：goal 条件里写轮次上限；评估 token 走小快模型、通常可忽略，但每轮主对话照常计费；定时任务每次触发带全量 context（第 5 章）；长时间无人值守跑在 auto mode 并配好 deny 清单（第 3 章）【官方文档】。

10.5 本章验收

本章信息保鲜期。 /goal 与 routines 都是 2026 年新引入且快速演进的特性（check-in 机制在 v2.1.234/236/239 连续调整）。本章核验于 2026-08-24（2.1.241）；以官方 goal 与 routines 文档为最终口径。

第 11 章 · 并行编排：Agent View、Agent Teams 与跨会话协作

Claude Code 实战指南：从上手到用好（橙皮书套装 · 卷〇）

11.1 并行方案选型地图

官方给出的并行手段全景，按「你要自己协调多少」排序【官方文档】：

方案本质适用
Subagents（第 9 章）单会话内的委派，结果回主 context聚焦的一次性子任务
Worktrees同一仓库的多个检出，各开一个会话互不冲突的并行修改
Agent viewclaude agents 一屏管理多个后台会话派发多个独立任务，只在需要时介入
跨会话消息会话之间互发消息（v2.1.224 起）两个已有工作流之间的协作
Agent teams一个 lead 会话 + 多个 teammate 会话，共享任务清单、互发消息需要讨论与自协调的复杂工作（实验性）
Dynamic workflows脚本编排几十到几百个 subagent（第 12 章）大规模、可重跑的编排

质量向的组合拳也值得一提：Writer/Reviewer 双会话——一个写实现，另一个在全新 context 里只看 diff 挑毛病，再把评审意见喂回 Writer。全新 context 的评审者不会偏袒自己刚写的代码【官方文档】。

11.2 Agent View：一屏指挥所有后台会话

claude agents 打开（research preview，界面与快捷键可能变化）。核心循环【官方文档】：

典型一天：派发「修这个 bug」「审这个 PR」「查这个 flaky test」三行，自己去别的窗口干活，某行亮 Needs input 再回来。

11.3 Agent Teams：会互相讨论的会话组

实验性、默认关闭：设 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1（settings.json 的 env 或环境变量）才会启用；未设时不会建任何团队目录、也不会派生 teammate【官方文档】。

与 subagent 的本质区别【官方文档】：

SubagentsAgent teams
通信结果返回给调用者teammate 之间直接互发消息
协调主 agent 全权管理共享任务清单 + 消息自协调
独立 context是是，且每个 teammate 是完整 Claude 实例
token 成本低（只摘要回主 context）高（每成员独立实例；plan 模式下约为普通会话 7 倍，见第 5 章）
最佳场景只要结果的聚焦任务需要互相挑战、讨论、分工的复杂工作

最适合的场景：多角度调研互搏、新模块每人认领一块、竞争性假设调试、跨前后端的联调改动。顺序性任务、同文件编辑、强依赖链的工作用单会话或 subagent 更划算【官方文档】。

注意事项：v2.1.178 起派生 teammate 不再需要先建团队；启用后 Claude 可能自行把「命名的 subagent」升级为 teammate——不想要这行为可以关掉对应倾向；非交互 -p 模式不派生 teammate；成本控制的四条（Sonnet 做 teammate、团队保持小、spawn prompt 聚焦、用完即关）见第 5 章【官方文档】。

11.4 跨会话消息与 worktree 隔离

不需要完整团队时，两个独立会话可以互发消息协作（如「前端会话」通知「后端会话」接口已定稿）。成本提醒：消息送达即在被送达会话里开新一轮（带全量 context），crossSessionInbound: hold 可改为暂存（第 5 章）【官方文档】。

并行的物理隔离靠 worktree：每个会话/子代理在独立检出里干活，改动不打架；subagent 定义里 isolation: worktree 一行即可（第 9 章），桌面应用也按此组织多会话【官方文档】。

11.5 本章验收

本章信息保鲜期。 Agent view 是 research preview，agent teams 是实验特性，两者界面与行为都可能随版本变化。本章核验于 2026-08-24（2.1.241）；以官方 agent-view 与 agent-teams 文档为最终口径。

第 12 章 · Dynamic Workflows 与 CI 集成：把编排变成代码

Claude Code 实战指南：从上手到用好（橙皮书套装 · 卷〇）

12.1 Dynamic Workflows：谁拿着计划

一条 JS 编排脚本，由它（而不是 Claude 逐轮决定）驱动几十到几百个 subagent：脚本持有循环、分支与中间结果，Claude 的 context 里只落最终答案。脚本由 Claude 按你的任务描述来写，运行时在后台执行，会话保持响应【官方文档】。

与前面各章形态的分界线【官方文档】：

谁决定下一步中间结果在哪可重复的是什么规模
Subagents / SkillsClaude 逐轮Claude 的 context定义/指令每轮几个
Agent teamslead 逐轮共享任务清单团队定义少数长跑同伴
Workflows脚本脚本变量编排本身几十到几百个 agent

编排代码化还带来质量模式：让独立 agent 互相反驳彼此的发现再上报，或多角度起草计划再权衡——比单跑一遍更可信。可用性：v2.1.154+，全部付费套餐与 API、Bedrock/Agent Platform/Foundry 可用；Pro 需在 /config 的 Dynamic workflows 行开启【官方文档】。

12.2 跑起来：三种入口与审批

审批与权限【官方文档】：CLI 每次运行前展示计划阶段，可选「运行 / 本项目不再询问 / 查看原始脚本（Ctrl+G 进编辑器）/ 取消」。会话权限模式只控制启动提示；workflow 派生的 subagent 一律跑在 acceptEdits 并继承你的工具白名单——不在白名单里的 shell/web/MCP 调用仍可能中途问你，长任务前先把命令加白名单。

运行中用 /workflows 看进度：每阶段的 agent 数、token 量、耗时，可下钻到单个 agent 的 prompt 与最近工具调用；p 暂停、x 停单个或整个、r 重启单个、s 保存为命令【官方文档】。

12.3 保存、复用与分发

跑得满意的 workflow 按 s 存成命令：项目位 .claude/workflows/（进版本库共享）或个人位 ~/.claude/workflows/；之后用 /<name> 直接跑。保存支持 args 参数传入（脚本里以全局 args 读取结构化数据，免解析）。跨团队分发就打进插件的 workflows/ 目录，以 /<plugin>:<name> 调用【官方文档】。

四个经典 prompt 形状（直接抄改）：全库同问题审计（每文件一 agent + 对抗核验）、修到检查通过为止（跑 tsc → 修 → 循环至通过或连续两轮无进展）、并行大迁移（每文件独立副本隔离改动）、PR 全文件评审后汇总去重排序【官方文档】。

12.4 CI 里的 Claude Code：GitHub Actions 与自托管

官方 Action（anthropics/claude-code-action）让它在你的仓库工作流里跑：PR/issue 评论里 @claude 即可让它分析代码、实现改动、推 commit；也可以对任意 GitHub 事件自动跑指定 prompt【官方文档】。

12.5 本章验收

本章信息保鲜期。 Dynamic workflows（v2.1.154 引入）与 GitHub Actions 集成都在快速演进（关键词行为、保存路径规则、评审落点均为近期版本变更）。本章核验于 2026-08-24（2.1.241）；以官方 workflows 与 github-actions 文档为最终口径。

附录 · 速查与信源

Claude Code 实战指南：从上手到用好（橙皮书套装 · 卷〇）

附录 A · 命令与快捷键速查

命令/键作用章节
/init · /import生成 CLAUDE.md 初稿 / 导入其他 agent 配置2
/memory · /context浏览编辑自动记忆 / 查看 context 占用2、4
Shift+Tab循环切换权限模式（default→acceptEdits→plan）3
/permissions查看与管理 allow/ask/deny 规则3
Ctrl+E / Tab（提示框内）风险解释 / 附评论批准3
Esc · Esc Esc · /rewind打断 / 回溯到 checkpoint（对话、代码或两者）4
/clear · /compact [指令] · /btw清空 / 带指令压缩 / 不留历史的提问4
/rename · /resume · --continue会话命名与恢复4
/usage · /insights · /usage-credits用量与归因 / 工作方式报告 / 额度管理5
/model · /effort切模型 / 调推理档（注意都炸缓存）5
/<skill> · /skills调用 skill / 浏览 skill 清单6
/hooks只读浏览当前生效 hooks7
claude mcp add|list|get|remove · /mcpMCP server 管理与认证8
/plugin · /reload-plugins · --plugin-dir插件市场 / 热加载 / 本地测试9
claude plugin validate插件发布前预检9
/goal [条件] · /goal clear · Ctrl+O设目标 / 清除 / 看评估理由10
/loop · /schedule会话内重复执行 / 创建 routine10
claude agents打开 agent view 管理后台会话11
/workflows · /deep-researchworkflow 进度面板 / 内置深度调研12
claude -p "..." · --output-format stream-json非交互模式与流式 JSON 输出4、10
/doctor · /verify · /code-review环境自检 / 对照运行中的应用验收 / 全新 context 评审 diff2、4

附录 B · settings.json 高频键速查

键作用章节
permissions.allow / ask / deny规则数组，deny > ask > allow3
permissions.defaultMode默认权限模式3
permissions.disableBypassPermissionsMode禁用 bypass 模式（含 subagent frontmatter 里的声明）9
hooks事件 → matcher → handler 三层7
disableAllHooks全局停 hooks（管不住 managed 层）7
claudeMdExcludes按 glob 排除上游 CLAUDE.md2
enabledMcpjsonServers / disabledMcpjsonServers.mcp.json server 批准/拒绝（未信任文件夹里被忽略）8
disableBundledSkills · skillOverrides关内置 skills（/doctor 除外）/ 单个关停6
crossSessionInbound: "hold"跨会话消息暂存不即送5、11
autoMemoryEnabled自动记忆开关（关掉则 subagent memory 也失效）2、9

环境变量高频项：ENABLE_PROMPT_CACHING_1H（1 小时缓存 TTL）、MAX_MCP_OUTPUT_TOKENS（MCP 输出上限）、CLAUDE_CODE_GOAL_CHECKIN_MINUTES（goal check-in 间隔，0 关闭）、CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS（agent teams 开关）、DISABLE_AUTOUPDATER（控制升级时机）、MAX_THINKING_TOKENS（固定思考预算模型的预算上限）【官方文档】。

settings 文件层级：managed（企业）→ 命令行 --settings → 项目 .claude/settings.local.json → 项目 .claude/settings.json → 用户 ~/.claude/settings.json；前者优先于后者【官方文档】。

附录 C · 问题排查决策树

附录 D · 信源书目（全部为官方渠道）

使用建议。 本书所有时效性论断都标注了核验日期。当你读到本书时若行为不符，请以上述官方页面与 changelog 为准——它们才是唯一持续更新的口径。