AI蓝皮书：Claude Code 流程控制高级应用

我们终于学习完了上篇，关于Cladue Code的规则（CLAUDE.md、Rules）和技能（Skills），对于如何执行一个任务，已经有所了解。但我们可以继续优化整个执行流程，以支持更复杂的项目，以及节省更多的算力、时间，提升整个项目的执行效率。下面我们就继续根据官方博客的文章，学习剩余的四个流程。

一、Subagents （子实体）

1、什么是Subagents

如果说 Skills 是“教会 AI 怎么做一件事”，那 Subagents 就是“叫一个分身去独自做这件事”。
子实体是 Claude Code 启动的独立会话子进程，它拥有独立的上下文窗口，可以访问你指定的文件范围，执行完任务后把结果返回给主会话。

这样做有三个巨大好处：

• 隔离上下文：子实体只加载必要的文件，避免主会话被大量中间数据占满，大幅节省 token。
• 并行处理：你可以同时启动多个子实体处理不同的文件/任务，像开了多线程一样。
• 无状态干扰：子实体做完就销毁，它的思考过程不会污染主会话的记忆。

用我们上一篇教程的案例做比喻，子实体就是“勇者的队友”。他可以帮助勇者闯关、也可以帮助勇者制造武器、收集材料等等。实际上，所有这些事勇者自己也可以做，但是勇者要忙着练级，这些琐碎的事情交给队友（子实体）做更节省时间、精力，但是所有人的目的最终都是打败魔王。

通常来说，子实体不需要单独的配置文件。你可以在 CLAUDE.md、Rules、Skills 或者直接对话中，告诉 Claude Code 去调用子实体。常用的方式是在Skills里规定子实体任务，或者在对话中用自然语言指派。

2、案例实践

继续使用我们伟大的“COC人物卡”做例子。比如我们有 20 张角色卡需要整理。如果全在主会话里一张一张读取、清洗、输出，上下文会很快爆掉，而且只能串行操作。这时候我们可以设计两个子实体：

• 子实体 A：负责“读取单个角色卡并返回结构化 JSON 数据”。
• 子实体 B：负责“接收一组 JSON 数据，生成最终的 Excel 汇总文件”。

然后我们就可以在主会话中批量调用子实体 A 并行读取所有角色卡，最后将结果汇总交给子实体 B 输出。这样可以大幅度降低Token消耗，整理的效率也会有极大的提升。下面我们来实际编写一个带有子实体的skill，要注意的是，子实体无法读取整个项目的上下文，所以指令编写要完整、自洽。

---
name: coc-batch-sort
description: 当用户需要批量整理超过5张角色卡时，使用此技能。
---

# 批量角色卡整理（子实体版）

## 触发条件
用户表达“批量整理角色卡”或卡片数量 > 5。

## 执行流程

### 第一步：扫描与分派（子实体A）
1. 列出当前目录下所有 `.xlsx` 和 `.xls` 角色卡文件。
2. 对每一张角色卡，**启动一个子实体**执行读取任务。
   - 子实体指令示例：
     “读取文件 {文件路径}，提取角色名、玩家名、职业、力量、敏捷、意志、理智、幸运、技能列表。若存在基础值与成长值，计算最终值。以 JSON 格式返回结果，不要包含任何解释。”
3. 设置子实体的工作目录为本项目根目录，**只读访问**角色卡文件。

### 第二步：收集与汇总（子实体B）
1. 收集所有子实体返回的 JSON 数据。
2. 启动一个新的子实体，传入所有 JSON 数据，执行生成 Excel 任务。
   - 子实体指令示例：
     “根据提供的 JSON 列表，生成一个 .xlsx 文件。每个玩家一个 Sheet，表头用中文。若缺少理智或幸运，在首行红字标记‘⚠️ 缺失’。文件保存至 output/角色卡汇总_YYYYMMDD.xlsx。”

### 第三步：检查与报告
1. 检查 output/ 目录是否生成文件。
2. 向用户简要报告处理结果：共处理多少张卡，有无异常。

3、QA环节

Q：上述例子这么简单的案例是否有必要使用子实体，或者说Skill里面就已经可以采取分步描述处理文件，是否有必要启用子实体？
A：完全有必要。子实体就相当于多线程处理器。比如 20 张角色卡，如果没有子实体，Claude Code 只能按顺序读取第 1 张、第 2 张……一直到第 20 张，所有原始数据全堆积在主会话的上下文中，Token 极易爆炸，最后再一口气处理。而启用子实体后，Claude Code 会分批同时启动多个子实体（比如每次 3~5 个并行），每个子实体独立读取一张卡，把数据提炼成精简的 JSON，干完活就把内部记忆清空销毁，只把结果交回主会话。这不仅节省了大量时间，也无需母体一直积累token，节省了不少算力。

二、Hooks（钩子）

1、什么是Hooks

Hooks 在Claude Code中的地位很特殊，他完全不依赖AI本身的思维能力，而是一个固定的、强制触发的安全审核。当 Claude Code 执行到某个特定的动作时，会自动运行一段你写的脚本（Shell、Python 等），对操作进行拦截、记录、校验或附加处理。这个过程无法被AI本身打断，具有最高的执行优先级。

所有 Hooks 定义在项目的“.claude/hooks/”目录下，一个 JSON 配置文件（例如hooks.json）。它的基本结构如下：

{
  "hooks": [
    {
      "event": "PreToolUse",
      "tool": "Write|Edit",
      "command": "bash .claude/hooks/backup.sh",
      "description": "修改文件前自动备份"
    },
    {
      "event": "PostToolUse",
      "tool": "Write",
      "command": "python .claude/hooks/check_xlsx.py",
      "description": "生成xlsx后自动检查字段完整性"
    }
  ]
}

• event：PreToolUse（工具调用前）、PostToolUse（工具调用后）。
• tool：可以指定具体工具名，如 Write、Edit、Bash 等，也可以用 * 匹配所有。
• command：要执行的脚本命令。
• Hooks 脚本会收到环境变量，如 CLAUDE_EVENT、CLAUDE_TOOL_NAME、CLAUDE_FILE_PATH 等，可以据此编写复杂逻辑。

2、案例实践

接下来我们继续有请我们的常驻嘉宾COC人物卡”项目做例子，我们计划给他追加两个Hooks：

• 防止误改原始卡：在 Claude Code 尝试写入或编辑任何 .xlsx 文件前，先弹出警告并取消操作（因为是只读的原始卡）。
• 生成文件后自动校验：每次生成 Excel 后，自动运行一个 Python 脚本检查是否包含“理智”“幸运”等必填字段，否则返回错误。

脚本一： .claude/hooks/block_write_original.sh （比较简单在指令，可以使用Shell）

#!/bin/bash
FILE="$CLAUDE_FILE_PATH"
# 如果目标是原始卡文件（非 output/ 目录），则拒绝修改
if [[ "$FILE" != *"/output/"* ]] && [[ "$FILE" == *.xlsx ]]; then
  echo "❌ 安全拦截：禁止修改原始角色卡文件。如需生成汇总，请输出到 output/ 目录。"
  exit 1
fi
exit 0

脚本二： .claude/hooks/check_xlsx.py （较为复杂的指令，可以使用Python）

import sys
from openpyxl import load_workbook
import os

file = os.environ.get("CLAUDE_FILE_PATH")
if not file or not file.endswith(".xlsx"):
    sys.exit(0)

wb = load_workbook(file)
for sheet in wb.sheetnames:
    ws = wb[sheet]
    headers = [cell.value for cell in ws[1]]
    if "理智" not in headers or "幸运" not in headers:
        print(f"⚠️ 校验失败：Sheet '{sheet}' 缺少理智或幸运字段。")
        sys.exit(1)
print("✅ 字段校验通过。")

配置Hooks： .claude/hooks/hooks.json

{
  "hooks": [
    {
      "event": "PreToolUse",
      "tool": "Write|Edit",
      "command": "bash .claude/hooks/block_write_original.sh",
      "description": "拦截对原始角色卡的修改"
    },
    {
      "event": "PostToolUse",
      "tool": "Write",
      "command": "python .claude/hooks/check_xlsx.py",
      "description": "生成Excel后自动校验必填字段"
    }
  ]
}

完成配置后，Claude Code 会在每次即将修改文件前执行阻断检查，并在生成完 Excel 后立即校验。这样你就获得了一层“自动化监理”，再也不用担心 AI 无意中破坏原始数据。

3、QA环节

Q：.sh 文件执行报错“Permission denied”怎么办？
A：如果你是Linux或者macOS用户，创建 .sh 文件执行的时候可能会提示“Permission denied”错误，这是因为缺少权限导致的。可以在终端执行一次“chmod +x .claude/hooks/block_write_original.sh”指令赋予权限。如果 .sh 指令确实出现问题（特别是windows用户），直接换成Python执行也可以，Claude Code强大的自适应能力，不挑运行语言。

Q：为什么我 .py 文件也无法执行
A：其实第一篇教程BLOG主就有提醒，执行 .py 文件需要安装Python运行环境，建议回去第一篇教程看看如何安装。

Q：exit 0 / exit 1 分别是什么意思
A：这是两个常用的命令，exit 0 代表放行，Claude Code可以继续执行后面的内容；而 exit 1 则代表拦截，本次操作会被取消，这也是Hooks能实现最高级别阻断的方法。

三、Output Styles（输出风格）

1. 什么是Output Styles

你在用AI的时候肯定也遇到过，AI喋喋不休地输出你根本不在意的内容，你只想要结果。或者莫名其妙开始有英语/日语回答，又或者老喜欢分段、列点、做表格。使用“Output Styles”就可以让你自定义 Claude Code 的回答风格和格式，而不用每次都啰嗦地提醒“用中文回答”“不要解释”“用列表形式”等等。

这不同于 CLAUDE.md（那是底层的系统约束），Output Styles 更偏向于交互体验：比如让 AI 的输出更简洁，或符合某种报告模板。你可以在项目根目录创建 .claude/output-styles.md，或者使用命令 /output-styles 进入交互式配置。文件内容用 Markdown 描述期望的风格。

2、案例实践

建立文件： .claude/output-styles.md：

# 输出风格设定

- 语言：简体中文。
- 语气：直接、简洁，像跑团助手一样。
- 禁止：不要说“当然可以”“好的，我来帮你……”，直接给结果。
- 结构：使用符号“🧙 守秘人报告：”作为固定开头，再列出要点。
- 遇到异常或警告：一律使用 ⚠️ 表情 + 红色文字标记。

配置好之后，当你让 Claude Code 整理完角色卡并汇报，它的回复就会变成：

🧙 守秘人报告：
- 已处理 5 张角色卡
- 3 张完整，2 张缺少理智值，已在汇总表中红字标注 ⚠️
- 输出文件：output/角色卡汇总_20260731.xlsx

不再有多余的礼貌用语，一眼看清关键信息，非常适合频繁操作时使用。
如果你临时想切回详细解释模式，只需说“这次用详细说明的风格回答我”，它会临时覆盖 Output Styles 的设置。

理论上。。你也能让它扮演猫娘……

四、Append System Prompt（追加系统提示）

1. 什么是Append System Prompt

有时候，你并不想改动 CLAUDE.md（因为那是全局/项目的基本法），也不想专门写一个 Skills，只想在这次对话或某个指令里，临时追加一条系统级的限制。你当然可以直接用自然语言告诉系统，但是总有一些不确定性存在，这时候就轮到 Append System Prompt 登场了。它可以理解成：在已加载的所有规则之上，再叠加一层你的即时指令，优先级极高。使用 Append System Prompt 有两种方式：

第一种是在启动Claude Code的时候输入：

claude --append-system-prompt "本次所有生成的Excel文件命名必须加前缀 ‘v2_’。"

第二种更为直接，你可以直接在Claude Code中输入

/append

随后在弹出的编辑器中输入你需要追加的指令，比如“本次对话中，所有角色名都必须使用英文拼音，不要翻译成中文。这个追加会在当前会话一直生效，直到你关闭会话。”

2、案例实践

仍然回到我们的COC人物卡案例中，如果这次KP开的是一个日系模组，其中所有参团人物都有日文名字。为了增加沉浸感，我想让系统将人名翻译成日文，并标记罗马音。我不想修改为此修改CLAUDE.md 或 Rules，毕竟日系模组跑的不多，那么我只需要在整理卡片开始时，输入：

/append 本次任务中，所有 Excel 中的角色名称都翻译成日语，并标注罗马音。

然后再说“整理今天的角色卡”，Claude Code 就会用临时将本次的人名都翻译成日语。任务结束后，关闭会话，规则恢复原样，没有任何残留影响。

3、优先级问题

为了让大家心里有数，这里再补一张完整的优先级链条（越靠上越高）：

用户即时指令（含 /append）
 > Skills
  > Rules
   > CLAUDE.md（项目规则）
    > 全局 CLAUDE.md

所以，Append System Prompt 是你在不破坏任何原有结构的前提下，进行“紧急特权干预”的最好工具。

五：总结

其实BLOG主写这个的时候是很崩溃的，在刚撰写第一篇教程的时候，Codex还没有原生支持deepseek，结果刚写完第一篇，它支持了！对于程序员来说，Claude Code对复杂问题的处理仍然是优于Codex的，但是如果对一般的普通用户来说，让他处理一些简单的问题，执行一些简单的工作，Codex更高效、用的token更少，似乎也是个不错的选择。但不管怎么说，Claude Code的教程总算是告一段落，这个系列教程并没有聚焦直接塞你几个Skills文件，而是从原理上告诉你如何把控整个流程，准确理解Claude Code的工作原理，做到知其然也知其所以然。我们最后复习一次整个进阶教程：

• CLAUDE.md：设定项目“宪法”，告诉 AI 你是什么项目、基本约束。
• Rules：针对特定文件或路径的“专门法”，自动条件触发。
• Skills：可复用的“标准作业流程”，让操作一键执行。
• Subagents：派发任务的“分身”，处理海量数据而不炸上下文。
• Hooks：自动化“监理和传送带”，防范风险、节省人工检查。
• Output Styles：定制“说话方式”，让交互清爽高效。
• Append System Prompt：临时“最高指示”，灵活微调不受限。

将这七层灵活组合，你就可以把 Claude Code 从一个普通助手，调教成一个深度适配自己项目的智能代理人。如果有下一篇进阶教程，我们将继续探索使用Git进行多项目协作、自定义 MCP 工具以及如何把 Claude Code 嵌入你的日常 CI/CD 流程等内容。但是考虑到Codex的强势地位，很可能BLOG主会优先写那边的入门教程。

也非常欢迎各位留言分享你的skills，让这个教程继续丰满起来。