深入了解Claude Code CLI子代理Subagent

前言

前面对Claude Code CLI有了基本了解，今天继续深度探索Claude Code CLI Subagent的使用方式。对往期内容感兴趣的小伙伴也可以看往期内容：

当前使用版本

1.0.128 (Claude Code)

主要优势

Context preservation(上下文保留)：每个子代理都在自己的环境中运行，防止主要对话受到污染，并使其专注于高级目标。
Specialized expertise(专业知识)：子代理可以通过针对特定域的详细说明进行微调，从而提高指定任务的成功率。
Reusability(可重用)：创建后，子代理可以在不同的项目中使用，并与您的团队共享，以实现一致的工作流程。
Flexible permissions(灵活的权限)：每个子代理可以具有不同的工具访问级别，允许您将强大的工具限制为特定的子代理类型。

Subagent配置

当子代理名称冲突时，项目级子代理优先于用户级子代理

在Claude Code CLI中Subagent提供 Project subagents(项目子代理) 和 User subagents(用户子代理) 2种配置：

项目子代理：针对特定项目生效，路径：项目根目录/.claude/agents/，优先级最高
用户子代理：针对所有项目生效，路径：~/.claude/agents/，优先级较低

Subagent与主Agent交互形式

通过Claude Code CLI官方文档我们可以了解到，主Agent和子Agent环境是隔离的，每个子Agent都有自己独立的运行环境，大致交互流程如下：

由此我们也可以理解为子代理的上下文不会受主Agent上下文的影响，也不会影响主Agent的上下文大小，对于复杂和庞大上下文的任务，我们可以将任务拆分为多个子Agent协同完成，变相的对上下文进行拆分。

Subagent格式

每个子代理都定义在具有以下结构的 Markdown 文件中：

yaml 复制代码

---
name: your-sub-agent-name
description: Description of when this subagent should be invoked
tools: tool1, tool2, tool3  # Optional - inherits all tools if omitted
model: sub-agent-model
color: sub-agent-backgroundcolor
---
Your subagent's system prompt goes here. This can be multiple paragraphs
and should clearly define the subagent's role, capabilities, and approach
to solving problems.
Include specific instructions, best practices, and any constraints
the subagent should follow.

Frontmatter属性：

name：子代理名称
description：描述子代理功能及何时应该调用此子代理
tools：可使用工具列表，如果省略，则允许使用所有工具
model：子代理使用的模型
color：子代理展示的背景色

Subagent提示词内容一般可以按照下面几个方面来写：

角色定位：说明子代理的角色、擅长领域，比如"你是一个软件测试工程师，非常擅长发现代码中的隐藏问题"
工作方式与标准：描述技能要求、最佳实践、风格指南或限制。
示例（可选）：若任务复杂，可在正文里放几个输入输出示例，帮助 Claude 更准确理解。

基本使用

Claude Code CLI提供了创建Subagent的交互式命令，对交互式命令创建Hooks流程还不了解的小伙伴可以看往期内容：Claude Code CLI初体验

在使用示例中我们主要以使用手动配置为主，对于不会写Agent提示词的小伙伴来说可能有些手足无措，但是不用担心，网上有很多大佬整理的提示词可以供我们借鉴，例如我们可以到Github上检索Subagent提示词，可以有很多人整理了subagent提示词，我们可以直接复制并稍作修改，调整的更符合我们项目要求。

显/隐式调用

在Claude Code CLI中有隐式调用和显示调用 2种使用子代理的方式，用白话讲就是模型推理和指定代理名称调用。

我们代码审查子代理为例，在项目工作区创建 .claude/agents/code-reviewer.md 文件

重启Claude Code CLI，隐式调用我们可以这么用：

复制代码

帮我审查最近修改的改动

或者这么用，表明需要进行代码审查

复制代码

使用代码审查员来审查所有代码更改

显示调用，就是明确告诉AI使用指定的子代理

css 复制代码

使用code-reviewer子代理review我最近的修改

多子代理

在Claude Code CLI中支持创建和使用多个子代理，我们可以在项目工作区 .claude/agents/ 目录下创建 code-reviewer.md、test-runner.md、debuger.md 3个子代理

重启Claude Code CLI，在交互式命令输入 /agents 可以看到已创建的3个子代理

串并行子代理

在Claude Code CLI中多子代理可以串行调用也可以并行调用，例如我们在代码中写一段错误代码

我们可以要求AI先对代码使用 code-reviewer子代理进行审查，然后使用 debugger子代理找到错误原因

typescript 复制代码

@index.py 首先使用 code-reviewer 子代理查看我最近的修改，然后使用 debugger 子代理检查错误原因

可以看到Claude Code CLI先是调用了 code-reviewer子代理，接着又调用了 debugger子代理

除了串行调用，我们也可以并行调用多个子代理进行任务处理，我们前面创建的 debugger子代理和 test-runner子代理中都有分析错误的提示词，可以让他们并行检查错误，最终汇总错误。

typescript 复制代码

使用 debugger 子代理和 test-runner 子代理并行检查 @index.py 中错误，最后汇总输出错误原因

可以看到Claude Code CLI先是同时调用了 debugger子代理和 test-runner子代理，并不是等debugger子代理调用结束再调用test-runner子代理

自定义命令搭建agent工作流

在Claude Code CLI中可以通过自定义命令调用子代理，借助这一特性，我们可以在自定义命令中使用结构化提示词的方式指定调用不同的子代理完成不同的任务。

依次在项目工作区 .claude/agents/ 目录下创建 code-reviewer.md、security-auditor.md、performance-engineer.md、test-automator.md 子代理

code-reviewer.md

yaml 复制代码

---
name: code-reviewer
description: 代码进行质量与可维护性审查
model: sonnet
color: red
---
对以下代码进行质量与可维护性审查：$ARGUMENTS。检查代码异味、可读性、文档完整性及最佳实践遵循情况
## 重点：
- 代码整洁原则
- SOLID 原则
- DRY 原则
- 命名规范

security-auditor.md

yaml 复制代码

---
name: security-auditor
description: 对内容进行安全审计
model: sonnet
color: yellow
---
对以下内容进行安全审计：$ARGUMENTS。检查漏洞、OWASP合规性、认证问题及数据保护措施
# 重点: 
- 注入风险
- 身份验证
- 授权机制
- 数据加密

performance-engineer.md

yaml 复制代码

---
name: performance-engineer
description: 对内容进行性能分析
model: sonnet
color: green
---
分析以下内容的性能特征：$ARGUMENTS。识别瓶颈、资源使用情况以及优化机会
## 重点: 
- 响应时间
- 内存使用情况
- 数据库查询
- 缓存

test-automator.md

yaml 复制代码

---
name: test-automator
description: 对内容进行测试覆盖范围与质量分析
model: sonnet
color: blue
---
评估以下内容的测试覆盖范围与质量：$ARGUMENTS。检查单元测试、集成测试，并识别测试覆盖中的空白。
## 重点: 
- 覆盖率指标
- 测试质量
- 边界情况
- 测试可维护性

在项目工作区 .claude/commands/ 目录 full-review.md 自定义命令，提示词启发来自：zhuanlan.zhihu.com/p/194381363...

yaml 复制代码

---
description: 全面的代码审查
argument-hint: [传入审查内容]
model: sonnet
---
执行多个子代理对 $ARGUMENTS 进行全面审查，要求并行执行审查：
## 1. 代码质量检查
- 调用 code-reviewer 子代理
## 2. 安全审查
- 调用 security-auditor 子代理
## 3. 性能分析
- 调用 performance-engineer 子代理
## 4. 测试覆盖率评估
- 调用 test-automator  子代理
## 合并报告结构
将所有反馈整理成一份统一报告:
- **关键问题** (必须修复): 安全漏洞、功能故障、架构缺陷
- **推荐** (应该修复): 性能瓶颈、代码质量问题、测试缺失
- **建议** (建议修复): 重构机会，文档改进
- **正面反馈** (哪方面做得好): 良好实践以维护和复制
目标: $ARGUMENTS

重启Claude Code CLI，执行 /full-review 命令，可以看到Claude Code CLI同时调用了4个子代理

最后给出了一个完整的分析报告

友情提示

见原文：深入了解Claude Code CLI子代理Subagent

本文同步自微信公众号 "程序员小溪" ，这里只是同步，想看及时消息请移步我的公众号，不定时更新我的学习经验。友情提示友情提示