【Claude基础】08.子代理系统：分身术与并行执行

文章目录[toc]0\. 【Claude基础】全部目录1\. 子代理设计哲学1.1 单一上下文窗口的局限1.2 核心价值1.3 子代理 vs 多会话 vs 多实例2\. 内置代理详解2.1 general-purpose — 通用多步任务2.2 Explore — 快速只读代码库分析2.3 Plan — 研究型实施规划2.4 claude-code-guide — Claude Code 功能问答3\. 自定义代理创建3.1 代理定义文件位置3.2 代理定义文件结构3.3 配置选项完全参考tools — 工具白名单/黑名单model — 指定模型effort — 推理深度控制maxTurns — 最大执行轮数isolation: worktree — Git Worktree 隔离memory — 持久存储background: true — 后台非阻塞执行permissionMode — 代理级权限覆盖skills — 预加载技能mcpServers — 代理专属 MCP3.4 优先级链4\. 代理调用方式4.1 自动匹配4.2 显式调用4.3 自然语言调用4.4 CLI 启动4.5 列出所有可用代理5\. Git Worktree 隔离5.1 工作原理5.2 优势5.3 完成后处理5.4 实际场景6\. 实战创建 2 个自定义代理6.1 Security Reviewer — 安全审计专家6.2 Documentation Agent — 文档生成代理7\. 代理间通信与协调7.1 父子代理的信息传递7.2 后台代理的结果回收7.3 多代理输出的合并策略实际工作流示例小结0. 【Claude基础】全部目录【Claude基础】01.Claude全景图模型、产品与生态【Claude基础】02.安装与首次交互5分钟上手Claude Code【Claude基础】03.斜杠命令体系掌握Claude Code的操作语言【Claude基础】04.Memory与CLAUDE.md打造你的专属AI助手【Claude基础】05.Skills深度指南让Claude学会你的工作流【Claude基础】06.Hooks深度指南事件驱动的自动化管道【Claude基础】07.MCP Servers深度指南连接万物的协议【Claude基础】08.子代理系统分身术与并行执行【Claude基础】09.多代理协作Agent Teams与编排模式【Claude基础】10.插件开发与生产部署构建可分发的能力包1. 子代理设计哲学1.1 单一上下文窗口的局限Claude Code 的会话运行在一个上下文窗口里。这个窗口有容量上限——即使是最大规格的模型上下文也就 200K tokens 左右Opus 4.6 有 1M但大多数场景用的是 Sonnet。一个复杂的工程任务可能需要读取几十个源码文件做安全审计同时在另一个分支上实现新功能再顺便把 API 文档更新一遍如果这些事情全塞在一个会话里问题就来了上下文爆炸。读了 30 个文件后早期读的内容开始被挤出去。你让它根据刚才的分析结果修改代码它可能已经忘了分析结果的一半。任务污染。安全审计的中间思考过程、文档生成的格式化指令、功能实现的代码片段——全部混在同一个上下文里。Claude 在做功能实现的时候脑子里还飘着安全审计的 OWASP 清单决策会被干扰。串行瓶颈。一个会话同一时间只能干一件事。审计完了才能写功能写完功能才能生成文档。三个任务串行执行时间直接乘以三。子代理就是为了解决这些问题而设计的。1.2 核心价值子代理提供三个关键能力上下文隔离。每个子代理有自己独立的上下文窗口。安全审计代理读了再多文件也不会挤占功能实现代理的上下文空间。各干各的互不干扰。并行执行。多个子代理可以同时运行。你派出三个代理分别做审计、实现、文档三件事同时进行总时间取决于最慢的那个而不是三个的总和。防止污染。每个子代理有明确的任务边界和工具权限。安全审计代理只能读代码不能改代码文档代理只能读代码和写 Markdown。权限隔离意味着一个子代理不会意外搞砸另一个子代理的工作。1.3 子代理 vs 多会话 vs 多实例这三个概念容易混淆区别如下简单说子代理是有组织的分身多会话是各自为政的克隆人多实例是完全独立的平行世界。子代理的最大优势在于自动协调——父代理派出子代理子代理干完活自动把结果交回来父代理汇总后继续推进。整个过程不需要你手动搬运信息。2. 内置代理详解Claude Code 出厂自带四个内置代理覆盖了最常见的使用场景。2.1 general-purpose — 通用多步任务这是最基础的子代理当 Claude Code 判断需要把一个子任务委派出去时默认使用的就是它。特点继承父代理的模型配置父代理用 Opus它也用 Opus拥有完整的工具集——可以读写文件、执行命令、搜索代码没有特殊的角色设定就是一个干活的分身典型场景父代理在做一个复杂重构发现需要先把某个模块的测试跑通。它会派一个 general-purpose 子代理去把tests/unit/auth/下的测试全部跑通自己继续分析其他模块。2.2 Explore — 快速只读代码库分析触发方式描述中包含探索、分析代码库等意图时自动匹配特点使用 Haiku 模型速度快、成本低工具白名单严格限制为Read、Grep、Glob——只能看不能改适合大范围的代码扫描和结构分析这个代理的设计思路很清晰代码探索本质上是一个读多写少准确说是只读的任务用高端模型是浪费。Haiku 读文件、搜关键词的能力完全够用而且速度快很多。实际用法示例帮我分析一下这个项目的目录结构和主要模块划分找出所有使用了 deprecated API 的文件这个项目的数据库连接是在哪里配置的2.3 Plan — 研究型实施规划触发方式/plan 命令或描述中包含制定计划、规划方案等意图特点做研究、出方案但不执行会深入阅读代码、分析依赖关系、评估影响范围输出的是一份结构化的实施计划交给你或其他代理去执行这个代理解决的是一个很实际的问题有时候你只是想知道如果要做 X应该怎么做并不想让 AI 直接动手。比如我想把项目从 REST 迁移到 GraphQL帮我做个实施计划升级 React 17 到 React 19 需要改哪些东西Plan 代理会去读代码、查依赖、分析 breaking changes最后给你一份步骤清晰的方案。它自己不会去改一行代码。2.4 claude-code-guide — Claude Code 功能问答这个代理的作用是回答关于 Claude Code 本身的问题。它内置了 Claude Code 的文档和使用指南。claude code 怎么配置 MCP server自定义代理的 YAML 格式是什么/compact 命令有什么参数当你不确定某个功能怎么用的时候问它比翻文档快。3. 自定义代理创建内置代理覆盖的是通用场景。真正的威力在于你可以根据自己的需求创建专属代理。3.1 代理定义文件位置代理定义文件放在两个地方.claude/agents/| 项目级 | 跟随项目走可以提交到 Git团队共享~/.claude/agents/| 个人级 | 所有项目都可用个人偏好文件名就是代理名。比如.claude/agents/security-reviewer.md定义了一个名叫security-reviewer的代理。3.2 代理定义文件结构一个代理定义文件由两部分组成YAML frontmatter——结构化配置工具、模型、隔离模式等Markdown 正文——代理的系统提示词角色定义、行为指令基本骨架长这样--- description:一句话描述这个代理做什么用于自动匹配tools: - Read - Grep - Glob model: sonnet maxTurns:15---# 你是一个 [角色]你的职责是[做什么]。## 工作流程1. 先做什么2. 再做什么3. 最后做什么## 输出格式按照以下格式输出结果...YAML frontmatter 定义代理的能力边界Markdown 正文定义代理的行为模式。两者配合一个专业的子代理就诞生了。3.3 配置选项完全参考下面逐一讲解每个配置项。tools — 工具白名单/黑名单控制代理能使用哪些工具。# 白名单模式——只能使用列出的工具tools: - Read - Grep - Glob# 黑名单模式——禁用特定工具其他都能用tools: -!Bash-!Write白名单适合需要严格限制的场景比如只读审计黑名单适合大部分工具都要用只是禁掉几个危险的场景。常用工具名Read、Write、Edit、Bash、Grep、Glob、WebSearch、WebFetch。model — 指定模型# 指定具体模型model: haiku# 速度优先成本低model: sonnet# 平衡之选model: opus# 质量优先成本高# 不指定——继承父代理的模型选择策略很简单纯搜索/扫描任务 → haiku常规编码/分析任务 → sonnet需要深度推理的复杂任务 → opuseffort — 推理深度控制effort: low# 快速粗略适合简单任务effort: medium# 默认级别effort: high# 深度思考适合复杂推理这个参数影响的是模型在每一步的思考深度。设为low时模型会快速给出答案设为high时模型会花更多时间做推理。配合model一起用效果最好——比如model: opuseffort: high是最大火力输出。maxTurns — 最大执行轮数maxTurns:10# 最多执行 10 轮工具调用这是一个安全阀。防止代理陷入死循环或者做了太多不必要的操作。对于有明确边界的任务比如审计一个目录设一个合理的上限能避免不必要的 token 消耗。isolation: worktree — Git Worktree 隔离isolation: worktree这个配置值得单独拿出来说后面第 5 节详细展开。简单讲开启 worktree 隔离后代理会在一个独立的 Git worktree 中工作有自己的分支和工作目录。它做的所有文件修改都不会影响你当前的主分支。适用场景大规模重构、实验性功能、任何你不确定代理做的修改是否靠谱的情况。memory — 持久存储memory:true开启后代理可以在MEMORY.md中存储和读取持久化信息。这在需要跨会话保持状态的场景下很有用——比如一个代理专门负责某个模块的维护它可以把上次发现的问题、修改历史等信息存下来下次启动时自动加载。background: true — 后台非阻塞执行background:true这个配置让代理在后台运行不阻塞父代理的主流程。父代理派出后台代理后可以继续做其他事情后台代理完成后会通知父代理。典型场景父代理正在做功能实现 ├── 派出后台代理 A跑测试 ├── 派出后台代理 B更新文档 └── 继续写代码...[后台代理 A 完成]→ 测试全通过[后台代理 B 完成]→ 文档已更新permissionMode — 代理级权限覆盖permissionMode: auto# 自动批准所有操作permissionMode: default# 继承父代理的权限设置对于你完全信任的代理比如只读审计代理可以设为auto让它自动执行不用每次确认。对于会修改文件的代理建议保持default或更严格的权限。skills — 预加载技能skills: - commit - review-pr代理启动时自动加载指定的技能Skills。技能是预定义的指令集类似于给代理预装知识模块。mcpServers — 代理专属 MCPmcpServers: - name: my-database url:http://localhost:3001- name: jira url:http://localhost:3002为代理配置专属的 MCPModel Context Protocol服务器。比如一个数据库管理代理可以连接数据库 MCP一个项目管理代理可以连接 Jira MCP。不同代理连不同的外部服务职责清晰。3.4 优先级链当多个来源的代理定义冲突时优先级从高到低Policy组织策略CLI 定义项目级用户级插件内置比如项目级.claude/agents/里有一个reviewer.md个人级~/.claude/agents/里也有一个同名文件。项目级的会覆盖个人级的。再往上如果组织策略里定义了同名代理策略的优先级最高。这个优先级链的设计逻辑是越具体、越受控的来源优先级越高。4. 代理调用方式定义好的代理有多种调用方式。4.1 自动匹配Claude Code 会根据你的任务描述自动匹配合适的代理。匹配依据是代理定义中的description字段。# .claude/agents/security-reviewer.md--- description:安全审计检查代码中的安全漏洞和风险---当你说帮我检查这个项目有没有安全漏洞时Claude Code 看到关键词安全、“漏洞”会自动匹配到这个代理并调用它。自动匹配是最无感的调用方式但也最不可控。如果你有多个描述相近的代理自动匹配可能选错。4.2 显式调用用语法直接指定代理security-reviewer 检查 src/auth/ 目录的代码安全性这种方式最明确——就是要用这个代理没有歧义。4.3 自然语言调用在对话中明确提到代理名称使用 security-reviewer 代理审查 src/api/ 下所有的接口让 implementation-agent 在独立分支上实现用户注册功能用文档代理更新一下 API 参考文档Claude Code 能从自然语言中识别出你想调用的代理。4.4 CLI 启动直接用命令行参数启动一个代理作为整个会话的主角色claude--agentsecurity-reviewer这种方式下整个会话都由指定代理控制。适合单一用途的场景——比如你就想做一次安全审计从头到尾都用安全审计代理。4.5 列出所有可用代理claude agents这个命令会列出所有可用的代理内置 项目级 个人级包括名称和描述。当你忘了某个代理叫什么名字时这个命令能救急。5. Git Worktree 隔离5.1 工作原理Git worktree 是 Git 的原生功能——允许在同一个仓库下创建多个工作目录每个目录关联一个不同的分支。Claude Code 的 worktree 隔离就是利用了这个机制。当一个配置了isolation: worktree的代理启动时Claude Code 调用git worktree add在临时目录下创建一个新的工作树自动创建一个新分支通常命名为agent/agent-name/timestamp之类的格式代理在这个独立的工作目录中执行所有操作代理完成后结果留在那个分支上主分支完全不受影响整个过程对你来说是透明的——你不需要手动管理 worktree代理启动时自动创建完成后你决定怎么处理。5.2 优势主分支安全。代理做的所有修改——不管是写得好的代码还是写崩了的代码——都在独立分支上。你的 main 分支纹丝不动。可安全实验。你可以让代理尝试一些激进的重构方案。方案好就合并不好就直接丢掉分支零成本。并行不冲突。多个 worktree 隔离的代理可以同时工作各自在自己的分支上改文件不会出现文件冲突。5.3 完成后处理代理完成后你有三种选择审查并合并# 查看代理做了什么gitdiffmain..agent/implementation/20260502# 满意的话合并gitmerge agent/implementation/20260502Cherry-pick 部分提交# 只要其中几个提交gitcherry-pick abc123 def456丢弃# 不满意直接删掉gitworktree remove /path/to/worktreegitbranch-Dagent/implementation/202605025.4 实际场景大规模重构让代理在独立分支上把整个项目从 CommonJS 迁移到 ESM。迁移完了你审查一下没问题就合并有问题就丢掉让它重来。实验性功能让代理在独立分支上实现一个新的认证方案。你可以同时让另一个代理实现另一种方案最后比较两个分支的代码选更好的那个。破坏性操作比如删掉所有 deprecated 的 API 端点并更新调用方。这种操作影响面大在 worktree 里做比在主分支上做安全得多。6. 实战创建 2 个自定义代理下面给出三个完整的代理定义文件涵盖了不同的使用模式。6.1 Security Reviewer — 安全审计专家文件位置.claude/agents/security-reviewer.md--- description:代码安全审计检查安全漏洞、敏感信息泄露、注入风险等tools: - Read - Grep - Glob model: sonnet effort: high maxTurns:30---# 安全审计代理你是一个专注于代码安全审计的专家代理。你的任务是对指定的代码范围进行全面的安全检查。## 审计清单基于 OWASP Top 10 2021### A01: 访问控制失效- 检查 API 端点是否有适当的权限校验 - 寻找 IDOR不安全的直接对象引用漏洞 - 检查是否存在路径穿越风险 - 验证角色/权限检查是否在每个需要的地方都存在### A02: 加密失败- 检查敏感数据密码、token、密钥是否明文存储 - 查找硬编码的密钥、API key、密码 - 验证密码是否使用了安全的哈希算法bcrypt/scrypt/argon2 - 检查 HTTPS/TLS 配置### A03: 注入- SQL 注入查找字符串拼接 SQL 的代码 - XSS检查用户输入是否未经转义直接输出到 HTML - 命令注入查找 shell 命令拼接 - LDAP/XML/NoSQL 注入风险### A04: 不安全的设计- 检查业务逻辑中的竞态条件 - 验证重要操作是否有速率限制 - 检查是否缺少 CSRF 防护### A05: 安全配置错误- 查找 DEBUG 模式在生产环境中开启的风险 - 检查默认凭据 - 验证 CORS 配置是否过于宽松 - 检查错误处理是否泄露敏感信息堆栈跟踪、数据库信息### A06-A10: 其他风险- 过时的依赖组件检查 package.json/requirements.txt - 认证和会话管理缺陷 - 数据完整性校验 - 日志和监控不足 - SSRF服务端请求伪造## 工作流程1. 先用 Glob 获取目标范围内的文件列表2. 用 Grep 快速扫描常见的安全模式如eval(、exec(、password、secret、api_key3. 用 Read 逐个检查可疑文件的完整上下文4. 按严重程度分类输出结果## 输出格式按以下格式输出审计报告### 严重Critical[需要立即修复的漏洞]### 高危High[应尽快修复的风险]### 中危Medium[建议修复的问题]### 低危Low[最佳实践建议]每个发现包含 - **文件**具体文件路径和行号 - **问题**一句话描述 - **风险**可能导致什么后果 - **修复建议**具体的修复方案这个代理的关键设计决策工具只给了 Read/Grep/Glob——审计代理不应该有修改代码的权限。它的职责是发现问题不是修复问题。model: sonnet effort: high——安全审计需要一定的推理能力理解业务逻辑才能发现逻辑漏洞但不需要 Opus 级别的成本。Sonnet 配合高推理深度是性价比最优解。maxTurns: 30——安全审计需要读很多文件30 轮工具调用给了足够的空间。6.2 Documentation Agent — 文档生成代理文件位置.claude/agents/doc-generator.md--- description:分析代码结构并生成或更新 API 文档、模块文档tools: - Read - Grep - Glob - Write - Edit model: sonnet effort: medium maxTurns:40---# 文档生成代理你是一个技术文档生成代理负责分析代码并生成准确、实用的技术文档。## 核心原则1. **准确性第一**。文档必须与代码实际行为一致。不确定的地方宁可标注待确认也不要瞎编。2. **示例驱动**。每个 API、函数、类都应该有使用示例。没有示例的文档是半成品。3. **面向使用者**。文档的读者是要使用这些 API 的开发者不是写这些 API 的人。关注怎么用而不是怎么实现的。## 文档类型### API 参考文档对于每个公开的 API 端点/函数/类记录 - 功能描述一句话 - 参数列表名称、类型、是否必须、默认值、说明 - 返回值类型、结构、可能的值 - 错误情况什么条件下会抛出什么错误 - 使用示例至少一个基本用法 一个高级用法### 模块概览文档对于每个主要模块/包记录 - 模块职责这个模块干什么的 - 对外暴露的接口 - 与其他模块的依赖关系 - 核心概念和术语解释## 工作流程1. 用 Glob 扫描目标范围内的所有源码文件2. 用 Grep 查找公开接口export、public、装饰器等3. 用 Read 阅读每个接口的完整实现4. 生成文档内容5. 如果已有文档文件用 Edit 更新如果没有用 Write 创建## 输出格式使用 Markdown 格式结构如下# 模块名一句话描述## 安装/引入## 快速开始## API 参考### function_name(param1, param2)描述... **参数**|名称|类型|必须|默认值|说明||------|------|------|--------|------|**返回值** **示例**## 常见问题这个代理比安全审计代理多了Write和Edit工具——因为它需要生成文档文件。但注意它没有Bash不能执行任意命令。这是一个合理的权限边界文档代理只需要读代码、写 Markdown。7. 代理间通信与协调当你使用多个子代理时它们之间的通信和协调是一个关键话题。7.1 父子代理的信息传递父代理和子代理之间的通信遵循一个简单的模式下行父 → 子父代理在创建子代理时传递任务描述。这个描述是子代理的全部输入——它不能访问父代理的上下文历史只能看到父代理明确传给它的信息。父代理心里想的用户要我做一个完整的代码审查。我先让安全审计代理去查安全问题。父代理传给子代理的对 src/api/ 目录下所有文件进行安全审计重点关注认证和授权相关的代码。 项目使用 Express.js TypeScript认证方案是 JWT。这意味着父代理在派发任务时需要把必要的上下文信息提炼出来一并传递。子代理不会自动继承父代理读过的文件内容。上行子 → 父子代理完成任务后把结果返回给父代理。返回的内容就是子代理的最终输出文本。父代理拿到后可以继续基于这个结果做下一步决策。子代理返回审计完成。发现 3 个高危问题 1. src/api/users.ts:45 — SQL 注入风险 2. src/api/auth.ts:78 — JWT 密钥硬编码 3. src/api/upload.ts:23 — 文件上传没有类型校验父代理收到后好的有 3 个高危问题。我现在让 implementation-agent 去修复这些问题。7.2 后台代理的结果回收后台代理background: true的结果回收是异步的。时间线 t0: 父代理派出后台代理 A跑测试 t1: 父代理派出后台代理 B更新文档 t2: 父代理自己继续写代码 t3: 后台代理 B 完成 → 结果进入待处理队列 t4: 后台代理 A 完成 → 结果进入待处理队列 t5: 父代理在合适的时机处理队列中的结果父代理不会被后台代理阻塞。它可以在任何时候检查后台代理的状态代理还在跑 → 继续干自己的事代理已完成 → 读取结果并处理代理出错 → 获取错误信息并决定是否重试这种异步模式特别适合派出去做耗时任务自己不用干等着的场景。7.3 多代理输出的合并策略当多个代理并行完成后父代理需要合并它们的输出。这里没有自动的合并机制——合并逻辑完全由父代理或者你来决定。补充型合并多个代理分别负责不同的方面结果直接拼起来。比如安全审计报告 性能分析报告 代码质量报告三份报告合在一起就是完整的代码审查结果。冲突型合并多个代理对同一段代码做了不同的修改。这种情况下需要人工介入判断或者让父代理基于所有修改做一个综合决策。如果用了 worktree 隔离冲突型合并就变成了 Git 分支合并问题——用标准的git merge或git rebase流程处理。筛选型合并多个代理做同一个任务比如让两个代理分别实现同一个功能选结果更好的那个。这种模式成本高但质量也高适合关键功能的开发。实际工作流示例把上面的知识串起来看一个完整的工作流。假设你要给一个 Express.js 项目添加用户注册功能你添加用户注册功能要包含邮箱验证Claude Code父代理1. 先派出 Explore 代理 → 快速扫描项目结构了解现有的认证模块、数据库模型、路由组织方式2. 基于探索结果派出 Plan 代理 → 制定实施方案需要改哪些文件、添加哪些端点、邮件服务怎么集成3. 把方案展示给你确认4. 你确认后派出 implementation-agentworktree 隔离→ 在独立分支上实现功能5. 同时派出 security-reviewer后台→ 对新写的代码做安全审计6. implementation-agent 完成 → 父代理报告分支名和改动摘要7. security-reviewer 完成 → 父代理报告安全审计结果8. 如果有安全问题让 implementation-agent 修复9. 最后派出 doc-generator → 更新 API 文档10. 所有子代理完成父代理给你一个完整的总结整个过程中你只说了一句话。Claude Code 自动拆分任务、调度子代理、汇总结果。这就是子代理系统的核心价值——让 AI 自己管理 AI。小结子代理系统的本质是任务分解 并行执行 结果汇总。通过给每个子任务分配独立的上下文、独立的工具权限、甚至独立的 Git 分支把一个复杂的大任务拆成多个简单的小任务并行处理。几个实操建议从内置代理开始。Explore 和 Plan 已经覆盖了大部分场景先用熟了再考虑自定义。权限最小化。给代理的工具权限尽量少——不需要写文件的代理就不给 Write不需要执行命令的就不给 Bash。worktree 隔离用在不确定的场景。任何你觉得代理可能改出问题的任务都用 worktree 隔离。成本几乎为零但能避免很多麻烦。maxTurns 要设合理。太小了代理干不完活太大了浪费 token。根据任务复杂度调整——简单搜索 10 轮够了功能实现可能需要 40-50 轮。description 写准确。自动匹配的准确率完全取决于 description 写得好不好。用具体的关键词不要写空泛的描述。