前言：在上一篇《ClaudeCode 实战指南（四）：一键安装配置教程》中，我们成功把 Claude Code 跑起来了。今天，我们要进入它最强大的功能领域——SubAgent（子代理）。学会这个，你就不再是一个人在写代码，而是拥有了一支随时待命的专家团队。
🧭 一、核心摘要
本文将带你深入理解 Claude Code 的 SubAgent 机制。我们将从零开始，解析其工作原理、配置规则，提供快速导入方案与最佳实践，并附带官方文档与社区模板资源，助你构建一支高效的 AI 开发团队。
🔍 二、基本介绍：什么是 SubAgent？
在 Claude Code 的生态中，SubAgent（子代理）是将通用 AI 转化为特定领域专家的关键机制。
如果把主 Agent比作一位全能的项目经理，负责理解你的意图、拆解任务和统筹规划；那么SubAgent就是一位位专职工程师。它们拥有独立的上下文和特定的工具权限，专注于解决单一领域的复杂问题。
核心角色分工
| 角色 | 职责 | 类比 |
|---|---|---|
| 主 Agent | 任务分发、流程控制、结果整合 | 项目经理 / 架构师 |
| SubAgent | 代码审查、测试生成、性能分析 | 后端开发 / 测试工程师 / 安全专家 |
⚙️ 三、工作原理：它们是如何协作的？
SubAgent 的核心价值在于“上下文隔离”和“专业化分工”。主 Agent 不会把所有代码都读进自己的上下文（这很贵且容易乱），而是委托 SubAgent 去处理，从而保持主线程的清晰和高效。
协作流程图
📂 四、文件位置与优先级
Claude Code 通过读取特定目录下的 Markdown 文件来加载 SubAgent。理解文件位置是管理团队协作的关键。
4.1 存储路径
| 类型 | 路径 | 适用场景 | 优先级 |
|---|---|---|---|
| 项目级 | .claude/agents/*.md | 团队协作。配置随代码库提交,所有成员共享。 | 最高🥇 |
| 用户级 | ~/.claude/agents/*.md | 个人工具箱。跨项目通用的私人助手。 | 中等 🥈 |
| 插件级 | (由插件提供) | 第三方扩展提供的通用能力。 | 最低 🥉 |
4.2 加载规则
系统会自动扫描上述目录。
如果存在同名 Agent（例如都叫
code-reviewer），项目级配置会覆盖用户级配置。这允许你针对特定项目微调通用的 Agent 行为。
🛠️ 五、配置规则与快速导入方式
一个 SubAgent 本质上就是一个带有YAML 前置元数据的 Markdown 文件。
5.1 配置文件结构详解
一个标准的 SubAgent 文件（如code-reviewer.md）包含两部分：
第一部分：YAML 配置头 (必需)
--- name: code-reviewer # 唯一标识符 (调用时使用) description: 代码审查专家，专注于代码质量和安全 # 主 Agent 根据此描述决定是否调用 tools: Read, Grep, Glob # 授予的工具权限 (最小权限原则) model: sonnet # 指定模型 (sonnet/opus/haiku) ---第二部分：System Prompt (核心指令)
这是 Markdown 的正文部分，定义了 AI 的人设、工作流程和输出格式。
# 角色定义 你是一位资深架构师... # 核心职责 1. 检查命名规范 2. 识别 N+1 查询问题... # 输出格式 请以 Markdown 列表形式输出问题，按严重程度排序...5.2 快速导入与创建方式
方式 A：命令行快速创建 (推荐初次使用)
直接在对话中让 Claude 帮你生成模板：
claude > create a new subagent for unit testing系统会引导你选择范围（项目级/用户级）并自动生成文件。
方式 B：手动创建文件 (推荐进阶配置)
直接在.claude/agents/目录下新建.md文件。示例：创建.claude/agents/security-check.md
方式 C：CLI 动态定义 (临时测试用)
如果你不想创建文件，只想临时测试一个 Agent，可以使用命令行参数：
claude --agents '{ "quick-fix": { "description": "快速修复语法错误", "tools": ["Read", "Write"], "model": "haiku" } }' --prompt "Fix the syntax error in main.js"💡 六、最佳实践：如何写好 SubAgent？
要让 SubAgent 真正发挥作用，不仅要配置对，还要设计好。以下是经过验证的四个最佳实践。
6.1 编写"触发式"描述 (Description)
主 Agent 是根据description字段来决定是否召唤 SubAgent 的。
❌坏的描述：
处理代码(太模糊，主 Agent 不知道何时用它)✅好的描述：
代码审查专家，负责检查 Java 代码的安全性、性能瓶颈和命名规范(包含关键词和具体职责)
6.2 权限最小化原则 (Tools)
只给 SubAgent 完成任务所需的最小工具集，既安全又高效，防止 AI 误操作。
分析类 Agent（如代码审查）：仅需
Read,Grep,Glob。不要给 Write 权限。生成类 Agent（如测试生成）：需要
Read,Write。执行类 Agent（如构建脚本）：才需要
Bash。
6.3 结构化 Prompt 设计
不要只给一句话指令。在 Markdown 正文中，使用清晰的标题结构：
角色 (Role): “你是一个…”
目标 (Goal): “你的任务是…”
工作流 (Workflow): “第一步读取文件，第二步分析…”
输出规范 (Output): “必须包含具体的代码行号和修改建议…”
6.4 团队协作工作流
将.claude/agents目录纳入 Git 版本控制，实现团队能力的“代码化”。
在项目根目录创建
.claude/agents/。添加通用的
code-reviewer.md和test-generator.md。提交到 Git。
团队成员
git pull后，直接输入> 审查我的代码，即可使用统一标准的审查助手。
📚 七、扩展阅读与资源
想要深入研究参数细节，或者直接下载现成的高质量 Agent 模板？请参考以下资源：
1. 官方文档 (权威指南)
地址: https://code.claude.com/docs/zh-CN/sub-agents
内容: 包含最新的参数说明、API 变更以及官方推荐的安全配置指南。
2. 社区 Agent 仓库 (实战模板)
地址: https://github.com/wshobson/agents
内容: 这是一个非常棒的开源仓库，收集了大量现成的 SubAgent 配置文件（例如：Python 专家、React 组件生成器、SQL 优化器等）。
用法: 下载其中的
.md文件放入你的.claude/agents/目录，立刻拥有专家能力。
📝 八、结语
SubAgent 机制是 Claude Code 最强大的特性之一。它将原本线性的 AI 对话，升级为多维度的专家协作。
通过简单的 Markdown 配置，你可以：
固化团队知识：将资深工程师的审查标准写入 Prompt。
提升自动化水平：让 AI 自动处理繁琐的测试编写和格式化工作。
降低认知负荷：你只管提需求，让专门的 Agent 去处理细节。
👉下一步：建议先下载wshobson/agents仓库中的模板，试着运行一次代码审查，体验一下拥有“AI 专家团队”的感觉！🚀
本文是《ClaudeCode 实战指南》系列的第五篇，更多 AI 编程实战技巧，欢迎关注 晨启AI。
