🤖 Claude Code Agent Team 完整指南

子代理（Subagents）设计理念、应用场景与使用详解

一、什么是 Agent Team？

二、设计理念

三、解决什么问题

痛点	解决方案
上下文窗口被探索污染	子代理在独立上下文中工作，结果返回主对话
单一模型处理所有任务成本高	子代理可使用不同模型（Haiku/Sonnet/Opus）
工具权限难以精细控制	可为子代理单独配置允许/禁止的工具
重复创建相同任务指令	一次配置，随处使用
复杂任务难以分工	多个子代理协同工作，各司其职

四、应用场景

场景 1：代码审查团队

• 代码审查代理 - 专门审查代码质量和安全
• Bug 追踪代理 - 分析错误日志，定位问题
• 性能优化代理 - 分析性能瓶颈

场景 2：测试自动化

• 单元测试代理 - 为代码生成测试用例
• E2E 测试代理 - 编写端到端测试
• 测试分析代理 - 分析测试覆盖率

场景 3：文档生成

• API 文档代理 - 自动生成 API 文档
• 注释生成代理 - 为代码添加注释
• 变更日志代理 - 生成版本更新日志

场景 4：数据处理

• 数据清洗代理 - 清洗和转换数据
• 数据分析代理 - 分析数据趋势
• 报表生成代理 - 生成数据报表

五、内置子代理

子代理	模型	工具权限	用途
Explore	Haiku	只读（无 Write/Edit）	代码搜索、探索、分析
Plan	继承主对话	只读	计划模式下的研究代理
General-purpose	继承主对话	全部工具	复杂多步骤任务
Bash	继承主对话	终端命令	在独立上下文中运行命令
Claude Code Guide	Haiku	-	回答 Claude Code 功能问题

六、创建子代理

方式 1：使用 /agents 命令（推荐）

# 打开子代理管理界面
/agents

然后按提示创建新子代理。

方式 2：手动创建文件

# 项目级子代理
.claude/agents/code-reviewer.md

# 用户级子代理
~/.claude/agents/code-reviewer.md

子代理文件格式

---
name: code-reviewer
description: 代码审查专家，专注于代码质量和安全
tools:
  - Read
  - Glob
  - Grep
model: sonnet
permissionMode: auto-accept
maxTurns: 10
---

你是代码审查专家。当被调用时，分析代码并提供具体、可操作的反馈，重点关注：
1. 代码质量
2. 安全漏洞
3. 最佳实践
4. 性能优化

请提供详细的审查报告，包括问题描述、严重程度和修复建议。

七、配置详解

支持的前端字段

字段	类型	说明
name	string	子代理名称
description	string	描述（让 Claude 知道何时调用）
tools	array	允许使用的工具列表
disallowedTools	array	禁止使用的工具列表
model	string	使用的模型（haiku/sonnet/opus）
permissionMode	string	权限模式（normal/auto-accept/plan）
maxTurns	number	最大对话轮数
skills	array	附加的技能列表
hooks	array	钩子配置

八、作用域与优先级

位置	作用域	优先级	创建方式
--agents CLI 参数	当前会话	1（最高）	启动时传入 JSON
.claude/agents/	当前项目	2	交互式或手动
~/.claude/agents/	所有项目	3	交互式或手动
插件目录	插件启用时	4（最低）	安装插件

九、使用示例

示例 1：代码审查代理

---
name: code-reviewer
description: 代码审查专家，用于代码变更审查
tools:
  - Read
  - Glob
  - Grep
  - Bash
model: sonnet
---

你是高级代码审查专家。分析代码变更并提供：
1. 代码质量问题
2. 安全漏洞检查
3. 最佳实践建议
4. 潜在性能问题

提供具体、可操作的修复建议。

示例 2：调试专家代理

---
name: debugger
description: 调试专家，用于分析和修复错误
tools:
  - Read
  - Grep
  - Bash
model: sonnet
---

你是调试专家。当被调用时：
1. 分析错误信息和堆栈跟踪
2. 定位问题根因
3. 提供修复方案
4. 如需要，运行测试验证修复

示例 3：低成本探索代理

---
name: fast-explorer
description: 快速代码探索，用于快速查找文件
tools:
  - Read
  - Glob
  - Grep
model: haiku
---

你是快速代码探索代理。使用最少的 token 快速回答问题。
- 保持回答简洁
- 只提供关键信息
- 避免长篇解释

示例 4：通过 CLI 启动

claude --agents '{
  "code-reviewer": {
    "description": "代码审查专家",
    "prompt": "你是高级代码审查专家...",
    "tools": ["Read", "Glob", "Grep"],
    "model": "sonnet"
  },
  "debugger": {
    "description": "调试专家",
    "prompt": "你是调试专家...",
    "tools": ["Read", "Bash"],
    "model": "sonnet"
  }
}'

十、最佳实践

十一、总结