前言
说到 Claude Code CLI，很多人可能还停留在"会写代码的 AI 助手"这个印象。但今天要聊的子代理（Subagent）功能，可以说是把这个工具玩出了新高度。
想象一下，你开了一家餐厅。刚开始规模小的时候，老板既当厨师又当服务员还兼职收银员，啥都自己干。但餐厅做大了呢？你肯定得招人，让专业的厨师负责炒菜，服务员负责上菜，收银员负责结账。每个人干自己擅长的事，整个餐厅才能高效运转。
Claude Code 的子代理就是这个道理。主 Agent 就像老板，负责统筹全局；子 Agent 就像员工，各有专长。有的专门审查代码质量，有的负责找安全漏洞，有的擅长性能优化，有的专攻测试覆盖。这样一来，不仅效率更高，而且每个任务都能得到更专业的处理。
子代理的四大优势
1. 上下文保留（Context Preservation）
这就像你在家里吃饭和在公司开会，两个场景完全分开。在家里你可以随便聊天，但不会把家里的琐事带到公司会议上。子代理也是这样，每个子代理都有自己独立的"工作空间"，处理任务时不会被主对话的上下文干扰，也不会污染主对话的环境。
比如你让一个子代理去检查代码中的安全漏洞，它不需要知道你之前和主 Agent 聊了什么家常，只需要专注于眼前的代码就好。这样既保持了专注，又避免了信息过载。
2. 专业知识（Specialized Expertise）
就像你去医院看病，眼科医生看眼睛，骨科医生看骨折，每个医生都在自己的专业领域深耕。子代理也是如此，你可以针对不同的任务类型，给每个子代理配置专门的提示词和工作方式。
审查代码质量的子代理可能特别关注 SOLID 原则、命名规范、代码整洁度；而检查安全的子代理则重点关注注入风险、身份验证、数据加密等。各司其职，术业有专攻。
3. 可重用性（Reusability）
这个就更好理解了。你辛辛苦苦培养出一个优秀的代码审查员，肯定希望他能在所有项目里都发挥作用，而不是每次换个项目就得重新培训一遍。
Claude Code 的子代理创建一次，就可以在不同项目中反复使用，甚至可以分享给团队成员。这样整个团队的工作流程都能保持一致，新人上手也更快。
4. 灵活的权限（Flexible Permissions）
这就像公司里的权限管理。前台不需要访问财务系统，销售也不需要接触研发代码库。不同角色有不同的权限范围。
在 Claude Code 里，你可以为每个子代理设置不同的工具访问权限。有些子代理可能只需要读取代码，有些可能需要运行测试，有些可能需要修改文件。根据任务需求灵活配置，既安全又高效。
子代理的配置方式
Claude Code 提供了两种配置子代理的方式，就像你可以把员工分为"全职员工"和"外包人员"。
项目子代理（Project Subagents）
这就是你的"全职员工"，专门为某个项目服务。配置文件放在项目根目录的 .claude/agents/ 文件夹里。这些子代理只在当前项目生效，优先级最高。
比如你做一个电商项目，可能需要一个专门检查支付安全的子代理；做一个数据分析项目，可能需要一个专门优化查询性能的子代理。这些都是项目特定的需求，用项目子代理最合适。
用户子代理（User Subagents）
这就是你的"通用顾问"，在所有项目里都能用。配置文件放在用户目录的 ~/.claude/agents/ 文件夹里。这些子代理适合做一些通用任务，比如代码风格检查、基础测试覆盖等。
需要注意的是，当项目子代理和用户子代理同名时，项目子代理优先级更高。就像公司的正式员工肯定比外包更了解项目情况一样。
主 Agent 和子 Agent 的关系
这里有个很重要的概念：主 Agent 和子 Agent 是隔离的，就像不同的部门有各自的办公室。
想象一下这个场景：你（用户）给老板（主 Agent）安排了一堆任务。老板一看，哦，这个任务需要检查代码质量，那就叫质检员（code-reviewer 子代理）来；那个任务需要测试，就叫测试工程师（test-runner 子代理）来。
每个子代理接到任务后，就回到自己的"办公室"（独立环境）开始工作，完成后把结果交给老板。老板汇总所有结果，最后向你汇报。
这样的好处是什么呢？
- 上下文不会混乱：质检员不需要知道测试工程师在干什么，各自专注自己的任务
- 可以节省资源：如果主 Agent 的上下文已经很大了，可以把部分任务拆给子代理，变相减轻主 Agent 的负担
- 任务可以并行：多个子代理可以同时工作，就像多个员工同时处理不同的任务，效率更高
子代理的配置格式
每个子代理都是一个 Markdown 文件，格式很简单，就像填一张员工信息表：
---
name: code-reviewer
description: 代码进行质量与可维护性审查
tools: Read, Grep, Bash
model: sonnet
color: red
---
你是一个经验丰富的代码审查员，非常擅长发现代码中的问题。
审查时请重点关注：
- 代码整洁原则
- SOLID 原则
- DRY 原则
- 命名规范
这里面几个关键字段：
- name：子代理的名字，就像员工的工号
- description：子代理的职责描述，告诉主 Agent 什么时候该叫这个子代理出来干活
- tools：子代理可以使用的工具列表，不填的话就是所有工具都能用
- model：子代理用的模型，可以根据任务难度选择合适的模型
- color：显示时的背景色，纯粹是为了好看和区分
下面的正文部分就是子代理的"工作手册"，详细说明它的角色、技能、工作方式、注意事项等。写得越详细，子代理的表现就越专业。
实战：创建你的第一个子代理
理论说了这么多，来点实际的。假设我们要创建一个代码审查员。
第一步：创建配置文件
在项目根目录创建 .claude/agents/code-reviewer.md 文件：
---
name: code-reviewer
description: 对代码进行质量与可维护性审查
model: sonnet
color: red
---
你是一个资深的代码审查员，有 10 年的开发经验。
审查代码时，请像老师批改作业一样认真，但态度要温和友好。
重点检查这几个方面：
1. 代码是否清晰易懂（命名、注释、结构）
2. 是否遵循设计原则（SOLID、DRY）
3. 有没有明显的 bug 或隐患
4. 有没有性能问题
5. 代码风格是否统一
给出建议时，请说明为什么要这样改，不要只说"这里不好"。
第二步：重启 Claude Code
创建好配置文件后，重启一下 Claude Code CLI，让它识别新的子代理。
第三步：使用子代理
现在你有两种方式使用这个子代理：
隐式调用（让 AI 自己判断）：
帮我审查一下最近的代码改动
AI 看到"审查"这个词，再看看 code-reviewer 的 description，就知道该用这个子代理了。
显式调用（明确指定）：
使用 code-reviewer 子代理审查我的最新改动
这样就是明确告诉 AI 用哪个子代理，不用它自己猜。
进阶玩法：多子代理协作
有了一个子代理，当然就能有第二个、第三个。咱们再创建几个：
security-auditor.md：安全审计员，专门找安全漏洞performance-engineer.md：性能工程师，专门优化性能test-automator.md：测试专员，专门检查测试覆盖
串行调用：一个接一个
就像流水线作业，先做这个再做那个：
先用 code-reviewer 审查代码质量，
然后用 security-auditor 检查安全问题，
最后用 performance-engineer 分析性能
AI 会按顺序调用这三个子代理，每个子代理完成后，下一个接着干。
并行调用：同时开工
如果任务之间没有依赖关系，可以让多个子代理同时工作：
同时使用 security-auditor 和 performance-engineer 检查这段代码，
最后把结果汇总给我
这就像让多个员工同时工作，效率显然更高。
终极玩法：自定义命令搭建工作流
如果你经常需要执行一套固定的检查流程，每次都要打一长串命令显然太麻烦。这时候就可以用自定义命令（Custom Commands）来简化操作。
比如我们创建一个"全面审查"命令，一次性调用四个子代理：
在 .claude/commands/full-review.md 中写入：
---
description: 全面的代码审查
argument-hint: [传入审查内容]
model: sonnet
---
执行多个子代理对 $ARGUMENTS 进行全面审查，要求并行执行：
1. 代码质量检查 - 调用 code-reviewer 子代理
2. 安全审查 - 调用 security-auditor 子代理
3. 性能分析 - 调用 performance-engineer 子代理
4. 测试覆盖率评估 - 调用 test-automator 子代理
最后请把所有反馈整理成一份报告，按优先级分为：
- 关键问题（必须修复）
- 推荐修复（应该修复）
- 优化建议（可以考虑）
- 做得好的地方（值得保持）
重启 Claude Code 后，只需要一行命令：
/full-review @index.py
四个子代理就会同时开工，各自完成任务后，主 Agent 会把结果汇总成一份完整的审查报告。这效率，简直不要太爽。
实用技巧和注意事项
提示词不用自己从头写
很多人一听要写提示词就发怵，其实完全不用担心。Github 上有大量现成的子代理配置，搜索"claude code subagent"就能找到一堆。拿来稍微改改，调整成符合你项目需求的样子就能用。
就像做菜不一定要自己发明菜谱，照着食谱做，再根据自己口味调整调整，也能做出好吃的菜。
合理设置工具权限
不是所有子代理都需要所有工具的访问权限。比如一个纯粹做静态分析的子代理，可能只需要 Read 和 Grep，不需要 Write 和 Bash。
这就像公司权限管理，该给的给，不该给的别乱给，既安全又避免误操作。
善用颜色区分
虽然 color 字段看起来只是装饰，但当你同时用多个子代理时，不同颜色能让你一眼看出哪个子代理在说话。红色是审查员，黄色是安全员，绿色是性能工程师，蓝色是测试员——清清楚楚，一目了然。
项目级和用户级合理搭配
通用的子代理（比如基础代码审查、简单测试检查）可以放在用户级，所有项目都能用。项目特定的子代理（比如特定框架的检查、业务规则验证）放在项目级。
这样既能重用通用能力，又能满足项目特殊需求。
总结
Claude Code 的子代理机制，本质上就是把"一个人干所有活"变成"一个团队分工协作"。每个子代理都有自己的专长和工作环境，互不干扰又能协同配合。
合理使用子代理，可以：
- 让每个任务都得到更专业的处理
- 避免上下文污染，保持任务焦点
- 提高工作效率，支持并行处理
- 建立可复用的工作流，降低重复劳动
说白了，就是把 AI 助手从"全能选手"升级成"专业团队"。你作为"项目经理"，只需要把任务分配好，剩下的交给专业的"员工"去处理。
这不仅是技术上的进步，更是工作方式的革新。从此以后，你的 Claude Code 不再是一个孤军奋战的助手，而是一支各有所长的精英团队。
想想看，下次写代码的时候，身边站着代码审查员、安全专家、性能工程师、测试工程师……这阵容，是不是很安心？
写在最后
其实这篇文章也是我在实际使用 Claude Code 子代理过程中的一些心得体会。刚开始用的时候，我也觉得配置子代理挺麻烦的，直到有一次项目要做安全审计，四五个检查项，一个个手动跑下来得半天。后来配了几个子代理，一条命令全搞定，那感觉就像突然多了几个助手。
AI 工具这东西，发展实在太快了。前两年还在讨论 AI 能不能写代码，现在已经开始讨论怎么让 AI 团队协作了。如果你也在关注 AI 编程工具的发展，或者想交流一些实战经验，欢迎关注我的公众号"梦兽编程"。我会持续分享一些 AI 工具的使用技巧和踩坑经验，也会聊聊对这个领域的一些思考。
毕竟这个领域变化太快，一个人摸索总是有局限的，大家一起交流，才能少走弯路。