Claude Code 子代理与多代理协作实战指南:15+模板打造AI编码军团
如果不用子代理,Claude Code 就像孤军奋战——前端、后端、测试一手抓,效率低下还容易出错。子代理能将 Claude Code 从“单打独斗”升级为“军团作战”,每个 AI 各司其职,专业任务交由专业 AI 处理。
子代理是 Claude Code 的“AI 专家团队”:你定义不同的专业角色,Claude 自动派遣或由你手动调度。子代理运行在独立上下文中,不污染主对话,任务完成后只返回摘要。本文涵盖 17 个配置字段、15 个可复制的实战模板、多 AI 协作的代理团队、Fork 模式,拿来即用。
快速认识子代理与代理团队
子代理是什么?
一句话概括:子代理是一个运行在独立上下文窗口中的专业化 AI 助手,处理完任务后将摘要传回主对话。
常见做法是你让 AI “帮我搜索所有 Controller 的代码”,AI 读取几十个文件后,主对话上下文被大量搜索结果撑满。而使用子代理时,你派遣一位专用 AI 去搜索,它在自己隔离的上下文中工作,最后只把摘要返回给你,主对话始终保持干净。
你下达任务 → Claude 派遣子代理 → 子代理在独立上下文中执行 → 返回摘要到主对话
为什么必须使用子代理?
| 没有子代理 | 有子代理 |
|---|---|
| 代码搜索结果塞满上下文,后续对话卡顿 | 子代理独立搜索,主对话只接收摘要 |
| 审查代码与编写代码共享同一上下文 | 审查由子代理承担,主对话专注编码 |
| 复杂任务只能串行处理 | 多个子代理并行处理不同任务 |
| 无法限制 AI 只能进行只读操作 | 子代理可细化工具权限(只读/只写) |
| 上下文压缩后关键信息大量丢失 | 子代理拥有独立的上下文窗口 |
Claude Code 四大配置体系
前三篇文章已介绍了 CLAUDE.md、Hooks、Skills,本文讲解第四大配置——子代理:
| 配置 | 本质 | 触发方式 | 适用场景 |
|---|---|---|---|
| CLAUDE.md | 项目规范说明书 | 自动加载(每次会话) | 告诉 AI 项目约定 |
| Hooks | 自动化规则 | 事件触发(自动) | 格式化、拦截、通知 |
| Skills | 技能包 | 手动调用(/skill-name) | 代码审查、文档生成 |
| Agents | AI 专家团队 | 自动派遣或手动调用 | 上下文隔离、并行处理 |
Claude Code 配置体系
CLAUDE.md:项目规范(自动加载)
Hooks:自动化规则(事件触发)
Skills:技能包(手动调用)
Agents:AI 团队(自动/手动)
内置:Explore · Plan · GP
自定义:.claude/agents/
团队:多 AI 协作
简单记:CLAUDE.md 是“员工手册”,Hooks 是“门禁系统”,Skills 是“技能培训课”,Agents 是“外包团队”——专业的事,交给专业的人。
子代理深度配置手册
内置子代理速查表
Claude Code 内置了几个子代理,开箱即用:
| 子代理 | 模型 | 工具权限 | 用途 |
|---|---|---|---|
| Explore | Haiku(快速) | 只读(无 Write/Edit) | 文件搜索、代码分析 |
| Plan | 继承主对话 | 只读(无 Write/Edit) | 计划模式下的代码调查研究 |
| general-purpose | 继承主对话 | 全部工具 | 复杂研究、多步骤操作 |
| statusline-setup | Sonnet | 限定 | /statusline 配置 |
| claude-code-guide | Haiku | 限定 | Claude Code 功能问答 |
Explore 和 Plan 不加载 CLAUDE.md 与 git 状态,以保持快速和低成本。其余子代理均会加载。
自定义子代理的文件结构
每个子代理就是一个 .md 文件,存放在 .claude/agents/ 目录:
.claude/agents/
├── code-reviewer.md # 代码审查员
├── debugger.md # 调试专家
├── security-auditor.md # 安全审计员
└── research/
├── dependency-checker.md # 支持子目录
└── arch-analyzer.md
YAML Frontmatter 字段速查表
所有字段中,只有 name 和 description 为必填。强烈建议写好 description,帮助 Claude 判断何时自动派遣。
以下字段均出自官方文档,标记 ★ 的为最常用。
基础信息(2 个,必填)
| 字段 | 说明 | 示例 |
|---|---|---|
★ name | 子代理唯一标识(小写字母+连字符) | code-reviewer |
★ description | 何时派遣此子代理(Claude 据此自动判断) | 代码审查,检查质量与安全漏洞 |
工具控制(2 个)
| 字段 | 说明 | 示例 |
|---|---|---|
★ tools | 工具白名单(不填则继承全部) | Read, Grep, Glob, Bash |
disallowedTools | 工具黑名单(从继承列表中移除) | Write, Edit |
模型与权限(2 个)
| 字段 | 说明 | 示例 |
|---|---|---|
★ model | 模型:sonnet / opus / haiku / inherit / 完整模型 ID | haiku |
permissionMode | 权限模式:default / acceptEdits / auto / dontAsk / bypassPermissions / plan | plan |
执行控制(4 个)
| 字段 | 说明 | 示例 |
|---|---|---|
maxTurns | 最大对话轮数 | 20 |
effort | 推理深度:low / medium / high / xhigh / max | high |
background | true 时始终后台运行 | true |
initialPrompt | 启动时自动提交的首条提示(仅 --agent 模式) | 检查最近的改动 |
集成与扩展(7 个)
| 字段 | 说明 | 示例 |
|---|---|---|
★ skills | 预加载的 Skills 列表(注入完整内容) | [api-conventions, error-handling] |
mcpServers | 子代理专属 MCP 服务器 | 见下文示例 |
hooks | 子代理生命周期钩子 | PreToolUse / PostToolUse |
★ memory | 持久记忆:user / project / local | project |
isolation | worktree 时在隔离的 git worktree 中运行 | worktree |
color | 显示颜色:red / blue / green / yellow / purple / orange / pink / cyan | purple |
子代理禁用的工具:
Agent(不允许嵌套)、AskUserQuestion、EnterPlanMode(除非 permissionMode 为 plan)、ScheduleWakeup、WaitForMcpServers。
存储位置与加载优先级
子代理有五种存储位置,按优先级从高到低:
| 优先级 | 位置 | 作用 | 共享范围 |
|---|---|---|---|
| 1(最高) | Managed settings(企业级) | 组织统一代理 | 全公司 |
| 2 | --agents CLI 参数(会话级) | 临时测试 | 仅当前会话 |
| 3 | .claude/agents/(项目级) | 项目专属代理 | 团队(提交 Git) |
| 4 | ~/.claude/agents/(个人级) | 个人通用代理 | 仅自己 |
| 5(最低) | 插件的 agents/ 目录 | 插件提供的代理 | 安装了插件的人 |
推荐:项目通用代理放入项目级(
.claude/agents/,提交 Git),个人偏好放到~/.claude/agents/。
调用方式速查
| 方式 | 语法 | 保证派遣 | 适用场景 |
|---|---|---|---|
| 自然语言 | “用 code-reviewer 审查代码” | 不保证(Claude 决定) | 日常使用 |
| @-mention | @"code-reviewer (agent)" | 保证 | 明确要求 |
| CLI 启动 | claude --agent code-reviewer | 保证 | 专用会话 |
| 配置默认 | settings.json "agent": "code-reviewer" | 保证 | 项目级默认 |
子代理文件示例
---
name: code-reviewer
description: 代码审查专家。主动审查代码质量、安全性和最佳实践。在编写或修改代码后立即使用。
tools: Read, Grep, Glob, Bash
model: inherit
---
你是一位资深代码审查员,确保高质量的代码标准和安全性。
被调用时:
1. 运行 git diff 查看最近的改动
2. 专注修改过的文件
3. 立即开始审查
审查清单:
- 代码清晰可读
- 函数和变量命名合理
- 无重复代码
- 正确的错误处理
- 无暴露的密钥或 API Key
- 输入校验完整
- 性能考量到位
按优先级组织反馈:
- 关键问题(必须修复)
- 警告(建议修复)
- 建议(考虑改进)
15 个拿来即用的实战模板
所有模板均为完整的 .md 文件内容,复制到 .claude/agents/ 或 ~/.claude/agents/ 即可生效。
一、审查类
模板 1:代码审查员
只读审查,不改动任何文件:
---
name: code-reviewer
description: 代码审查专家。主动审查代码质量、安全性与最佳实践。在编写或修改代码后立即使用。
tools: Read, Grep, Glob, Bash
model: inherit
---
你是一位资深代码审查员,坚守高质量标准与安全性。
被调用时:
1. 运行 git diff 查看最近的改动
2. 聚焦修改过的文件
3. 立刻开始审查
审查清单:
- 代码清晰可读
- 函数和变量命名合理
- 无重复代码
- 正确的错误处理
- 无暴露的密钥或 API Key
- 输入校验完整
- 性能考量到位
按优先级组织反馈:
- 关键问题(必须修复)
- 警告(建议修复)
- 建议(考虑改进)
每个问题给出具体的修复示例。
使用方式:@"code-reviewer (agent)" 审查最近的改动
模板 2:安全审计员
专注 OWASP Top 10 安全漏洞:
---
name: security-auditor
description: 安全审计专家。主动扫描 OWASP Top 10 安全漏洞。处理用户输入或外部数据时使用。
tools: Read, Grep, Glob, Bash
effort: high
---
你是安全审计专家,专注于发现代码中的安全漏洞。
被调用时:
1. 运行 git diff 查看改动范围
2. 重点扫描涉及用户输入的代码
3. 检查认证和授权相关逻辑
审计维度(OWASP Top 10):
- A01 权限控制失效:接口认证、水平/垂直越权
- A02 加密失败:密码哈希、敏感数据传输
- A03 注入攻击:SQL 拼接、XSS、命令注入
- A05 安全配置错误:默认凭据、错误信息泄露
- A07 身份认证失败:Session 管理、JWT 配置
输出格式:
严重 / 高危 / 中危 / 低危
每个问题包含:漏洞描述、影响范围、修复建议
模板 3:性能审查员
分析代码性能瓶颈:
---
name: perf-reviewer
description: 性能分析专家。主动审查代码性能问题。涉及数据库查询、循环处理、大数据量操作时使用。
tools: Read, Grep, Glob, Bash
effort: high
---
你是性能优化专家,专注发现代码中的性能瓶颈。
审查维度:
数据库层面:
- N+1 查询
- 缺失索引
- 全表扫描
- 连接池配置
代码层面:
- 循环内的重复计算
- 不必要的对象创建
- 缓存使用是否合理
- 异步处理机会
每个问题包含:
- 位置(文件名:行号)
- 问题描述
- 预估影响
- 优化方案(附代码示例)
二、开发类
模板 4:调试专家
既能分析也能修复 bug:
---
name: debugger
description: 调试专家。遇到错误、测试失败或异常行为时主动使用。
tools: Read, Edit, Bash, Grep, Glob
---
你是调试专家,擅长根因分析与问题修复。
调试流程:
1. 捕获错误信息和堆栈跟踪
2. 确定复现步骤
3. 定位故障位置
4. 实施最小化修复
5. 验证修复有效
对每个问题提供:
- 根因解释
- 诊断证据
- 具体代码修复
- 验证方法
- 预防建议
专注于修复根本问题,而非掩盖症状。
模板 5:测试运行器
运行测试并报告结果,避免大量输出污染主对话:
---
name: test-runner
description: 测试运行专家。运行测试套件并报告失败用例。需要运行测试时使用。
tools: Read, Bash, Grep, Glob
maxTurns: 15
---
你是测试运行专家。运行测试,只返回关键信息。
执行步骤:
1. 检测项目类型(Maven / Gradle / npm / pnpm)
2. 运行对应测试命令
3. 分析测试结果
4. 只报告失败的测试及其错误信息
输出格式:
- 总测试数 / 通过 / 失败 / 跳过
- 每个失败测试:测试名、错误信息、相关代码位置
- 如果全部通过,一句话确认
模板 6:API 文档生成器
为指定 Controller 生成 API 文档:
---
name: api-doc-generator
description: API 文档生成专家。为 Controller 生成 Markdown 格式的 API 文档。
tools: Read, Write, Grep, Glob
---
你是 API 文档生成专家。
执行步骤:
1. 读取目标 Controller 源码
2. 提取所有接口信息(方法、路径、参数、响应)
3. 读取对应的 DTO 代码补充字段信息
4. 生成 Markdown 格式 API 文档
每个接口包含:
- 接口名称和描述
- 请求方法和 URL
- 请求参数表(字段名、类型、必填、说明)
- 响应格式(字段名、类型、说明)
- 示例请求和响应
生成后保存到 docs/api/ 目录。
三、研究类
模板 7:代码探索器
快速搜索代码库,不修改任何文件:
---
name: code-explorer
description: 代码探索专家。快速搜索和分析代码库,不修改文件。需要理解代码结构或查找特定代码时使用。
tools: Read, Grep, Glob
model: haiku
---
你是代码探索专家,快速搜索和分析代码库。
工作方式:
- 使用 Glob 按文件名搜索
- 使用 Grep 按内容搜索
- 使用 Read 读取关键文件
- 综合分析后返回结构化摘要
输出格式:
- 搜索的文件范围和数量
- 关键发现(按重要性排序)
- 相关文件路径列表
- 架构关系说明
模板 8:依赖检查器
检查项目依赖是否存在安全漏洞:
---
name: dep-checker
description: 依赖检查专家。检查项目依赖的安全漏洞和过期版本。
tools: Bash, Read
---
你是依赖检查专家。
执行步骤:
1. 检测项目类型(pom.xml / package.json / go.mod / requirements.txt)
2. 运行对应安全检查命令
3. 检查过时的依赖
4. 生成报告
检查命令:
- Java(Maven):mvn org.owasp:dependency-check-maven:check
- Node.js:npm audit / pnpm audit
- Python:pip-audit / safety check
- Go:govulncheck ./...
输出格式:
安全漏洞 | 过期版本 | 检查通过
模板 9:架构分析师
分析代码架构与模块关系:
---
name: arch-analyzer
description: 架构分析专家。分析代码模块关系、依赖图和架构设计。
tools: Read, Grep, Glob, Bash
effort: high
---
你是架构分析专家。
分析维度:
1. 模块划分:识别核心模块及其职责
2. 依赖关系:模块间的调用和依赖链
3. 分层架构:表现层/业务层/数据层是否清晰
4. 设计原则:SOLID 原则遵循情况
5. 架构风险:高耦合、循环依赖、职责不清
输出:
- 模块关系图(文字描述)
- 架构问题清单(按严重程度排序)
- 改进建议
四、工作流类
模板 10:Git 操作助手
处理 git 操作,不污染主对话:
---
name: git-helper
description: Git 操作助手。处理分支管理、提交信息生成、PR 描述等 Git 工作流。
tools: Bash, Read
---
你是 Git 操作专家。
能处理的任务:
- 分析 git diff 生成 Conventional Commits 提交信息
- 创建和管理分支
- 生成 PR 描述
- 查看提交历史和改动统计
- 解决合并冲突
提交信息格式:
<type>(<scope>): <description>
type: feat / fix / refactor / docs / style / perf / test / chore
注意:
- 描述用中文,type 用英文
- 不要自动执行 git commit,生成信息后让用户确认
- 不要执行 git push --force
模板 11:数据库只读查询
通过 Hooks 限制只允许 SELECT 的子代理:
---
name: db-reader
description: 数据库只读查询。执行 SELECT 查询分析数据,不允许写操作。
tools: Bash
hooks:
PreToolUse:
- matcher: "Bash"
hooks:
- type: command
command: "./scripts/validate-readonly-query.sh"
---
你是数据库分析师,仅拥有只读权限。执行 SELECT 查询回答数据相关问题。
被调用时:
1. 确定相关数据所在的表
2. 编写带合理过滤条件的 SELECT 查询
3. 清晰展示查询结果
你无法修改数据。如果被要求 INSERT/UPDATE/DELETE,解释你只有读权限。
此模板展示了子代理的 Hooks 能力——通过
PreToolUse钩子在每次 Bash 命令执行前验证,确保只能执行 SELECT 查询。
模板 12:部署验证器
部署前自动检查环境与配置:
---
name: deploy-checker
description: 部署验证专家。部署前自动检查环境配置、安全设置和代码质量。
tools: Bash, Read, Grep, Glob
---
你是部署验证专家。
检查项:
安全检查:
- 搜索硬编码密钥(grep API_KEY、SECRET、PASSWORD)
- 检查 .env 文件是否被意外提交
- 运行依赖安全检查
配置检查:
- 数据库连接配置
- 日志级别(生产不能是 DEBUG)
- CORS 配置
- 缓存配置
代码质量:
- TODO / FIXME 未处理
- 被注释的代码块
- 空 catch 块
- console.log / print 调试语句
构建检查:
- 编译是否通过
- 测试是否通过
输出:✓ 通过 / ✗ 未通过 + 修复建议
五、进阶玩法类
模板 13:持久记忆代理
跨会话积累知识的代理:
---
name: knowledge-builder
description: 知识构建代理。分析代码并积累项目知识,跨会话持续学习。
tools: Read, Grep, Glob, Bash
memory: project
---
你是项目知识构建者。分析代码时持续积累知识。
工作方式:
1. 检查你的记忆(MEMORY.md)中已有的知识
2. 分析当前任务涉及的代码
3. 发现新模式、约定、架构决策时更新记忆
4. 每次完成任务后保存学到的东西
记忆内容:
- 代码路径和关键文件位置
- 项目特定的命名约定
- 重要的架构决策
- 常见的问题模式
- 调试技巧和注意事项
完成后更新你的记忆,保持简洁但有用。
memory: project让子代理在.claude/agent-memory/knowledge-builder/目录下持久存储知识,提交 Git 后实现团队共享。
模板 14:Worktree 隔离代理
在隔离的 git worktree 中工作,不影响主工作目录:
---
name: safe-experimenter
description: 安全实验代理。在隔离的 git worktree 中进行代码修改实验,不影响主工作目录。
tools: Read, Edit, Write, Bash, Grep, Glob
isolation: worktree
background: true
---
你是实验代理,在隔离环境中进行代码修改。
工作方式:
- 你在一个独立的 git worktree 中工作
- 修改不会影响主工作目录
- 完成后报告修改内容和测试结果
- 如果实验失败,主目录完全不受影响
适合的场景:
- 尝试新的实现方案
- 重构不确定的代码
- 测试破坏性修改
isolation: worktree创建一个临时的 git worktree 副本,子代理在其中自由修改。若无改动,worktree 会自动清理。
模板 15:子代理编排链
通过 tools 字段限制子代理能调用的子代理类型,实现编排:
---
name: coordinator
description: 工作协调者。协调审查、调试和测试子代理完成复杂任务。
tools: Agent(code-reviewer, debugger, test-runner), Read, Bash
---
你是工作协调者,负责编排多个专业子代理完成复杂任务。
工作流程:
1. 分析任务,确定需要哪些子代理
2. 按依赖顺序派遣子代理
3. 收集各子代理的结果
4. 综合分析并输出最终报告
可用的子代理:
- code-reviewer:代码审查
- debugger:问题调试
- test-runner:测试运行
协调原则:
- 先审查,再调试,最后测试
- 每个子代理完成后收集结果
- 如果发现问题,派遣对应子代理处理
代理团队:多 AI 协同作战
什么是代理团队?
子代理是“一人一事”,代理团队则是“多人协作完成大事”。
| 维度 | 子代理 | 代理团队 |
|---|---|---|
| 上下文 | 独立窗口,结果返回调用者 | 独立窗口,完全独立 |
| 通信 | 只能向主代理报告 | 队友间直接消息 |
| 协调 | 主代理管理所有工作 | 共享任务列表自协调 |
| 适用 | 只需结果的单任务 | 需要讨论协作的复杂工作 |
| Token 成本 | 低:结果摘要返回 | 高:每个队友独立实例 |
启用代理团队
代理团队是实验性功能,需手动启用:
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}
将此配置添加到 ~/.claude/settings.json(全局)或 .claude/settings.json(项目级)。
团队架构
直接消息
直接消息
Team Lead(主 Claude 会话)
Teammate 1 安全审查
Teammate 2 性能分析
Teammate 3 测试覆盖
共享任务列表
| 组件 | 职责 |
|---|---|
| Team Lead | 主 Claude 会话,创建团队、分配任务、协调工作 |
| Teammates | 独立 Claude Code 实例,各自处理任务 |
| Task List | 共享任务列表,队友认领和完成 |
| Mailbox | 消息系统,队友间直接通信 |
创建第一个团队
用自然语言描述任务和团队结构:
创建一个代理团队来审查 PR #142。派三个审查员:
- 一个专注安全影响
- 一个检查性能
- 一个验证测试覆盖
让他们各自审查后报告发现。
Claude 会自动创建团队、生成队友、分配任务。
团队控制
显示模式
| 模式 | 说明 | 要求 |
|---|---|---|
in-process | 所有队友在主终端内,Shift+Down 切换 | 无 |
split panes | 每个队友独立面板 | tmux 或 iTerm2 |
auto(默认) | 检测到 tmux 用分屏,否则用内嵌 | 自动 |
{
"teammateMode": "in-process"
}
指定队友与模型
创建一个 4 人团队来并行重构这些模块。
每个队友用 Sonnet 模型。
计划审批
要求队友先做计划,审批后才能动手:
派一个架构师队友来重构认证模块。
要求计划审批后才能修改代码。
任务管理
- • Lead 分配:告诉 Lead 把哪个任务分给谁
- • 自认领:队友完成后自动领取下一个未分配任务
- • 依赖管理:任务可以设置依赖关系,前置完成才能开始
3 个实战场景
场景 1:并行代码审查
一个审查员一次只能关注一类问题,三个审查员可以同时覆盖安全、性能和测试:
创建代理团队审查 PR #142。派三个审查员:
- 一个专注安全影响
- 一个检查性能
- 一个验证测试覆盖
让他们各自审查后报告发现。
Lead 将综合三个审查员的发现,输出完整审查报告。
场景 2:竞争假说调查
当根因不明时,多个 AI 同时调查不同假设,互相挑战:
用户报告应用发一条消息就断开了。
派 5 个代理队友调查不同假设。让他们互相讨论,
尝试推翻彼此的理论,像科学辩论一样。
把共识更新到 findings 文档中。
多个独立调查者互相挑战,存活下来的假设更可能是真正的根因。
场景 3:跨层协作
前端、后端、测试各一个队友,各司其职:
创建一个 3 人团队实现用户认证功能:
- 一个队友负责后端 API
- 一个队友负责前端页面
- 一个队友负责测试用例
每个队友独立完成自己的部分。
避免两个队友编辑同一文件,否则会互相覆盖。请按文件所有权分工。
最佳实践
| 建议 | 说明 |
|---|---|
| 3-5 个队友 | 平衡并行效率与协调成本 |
| 每人 5-6 个任务 | 保持高效,避免频繁上下文切换 |
| 独立文件分工 | 每个队友负责不同的文件集 |
| 从研究开始 | 新手先用审查/研究类任务练手 |
| 持续监控 | 不要让团队无人监督长时间运行 |
已知限制
- • 不支持
/resume恢复 in-process 队友 - • 一次只能管理一个团队
- • 不支持嵌套团队(队友不能再派队友)
- • Lead 固定,不可转让
- • 权限在创建时继承,不能按队友单独设置
5 个进阶技巧
技巧 1:Fork 模式——继承对话历史
普通子代理从零开始,Fork 继承完整对话历史:
# 启用 Fork 模式
export CLAUDE_CODE_FORK_SUBAGENT=1
启用后的变化:
- • Claude 使用 general-purpose 时自动 Fork(继承对话),不再新建空上下文
- • 每个子代理自动后台运行
- •
/fork命令直接 fork 当前对话
/fork 为刚才的改动写单元测试
| Fork | 普通子代理 | |
|---|---|---|
| 上下文 | 继承完整对话历史 | 全新空上下文 |
| 系统提示 | 与主会话相同 | 来自定义文件 |
| Prompt Cache | 共享(更便宜) | 独立(更贵) |
| 权限 | 提示会弹到你的终端 | 后台自动拒绝 |
Fork 共享 prompt cache,因为系统提示和工具定义完全相同,这比新建子代理更经济。
技巧 2:持久记忆——跨会话学习
memory 字段让子代理拥有持久记忆:
---
name: project-expert
description: 项目专家,持续积累项目知识
memory: project
---
分析代码时,持续更新你的记忆。
三种范围:
| 范围 | 存储位置 | 适用场景 |
|---|---|---|
project | .claude/agent-memory/<name>/ | 项目特定知识,提交 Git 团队共享 |
user | ~/.claude/agent-memory/<name>/ | 跨项目的个人知识 |
local | .claude/agent-memory-local/<name>/ | 项目特定但不提交 Git |
使用技巧:
- • 调用前提醒:“检查你的记忆中已有的模式”
- • 完成后提醒:“把学到的东西保存到记忆”
- • 在 prompt 中写明:“发现代码路径、模式、架构决策时更新记忆”
技巧 3:Worktree 隔离——安全实验
isolation: worktree 让子代理在独立的 git worktree 中工作:
---
name: refactor-agent
isolation: worktree
tools: Read, Edit, Bash, Grep, Glob
---
好处:
- • 零风险:子代理的修改完全不影响主工作目录
- • 自动清理:无改动的 worktree 自动删除
- • 安全测试:可先让子代理尝试,效果好再合并
技巧 4:后台运行——Ctrl+B 切换
子代理可后台运行,你继续处理其他事务:
- • 自动后台:Claude 根据任务决定是否后台运行
- • 手动后台:按
Ctrl+B将正在运行的任务切到后台 - • Fork 模式:启用后所有子代理自动后台
后台子代理的权限行为:
- • 已授权的工具正常执行
- • 需要权限确认的工具自动拒绝
- • 失败后可用前台子代理重试
技巧 5:子代理 Hooks——精细化控制
子代理内部 Hooks
在子代理 frontmatter 中定义 Hooks,仅在子代理生命周期内生效:
---
name: safe-researcher
description: 只读研究代理
tools: Bash
hooks:
PreToolUse:
- matcher: "Bash"
hooks:
- type: command
command: "INPUT=$(cat); CMD=$(echo \"$INPUT\" | jq -r '.tool_input.command'); echo \"$CMD\" | grep -qiE '\\b(rm|drop|truncate)\\b' && echo 'Blocked' >&2 && exit 2 || exit 0"
---
项目级 Hooks 监控子代理
在 settings.json 中配置,当子代理启动或完成时自动触发:
{
"hooks": {
"SubagentStart": [
{
"matcher": "code-reviewer",
"hooks": [
{
"type": "command",
"command": "echo '[$(date)] code-reviewer started' >> ~/.claude/agent-log.txt"
}
]
}
],
"SubagentStop": [
{
"hooks": [
{
"type": "command",
"command": "echo '[$(date)] $(jq -r '.agent_type') stopped' >> ~/.claude/agent-log.txt"
}
]
}
]
}
}
常见问题(FAQ)
Q1:子代理与普通对话有什么区别?
| 维度 | 普通对话 | 子代理 |
|---|---|---|
| 上下文 | 主对话上下文 | 独立上下文窗口 |
| 上下文占用 | 搜索/审查结果塞满主对话 | 只返回摘要 |
| 工具权限 | 使用所有工具 | 可限制工具 |
| 并行 | 不能 | 可以多个子代理并行 |
| 成本 | 便宜 | 多个子代理各自消耗 Token |
Q2:子代理与 Skills 有什么区别?
| 维度 | Skills | 子代理 |
|---|---|---|
| 本质 | 主对话中的可复用提示 | 独立上下文的 AI 助手 |
| 上下文隔离 | 不隔离,在主对话中运行 | 隔离,独立上下文窗口 |
| 工具限制 | 通过 allowed-tools 软限制 | 通过 tools / disallowedTools 硬限制 |
| 适用 | 需要主对话上下文的任务 | 产生大量输出的任务 |
简单任务用 Skills,重量级任务用子代理。
Q3:何时用子代理,何时用代理团队?
- • 用子代理:任务聚焦,只需返回结果。例如代码搜索、测试运行、代码审查。
- • 用代理团队:任务复杂,需要多个 AI 协作讨论。例如竞争假说调查、跨层开发、多维度审查。
- • 用 Fork:子代理需要主对话的上下文才能工作。例如“根据我们刚才讨论的方案写测试”。
Q4:子代理消耗多少 Token?
- • 每个子代理拥有独立上下文窗口,各自消耗 Token
- • 子代理完成后只返回摘要,主对话不承担完整输出
- •
model: haiku可大幅降低子代理成本 - • Fork 模式共享 prompt cache,比新建子代理更便宜
- • 代理团队每个队友是独立实例,Token 成本最高
Q5:子代理能嵌套吗?
不能。子代理不能在内部再派子代理,这是硬性限制。如需多级编排,可使用 tools: Agent(worker, researcher) 限制子代理能调用哪些其他子代理——但这仅在主线程(claude --agent)中生效。
Q6:Fork 与普通子代理的区别?
| Fork | 普通子代理 | |
|---|---|---|
| 上下文 | 继承完整对话历史 | 全新空上下文 |
| 适合 | “根据我们刚才的讨论继续” | “审查这个新文件” |
| 成本 | 共享 prompt cache,更便宜 | 独立 cache |
| 启用 | CLAUDE_CODE_FORK_SUBAGENT=1 | 默认 |
总结
Claude Code Agents 体系
子代理
代理团队
Fork 模式
内置 5 个
自定义 17 个字段
15 个实战模板
Leader + Teammates
共享任务列表
3 个实战场景
继承对话历史
共享 Prompt Cache
/fork 命令
通过本文,你已收获:
- • ✓ 子代理核心原理——独立上下文、专业角色、只返回摘要
- • ✓ 内置子代理(Explore / Plan / general-purpose)的用途
- • ✓ 17 项配置字段(工具控制、模型选择、权限模式、持久记忆等)
- • ✓ 15 个实战模板,覆盖审查、开发、研究、工作流、进阶玩法
- • ✓ 代理团队多 AI 协作(Leader + Teammates + 共享任务列表)
- • ✓ 5 个进阶技巧(Fork 模式、持久记忆、Worktree 隔离、后台运行、Hooks)
- • ✓ 6 个常见问题的解决方案
核心理念:CLAUDE.md 告诉 AI“项目规范是什么”,Hooks 告诉 AI“什么能做什么不能做”,Skills 告诉 AI“具体怎么干活”,Agents 告诉 AI“哪些活可以外包给专业 AI”。四者协同,AI 能成为真正高效的编程搭档。
延伸阅读
- • Claude Code 官方文档 - Subagents[1]
- • Claude Code 官方文档 - Agent Teams[2]
引用链接
[1] Claude Code 官方文档 - Subagents: https://code.claude.com/docs/en/sub-agents[2] Claude Code 官方文档 - Agent Teams: https://code.claude.com/docs/en/agent-teams