Claude Code 的 Plugin、Skill、Hook、Subagent、Agent Team 与 Workflow

一、先用一个“软件开发公司”的故事理解

假设你开了一家软件开发公司：

• Claude 是负责思考的工程师；
• Claude Code 是整家公司，包括办公环境、工具、管理制度；
• Tool 是工程师手里的工具，例如读文件、改代码、运行命令；
• Skill 是操作手册，告诉工程师“这类任务应该怎么做”；
• Hook 是门卫和检查员，在关键操作前后进行检查；
• Subagent 是临时请来的专业助手；
• Agent Team 是一个真正的项目小组，成员有独立任务，还能直接互相沟通；
• Workflow 是写成 JavaScript 的自动调度程序，可以批量安排大量助手；
• MCP 是公司连接外部系统的接口；
• Plugin 是一个可以安装的工具箱，把操作手册、专业助手和检查规则打包在一起；
• Marketplace 是下载这些工具箱的应用商店。

先记住最重要的一句话：

Plugin 负责打包，Skill 负责教方法，Hook 负责强制检查，Subagent 负责完成独立子任务，Agent Team 负责多人协作，Workflow 负责大规模自动调度。

---

二、Claude Code 的核心：不断循环的“思考—行动—检查”

普通聊天模型只能回答文字。

Claude Code 不一样，它可以使用工具：

• 读取文件；
• 搜索代码；
• 修改代码；
• 运行测试；
• 执行命令；
• 查询网页；
• 调用外部服务；
• 启动其他 Agent。

它的工作过程大致如下：

用户提出任务
    ↓
Claude 思考需要知道什么
    ↓
读取文件、搜索代码
    ↓
Claude 判断应该怎么修改
    ↓
调用工具修改代码
    ↓
运行测试检查结果
    ↓
如果有问题，继续修改
    ↓
确认完成后回答用户

这个过程叫 Agent Loop，也就是“智能体循环”。

例如你说：

帮我修复登录失败的问题

Claude Code 可能会：

1. 搜索登录相关文件；
2. 阅读认证代码；
3. 运行测试；
4. 找到错误原因；
5. 修改代码；
6. 再次运行测试；
7. 如果仍然失败，继续调查；
8. 最后告诉你修复了什么。

Claude Code 的 Plugin、Hook、Subagent、Agent Team 和 Workflow，全部建立在这个循环之上。

Claude Code 的基础工作原理

---

三、Plugin：一个可以安装的“扩展工具箱”

3.1 Plugin 不是一种单独的能力

很多人会误以为 Plugin 是一种新的 AI 能力。

其实不是。

Plugin 更像一个安装包。它可以把多种扩展能力打包在一起，例如：

• Skills：操作手册；
• Commands：可以输入的 /命令；
• Agents：专业 Subagent 定义，也可以作为 Agent Team 的成员角色；
• Hooks：自动检查规则；
• MCP：外部系统连接；
• LSP：代码语义分析；
• Monitor：后台监控程序；
• 可执行脚本；
• 输出风格和主题。

所以 Plugin 的主要作用是：

把一整套 Claude Code 扩展能力打包、安装、升级和分享。

3.2 一个 Plugin 的目录

一个代码质量检查 Plugin 可能是这样：

quality-gate/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   └── review/
│       └── SKILL.md
├── agents/
│   ├── security-reviewer.md
│   └── test-reviewer.md
├── hooks/
│   └── hooks.json
├── scripts/
│   ├── validate-edit.mjs
│   └── run-lint.mjs
├── .mcp.json
└── .lsp.json

其中：

• plugin.json：Plugin 的说明书；
• skills/：教 Claude 怎样完成任务；
• agents/：定义专业助手；
• hooks/：定义什么时候自动检查；
• scripts/：Hook 需要执行的程序；
• .mcp.json：连接外部服务；
• .lsp.json：连接代码语言服务器。

3.3 plugin.json 做什么

示例：

{
  "name": "quality-gate",
  "displayName": "Quality Gate",
  "version": "1.0.0",
  "description": "代码审查和质量检查工具",
  "skills": "./skills/",
  "agents": "./agents/",
  "hooks": "./hooks/hooks.json",
  "mcpServers": "./.mcp.json",
  "lspServers": "./.lsp.json"
}

它告诉 Claude Code：

• Plugin 叫什么；
• 当前版本是多少；
• Plugin 有哪些组件；
• 到哪里寻找 Skill、Agent 和 Hook；
• 是否依赖其他 Plugin。

3.4 Plugin 是怎样安装的

安装过程可以理解为：

从 Marketplace 找到 Plugin
        ↓
下载 Plugin
        ↓
检查配置文件是否合法
        ↓
复制到本地缓存目录
        ↓
读取 Skill、Agent、Hook 等组件
        ↓
把这些组件注册到 Claude Code
        ↓
当前会话可以使用这些能力

Marketplace 安装的 Plugin 一般会放到：

~/.claude/plugins/cache/

Claude Code 不直接使用远程仓库里的文件，而是先复制到本机的版本缓存。

这样做有几个好处：

• 不同版本可以同时存在；
• Plugin 升级时，不会破坏正在运行的旧会话；
• Plugin 不能随意通过 ../ 访问安装目录外的文件；
• 更容易进行版本检查和安全检查。

Plugin 内部如果要引用自己的文件，通常使用：

${CLAUDE_PLUGIN_ROOT}

如果要保存升级后仍然保留的数据，则使用：

${CLAUDE_PLUGIN_DATA}

因为 Plugin 更新后，安装目录可能改变，但数据目录可以继续保留。

3.5 为什么 Plugin 名称里经常有冒号

假设两个 Plugin 都提供一个叫 review 的 Skill。

如果都叫：

/review

就会冲突。

所以 Plugin Skill 通常带有命名空间：

/quality-gate:review
/security-tools:review

Plugin Agent 也类似：

quality-gate:security-reviewer

冒号前面是 Plugin 名称，后面是 Skill 或 Agent 名称。

3.6 Plugin 会不会一次性占用大量上下文？

通常不会。

Claude Code 会尽量采用“需要时再加载”的方式：

• Skill 名称和简介会先告诉 Claude；
• Skill 的完整内容只在真正使用时加载；
• Agent 的完整提示词只进入对应 Subagent；
• Hook 不触发时通常不占用模型上下文；
• MCP 工具定义也可以延迟加载。

这就像一本很厚的工具书：

目录先放在桌上，真正需要某一章时再翻开。

Claude Code Plugin 技术参考

3.7 Plugin 能不能直接定义一个 Agent Team？

目前，Plugin 可以提供 Agent 定义，但不会把一个正在运行的 Agent Team 直接打包进去。

原因是两者属于不同层次：

Plugin 中的 Agent 定义
    = “安全审查员应该是什么角色”

运行中的 Agent Team
    = “这次任务请安全审查员、测试工程师和架构师一起工作”

Plugin 负责提供可重复使用的“角色模板”。真正执行任务时，Team Lead 再根据需要选择这些角色，组建本次 Agent Team。

也就是说：

• Plugin 可以提供 security-reviewer、test-runner 等角色；
• 同一个角色既能作为普通 Subagent 使用，也能成为 Agent Team 成员；
• Team 的成员名单、任务状态和通信消息属于运行时数据，不是 Plugin 的固定内容。

---

四、Skill：教 Claude“这类事情应该怎么做”

Skill 可以理解为一份操作手册。

例如：

---
description: 检查当前代码改动中的风险
disable-model-invocation: true
allowed-tools: Read Grep Bash(git diff *)
---

请检查当前代码改动。

当前差异：

!`git diff HEAD`

请输出：

1. 必须修复的问题
2. 重要风险
3. 可以改进的地方

用户可以输入：

/review

Claude Code 就会加载这份操作手册。

4.1 Skill 和普通提示词有什么区别

普通提示词只在当前对话中有效。

Skill 可以：

• 保存在文件中；
• 重复使用；
• 提交到代码仓库；
• 分享给团队；
• 自动判断什么时候需要加载；
• 通过 /命令 手动调用；
• 携带脚本和参考资料；
• 在独立 Subagent 中运行。

4.2 自动触发和手动触发

Skill 的 description 会告诉 Claude：

什么情况下应该使用这个 Skill？

例如：

description: 当用户要求检查代码安全问题时使用

如果不希望 Claude 自动运行，可以设置：

disable-model-invocation: true

这类设置很适合：

• 发布；
• 部署；
• 提交代码；
• 发送消息；
• 修改生产环境。

因为这些操作不应该由 Claude 自己突然决定执行。

4.3 动态内容注入

Skill 中可以写：

!`git diff HEAD`

Claude Code 会先执行命令，然后把命令结果放进 Skill。

实际过程是：

读取 SKILL.md
    ↓
执行 git diff HEAD
    ↓
把代码差异放进 Skill
    ↓
将完整内容交给 Claude

这样 Claude 看到的不是一条死板的操作说明，而是带有当前真实数据的任务。

4.4 Skill 也可以交给 Subagent 执行

Skill 可以设置：

context: fork
agent: Explore

意思是：

不要在主对话中执行这份 Skill，而是启动一个独立 Agent 去执行。

这样大量搜索结果和日志不会占满主对话。

Claude Code Skill 文档

---

五、Hook：站在关键路口的“门卫”和“检查员”

5.1 为什么需要 Hook

你可以在 CLAUDE.md 中写：

不要修改 .env 文件

但这仍然是一条给模型看的文字要求。

模型可能因为：

• 上下文太长；
• 指令冲突；
• 判断错误；
• 提示注入；

而没有遵守。

Hook 则是在执行层进行检查。

例如：

Claude 准备修改 .env
        ↓
PreToolUse Hook 被触发
        ↓
Hook 发现目标是 .env
        ↓
返回 deny
        ↓
修改操作被真正阻止

因此：

提示词是“希望 Claude 遵守”，Hook 是“系统实际执行检查”。

5.2 Hook 的基本结构

Hook 一般有三层：

事件 Event
    ↓
匹配条件 Matcher
    ↓
处理程序 Handler

例如：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "node",
            "args": [
              "${CLAUDE_PLUGIN_ROOT}/scripts/validate-edit.mjs"
            ]
          }
        ]
      }
    ]
  }
}

意思是：

1. 在工具运行前触发；
2. 只检查 Edit 和 Write；
3. 启动 validate-edit.mjs；
4. 根据检查结果决定是否允许。

5.3 常见 Hook 事件

会话事件

• SessionStart：会话开始；
• SessionEnd：会话结束；
• ConfigChange：配置发生变化；
• PreCompact：准备压缩上下文；
• PostCompact：上下文压缩完成。

用户输入事件

• UserPromptSubmit：用户刚提交提示词；
• UserPromptExpansion：用户输入的 Skill 或命令准备展开。

工具事件

• PreToolUse：工具执行前；
• PermissionRequest：准备向用户申请权限；
• PostToolUse：工具执行成功后；
• PostToolUseFailure：工具执行失败后；
• PostToolBatch：一批并行工具全部结束后。

Subagent 事件

• SubagentStart：Subagent 启动；
• SubagentStop：Subagent 准备结束。

任务事件

• TaskCreated：任务创建；
• TaskCompleted：任务准备完成；
• TeammateIdle：Agent Team 成员准备进入空闲状态。

文件和工作区事件

• FileChanged：文件发生变化；
• CwdChanged：工作目录变化；
• WorktreeCreate：创建独立工作区；
• WorktreeRemove：删除独立工作区。

5.4 Hook 可以执行什么

Hook 有五种主要类型。

1. Command Hook

运行本地程序：

{
  "type": "command",
  "command": "node",
  "args": ["./check.mjs"]
}

适合：

• 检查文件路径；
• 运行格式化；
• 记录日志；
• 检查测试结果。

2. HTTP Hook

把事件发送到 HTTP 服务：

{
  "type": "http",
  "url": "https://policy.example.com/check"
}

适合企业统一的权限和审计平台。

3. MCP Tool Hook

调用已经连接的 MCP 工具：

{
  "type": "mcp_tool",
  "server": "security",
  "tool": "scan_file"
}

4. Prompt Hook

让模型做一次简单判断：

{
  "type": "prompt",
  "prompt": "判断当前任务是否真的已经完成：$ARGUMENTS"
}

5. Agent Hook

启动一个可以读文件、搜索代码的验证 Agent：

{
  "type": "agent",
  "prompt": "运行测试并确认所有测试都通过：$ARGUMENTS"
}

5.5 Hook 怎样阻止操作

Command Hook 主要通过退出码和 JSON 返回结果。

退出码：

• 0：成功，继续；
• 2：阻止；
• 其他值：通常只是报告错误，但不会阻止。

这里有一个很容易踩坑的地方：

exit 1 通常不会阻止操作，真正要阻止时应使用 exit 2。

也可以返回结构化 JSON：

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "不允许修改生产环境配置"
  }
}

除了拒绝，还可以：

• allow：允许；
• ask：要求用户确认；
• defer：交给正常权限系统判断；
• updatedInput：修改工具参数；
• additionalContext：给 Claude 增加说明。

5.6 Hook 在工具调用中的位置

完整顺序通常是：

Claude 决定调用工具
        ↓
PreToolUse Hook
        ↓
权限和沙箱检查
        ↓
必要时询问用户
        ↓
工具真正执行
        ↓
PostToolUse 或 PostToolUseFailure
        ↓
工具结果返回 Claude

需要特别注意：

• PreToolUse 可以在执行前阻止；
• PostToolUse 发生时操作已经完成，不能撤销；
• 同一事件的多个 Hook 可能并行执行；
• 不要依赖“Hook A 一定比 Hook B 先运行”；
• 如果必须保证顺序，应写进同一个处理脚本。

Claude Code Hook 完整参考

---

六、Subagent：拥有独立“脑容量”的专业助手

6.1 为什么需要 Subagent

假设主 Agent 要检查一个大型项目。

它可能需要：

• 搜索几百个文件；
• 阅读大量代码；
• 运行测试；
• 查看很长的错误日志。

如果所有内容都放进主对话，主 Agent 的上下文很快就会被占满。

于是 Claude Code 可以启动 Subagent：

主 Agent：
请你调查认证系统，只需要告诉我最后结论。

Subagent：
搜索文件
阅读代码
运行测试
分析日志
整理结果

最后只把摘要返回给主 Agent

大量中间信息留在 Subagent 的上下文中，不会全部塞进主对话。

6.2 Subagent 的定义文件

示例：

---
name: security-reviewer
description: 检查认证、权限、密钥和注入风险
model: sonnet
tools: Read, Grep, Glob, Bash
disallowedTools: Edit, Write
maxTurns: 20
skills:
  - secure-coding
isolation: worktree
---

你是一名安全审查员。

只报告有明确代码证据的问题。

每个问题必须说明：

1. 文件位置
2. 数据从哪里进入
3. 危险操作在哪里发生
4. 攻击需要什么条件
5. 风险等级

这里规定了：

• Agent 的名字；
• 什么时候使用；
• 使用哪个模型；
• 可以使用哪些工具；
• 不可以使用哪些工具；
• 最多工作多少轮；
• 预先加载哪些 Skill；
• 是否使用独立工作区；
• 它扮演什么角色。

6.3 Subagent 是怎样启动的

主 Agent 会调用内置的 Agent Tool：

主 Agent 判断任务适合委派
        ↓
生成一份任务说明
        ↓
调用 Agent Tool
        ↓
Claude Code 创建新的 Subagent
        ↓
Subagent 获得独立上下文
        ↓
Subagent 独立工作
        ↓
返回最终结果
        ↓
主 Agent 继续处理

用户也可以明确要求：

让 security-reviewer 检查登录代码

或者使用 Agent 的 @ 提及方式。

6.4 Subagent 会继承什么

普通 Subagent 通常会获得：

• 自己的系统提示词；
• 父 Agent 写的任务说明；
• 项目的 CLAUDE.md；
• Git 状态；
• 预加载的 Skill；
• 当前工作目录信息。

但它通常看不到：

• 主对话的完整聊天历史；
• 主 Agent 之前所有的思考过程；
• 主 Agent 阅读过的全部文件内容；
• 主对话中所有工具输出。

因此它既能了解项目规则，又不会复制整个主对话。

6.5 上下文隔离不等于文件隔离

这是一个非常重要的区别。

默认情况下：

• 主 Agent 和 Subagent 使用不同的上下文；
• 但它们可能仍然操作同一个项目目录。

因此，如果两个 Subagent 同时修改同一个文件，仍然可能发生冲突。

真正需要文件隔离时，可以设置：

isolation: worktree

Claude Code 会为这个 Subagent 创建独立的 Git Worktree。

可以把它理解为：

上下文隔离：每个人有自己的脑子和笔记本
文件隔离：每个人还有自己的一份项目副本

6.6 前台和后台 Subagent

• 前台 Subagent：主 Agent 等它完成；
• 后台 Subagent：主 Agent 可以继续做其他事情；
• 后台 Subagent 需要权限时，确认请求会回到主会话；
• 主 Agent 可以在运行过程中继续给它发送指示。

6.7 Subagent 能不能再启动 Subagent

这个机制近期变化很快。

历史上，Claude Code 曾允许 Subagent 继续派生 Subagent，最大深度为 5。

但从 v2.1.217 开始：

• 默认不允许嵌套派生；
• 如确实需要，可通过 CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH 开启；
• 默认最多同时运行 20 个 Subagent；
• 普通会话默认最多通过 Agent Tool 启动 200 个 Subagent。

这样做是为了避免：

1 个 Agent 启动 10 个
10 个再各自启动 10 个
最后突然出现 100 个或 1,000 个 Agent

Claude Code v2.1.217 发布说明

---

七、Agent Team：由多个独立 Agent 组成的协作小组

7.1 为什么有了 Subagent，还需要 Agent Team？

Subagent 很像主工程师临时请来的助手：

主 Agent 分配任务
        ↓
Subagent 独立工作
        ↓
Subagent 把结果交回主 Agent

这种方式很适合目标清楚、只需要最终结果的任务，例如：

• 调查某个模块；
• 运行一组测试；
• 审查一份代码；
• 查找一个错误的原因。

但有些复杂任务不仅需要“分工”，还需要成员之间讨论和协调。例如：

• 前端改了接口调用方式，需要后端成员及时调整接口；
• 安全审查员发现问题后，需要和实现人员讨论修复方案；
• 两个研究员得到相反结论，需要直接交换证据；
• 测试人员发现问题后，需要马上通知负责该模块的开发者。

如果所有信息都必须经过主 Agent 转发，主 Agent 很容易变成一个忙不过来的“传话员”。

Agent Team 就是为这种场景准备的。

Subagent 强调“把一项任务交出去”，Agent Team 强调“让多个成员共同完成一个项目”。

7.2 Agent Team 的四个核心部分

一个 Agent Team 通常包含四部分：

Agent Team
├── Team Lead：团队负责人
├── Teammates：多个团队成员
├── Task List：共享任务表
└── Mailbox：成员之间的消息系统

Team Lead

Team Lead 通常就是创建团队的主 Claude Code 会话。

它负责：

• 理解总目标；
• 把目标拆成任务；
• 选择和启动团队成员；
• 处理任务之间的依赖；
• 汇总所有成员的成果；
• 决定最终输出。

Teammates

Teammate 是独立运行的 Claude Code 实例。

每个成员都有：

• 自己的上下文窗口；
• 自己的任务；
• 自己的工具调用过程；
• 自己的会话状态；
• 向其他成员发送消息的能力。

它不只是主 Agent 内部的一次短暂工具调用，而更像团队里一位可以持续工作的成员。

Task List

共享任务表记录：

• 有哪些任务；
• 每个任务由谁负责；
• 哪些任务正在进行；
• 哪些任务已经完成；
• 哪些任务必须等待其他任务完成。

例如：

任务 1：分析旧接口              已完成
任务 2：实现新接口              进行中
任务 3：修改前端调用            等待任务 2
任务 4：补充端到端测试          待领取

当任务 2 完成后，原本被阻塞的任务 3 就可以继续。

Mailbox

Mailbox 是成员之间的消息系统。

例如，后端成员可以直接告诉前端成员：

新接口已经完成，响应字段从 user_name 改成了 displayName。

安全审查员也可以直接告诉实现人员：

当前接口缺少资源所有权检查，请在查询后验证 owner_id。

这就是 Agent Team 和普通 Subagent 最明显的区别：

普通 Subagent 主要向调用它的 Agent 汇报；Agent Team 成员可以互相通信。

7.3 Agent Team 是怎样启动的？

Agent Team 通常通过自然语言创建。

例如：

组建一个 Agent Team 完成登录系统重构：

- auth-researcher 负责调查现有认证流程；
- backend-developer 负责后端改造；
- frontend-developer 负责登录页面；
- test-engineer 负责集成测试；
- 由主会话担任 Team Lead。

运行过程大致是：

用户提出复杂任务
        ↓
Team Lead 拆分任务
        ↓
创建共享 Task List
        ↓
启动多个 Teammate
        ↓
成员领取或接受任务
        ↓
成员独立工作并互发消息
        ↓
任务完成后更新共享状态
        ↓
Team Lead 汇总结果

Agent Team 当前仍属于实验性功能。使用时通常需要启用：

CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

实验性功能表示它的界面、限制和配置方式以后仍可能变化。

7.4 Agent Team 的上下文怎样工作？

每个 Teammate 都有自己的上下文窗口。

成员启动时通常会获得：

• 项目的 CLAUDE.md；
• 项目可用的 Skill 和 MCP；
• Team Lead 给它的启动任务；
• 必要的团队和任务信息。

但它不会自动得到 Team Lead 的全部聊天历史。

可以把它理解为：

Team Lead 给新成员一份任务说明和项目资料，
而不是把自己从早上到现在说过的每一句话都复制过去。

这样可以减少无用上下文，也让每个成员专注于自己的任务。

7.5 Agent Team 和自定义 Agent 定义怎样配合？

你可以把已有的 Subagent 定义作为团队角色重复使用。

例如 Plugin 或项目中已经有：

security-reviewer
test-runner
backend-developer

创建 Agent Team 时，可以要求某个 Teammate 使用这些角色。

角色定义中的以下内容通常很有价值：

• system prompt；
• 模型选择；
• 工具允许列表；
• 专业职责。

但要注意：一个 Agent 定义作为普通 Subagent 使用，和作为 Teammate 使用，并不保证所有字段都完全相同地生效。Team 模式还会额外提供任务管理和通信工具。

7.6 Agent Team 会不会发生文件冲突？

会。

“每个成员有独立上下文”不代表“每个成员自动拥有独立代码副本”。

如果两个成员同时修改同一个文件，仍可能出现：

• 覆盖彼此的改动；
• 修改基于过期内容；
• 产生难以合并的结果。

因此组建 Agent Team 时，最好让成员负责不同的模块：

前端成员：负责 apps/web/
后端成员：负责 services/api/
测试成员：负责 tests/
安全成员：只读审查，不直接修改

需要更强隔离时，可以结合 Git Worktree，让不同成员在不同代码副本中工作。

7.7 Agent Team 如何使用 Hook 做质量门禁？

Agent Team 可以和 Hook 配合。

最常见的两个事件是：

• TeammateIdle：成员准备停止工作或进入空闲状态；
• TaskCompleted：成员准备把任务标记为完成。

例如 TaskCompleted Hook 可以检查：

测试是否通过？
要求的输出文件是否存在？
任务说明中的验收条件是否满足？

如果 Hook 返回阻止，任务就不会被标记为完成，成员会收到原因并继续修改。

这相当于团队中的验收流程：

成员说：“我完成了。”
        ↓
Hook 检查验收标准
        ↓
不符合要求
        ↓
任务保持未完成
        ↓
成员继续工作

7.8 什么时候适合使用 Agent Team？

适合：

• 多个模块可以并行开发；
• 不同成员需要频繁交换信息；
• 需要让不同观点互相质疑；
• 任务时间较长，成员需要持续工作；
• 前端、后端、测试、安全需要协同；
• 希望用户可以直接查看或指导某个成员。

不太适合：

• 任务非常简单；
• 所有步骤必须严格按顺序执行；
• 多个成员会频繁修改同一个文件；
• 只需要一个简短调查结果；
• 通过一段固定脚本就能完成大批重复任务。

最后一种场景通常更适合 Workflow。

7.9 Agent Team 的成本

Agent Team 中的每个成员都是独立 Claude Code 实例，都有自己的上下文和模型调用。

所以成员越多：

• token 消耗越高；
• 同时执行的工具越多；
• 协调成本越高；
• 文件冲突风险越大。

不要因为任务看起来复杂，就立即组建十几个成员。通常应该先问：

这些成员是否真的可以独立工作？他们是否必须互相沟通？

如果答案是否定的，普通 Subagent 或单 Agent 往往更简单。

Agent Team 官方文档

---

八、Workflow：让程序来调度大量 Subagent

8.1 为什么普通 Subagent 还不够

使用少量 Subagent 时，可以由主 Agent 逐个安排：

先让 Agent A 调查
读取 A 的结果
再让 Agent B 验证
读取 B 的结果
最后总结

问题是，每个结果都会回到主 Agent 的上下文。

如果任务包含几百个文件，主 Agent 很快就会被大量结果淹没。

Dynamic Workflow 的解决办法是：

Claude 先写一段 JavaScript 调度程序，然后由专门的 Workflow Runtime 执行。

8.2 Workflow 的运行过程

用户提出一个大型任务
        ↓
Claude 分析应该怎样拆分
        ↓
Claude 生成 JavaScript 工作流
        ↓
用户确认是否运行
        ↓
Workflow Runtime 在后台执行
        ↓
启动大量 Subagent
        ↓
中间结果保存在 JavaScript 变量中
        ↓
不同 Agent 互相检查结果
        ↓
最后只返回汇总结论

普通 Subagent 模式中，Claude 自己一步步决定下一步。

Workflow 模式中，JavaScript 脚本负责：

• 循环；
• 分支；
• 并发；
• 分批处理；
• 保存中间结果；
• 组织验证阶段。

8.3 一个简单的 Workflow

export const meta = {
  name: 'audit-routes',
  description: '检查所有接口是否缺少权限验证',
}

const found = await agent(
  '列出 src/routes/ 下所有 TypeScript 文件',
  {
    schema: {
      type: 'object',
      required: ['files'],
      properties: {
        files: {
          type: 'array',
          items: { type: 'string' }
        }
      }
    }
  }
)

const audits = await pipeline(
  found.files,
  file => agent(
    `检查 ${file} 是否缺少身份认证和权限校验`,
    { label: file }
  )
)

return audits.filter(Boolean)

这里：

• 第一个 agent() 负责找文件；
• pipeline() 遍历文件列表；
• 每个文件启动一个检查 Agent；
• 每个结果保存在 audits 变量中；
• 最后统一返回。

8.4 Workflow 中常见的编排能力

Workflow Runtime 提供的主要能力包括：

• agent()：启动一个 Agent；
• parallel()：同时执行多个任务；
• pipeline()：对列表中的每一项执行任务；
• phase()：把工作分成不同阶段；
• args：接收用户传入的参数。

Workflow 脚本负责调度，不直接读取文件或运行命令。

真正的文件读写和命令执行仍由 Agent 完成。

这就像：

Workflow 是项目经理
Subagent 是执行任务的工程师

项目经理负责任务安排，但不会亲自写每一行代码。

8.5 Workflow 为什么能处理更大的任务

普通 Agent 的中间结果进入模型上下文。

Workflow 的中间结果保存在脚本变量中：

普通 Agent：
结果 → 模型上下文 → 下一步判断

Workflow：
结果 → JavaScript 变量 → 下一步程序逻辑

这样可以减少主 Agent 的上下文压力。

适合的任务包括：

• 检查整个代码仓库；
• 修改几百个文件；
• 大规模框架迁移；
• 多角度研究；
• 让多个 Agent 独立验证同一结论；
• 重复修复，直到测试通过；
• 多轮寻找问题，直到不再发现新问题。

8.6 Workflow 的规模限制

当前官方限制包括：

• 最多同时运行 16 个 Agent；
• 单次 Workflow 最多启动 1,000 个 Agent；
• 工作流运行过程中不能随意插入普通用户对话；
• 权限请求仍可能暂停某些 Agent；
• 大型 Workflow 会明显增加 token 消耗。

因此正确用法不是一开始就让 500 个 Agent 工作，而是：

先测试一个小目录
    ↓
观察效果和成本
    ↓
确认流程正确
    ↓
再扩大到整个项目

8.7 Workflow 可以保存

成功的 Workflow 可以保存到：

.claude/workflows/

或者：

~/.claude/workflows/

保存后可以像命令一样运行：

/audit-routes

项目目录中的 Workflow 可以跟随代码仓库分享给团队。

Dynamic Workflow 官方文档

---

九、Subagent、Agent Team 和 Workflow 的区别

对比项	Subagent	Agent Team	Workflow
本质	一个由父 Agent 调用的专业助手	多个独立 Claude Code 成员组成的团队	一段由运行时执行的 Agent 调度程序
谁安排下一步	父 Agent	Team Lead、共享任务表和成员协作	JavaScript 脚本
中间结果放哪里	Subagent 自己的上下文，最终摘要返回父 Agent	各成员上下文、共享任务表和 Mailbox	JavaScript 变量和运行时状态
成员能否互相交流	主要向调用者汇报	可以直接互相发送消息	不靠自由讨论，而是按脚本传递结果
生命周期	通常完成一个子任务后结束	可以持续工作并接受新任务	按脚本运行，结束后返回统一结果
适合规模	少量独立子任务	少数需要协作的长期成员	几十到几百个重复或可程序化任务
最适合的任务	调查、审查、测试、日志分析	跨模块开发、观点辩论、前后端协同	全仓审查、大规模迁移、批量验证
主要优势	上下文隔离、使用简单	成员能沟通并共享任务状态	编排可读、可保存、可重复、规模大
主要代价	结果仍需父 Agent 汇总	token 和协调成本较高	token 消耗大，流程中不适合频繁人工讨论

简单记忆：

• 找一个专业助手完成一项任务：Subagent；
• 组建一个会分工、会沟通的小组：Agent Team；
• 让程序按固定逻辑管理大量助手：Workflow。

还可以用一个问题快速判断：

只需要一个独立结果？
    → Subagent

成员之间必须讨论和协调？
    → Agent Team

步骤可以写成循环、分支和批处理程序？
    → Workflow

---

十、把所有机制组合起来看

假设用户运行：

/quality-gate:review

完整过程可能是：

1. Plugin 已经注册 Skill、Agent 和 Hook

2. Claude Code 加载 review Skill
   Skill 告诉 Claude 应该怎样审查代码

3. Skill 获取当前 git diff

4. 如果改动较小、任务彼此独立
   启动 security-reviewer Subagent

5. 如果任务横跨前端、后端、测试和安全，
   而且成员之间需要沟通
   组建 Agent Team：
   - security-reviewer 负责安全
   - backend-developer 负责后端
   - test-engineer 负责测试

6. 如果需要对几百个文件执行相同检查
   创建 Dynamic Workflow
   为每个文件启动独立 Reviewer

7. Subagent、Teammate 或 Workflow Agent
   分别读取和搜索自己负责的代码

8. Agent 调用工具前
   PreToolUse Hook 检查操作是否安全

9. Agent 修改文件后
   PostToolUse Hook 自动运行格式化或检查

10. 普通 Subagent 准备结束时
   SubagentStop Hook 检查报告是否有证据

11. Teammate 准备完成任务时
    TaskCompleted Hook 检查验收条件

12. Workflow 再启动验证 Agent
    复查每个问题是不是真实存在

13. Team Lead 或汇总 Agent 去重并排序

14. 主 Agent 准备结束时
    Stop Hook 检查测试是否全部通过

15. 最终报告返回用户

其中：

• Plugin：把整套系统安装进来；
• Skill：说明应该怎么审查；
• Subagent：独立分析不同问题；
• Agent Team：让多个长期成员分工、通信和协作；
• Workflow：调度大量 Subagent；
• Hook：保证关键检查不会被漏掉；
• MCP：连接 GitHub、CI 或安全平台；
• Permission 和 Sandbox：决定实际允许执行什么。

---

十一、应该怎样选择

你的需求	推荐机制
每次打开项目都要知道的规则	CLAUDE.md
某类文件专用的规则	.claude/rules/
可重复使用的操作步骤	Skill
用户输入 /命令 后执行一套流程	Skill
每次修改文件后都必须检查	Hook
某些危险操作必须禁止	PreToolUse Hook 或 Permission Rule
搜索内容很多，不想占满主对话	Subagent
需要专门的安全、测试或数据库专家	Custom Subagent
多个 Agent 需要互相讨论、共享任务状态	Agent Team
前端、后端、测试需要长期并行协作	Agent Team
需要并发处理几十到几百项任务	Dynamic Workflow
需要连接 GitHub、数据库、浏览器	MCP
需要把整套能力分享给团队	Plugin

最后可以浓缩成一句话：

规则写进 CLAUDE.md，方法写成 Skill，硬性检查交给 Hook，独立专业任务交给 Subagent，需要沟通协作时组建 Agent Team，大规模程序化调度交给 Workflow，外部系统通过 MCP 连接，最后用 Plugin 统一打包和分发。

还要记住安全上的核心区别：

CLAUDE.md 和 Skill 是在“劝 Claude 应该怎么做”；Hook、Permission 和 Sandbox 才是在“决定系统真正允许它怎么做”。