创建子代理

创建子代理

摘要文字记录

Claude Code 自带内置子代理，但您也可以创建自己的子代理。自定义子代理专注于特定任务——比如审查代码、编写测试或检查文档。它们被定义为带有 YAML 前置元数据的 markdown 文件，该元数据告诉 Claude 何时使用该子代理以及该子代理应如何行事。

创建子代理最简单的方法是让 Claude 为您编写。描述您想要的子代理以及保存位置，Claude 就会编写该文件。本课中的视频和前三张截图展示的是 /agents 向导，该向导已在 Claude Code v2.1.198 中被移除。子代理文件及其字段保持不变，因此您仍需选择作用域、工具、模型和颜色。请在您的请求中包含这些选择。

首先，选择子代理的作用域。.claude/agents/ 中的文件是项目级的，而 ~/.claude/agents/ 中的文件是用户级的：

项目级 —— 仅在当前项目中可用
用户级 —— 在您机器上的所有项目中共享

接下来，您可以选择如何创建它。您可以手动编写配置，但推荐的方法是让 Claude 为您生成。只需描述您希望子代理执行的操作，Claude 就会根据您的输入生成名称、描述和系统提示。

Claude Code 中的 /agents create-new-agent 流程，创建方式包括"使用 Claude 生成（推荐）"和"手动配置"

自定义工具

在创建过程中，您有机会自定义子代理可以访问哪些工具。工具类别包括：

只读工具
编辑工具
执行工具
MCP 工具
其他工具

代理创建的"选择工具"步骤，带有"所有工具"、"只读工具"、"编辑工具"、"执行工具"、"MCP 工具"和"其他工具"的复选框

请考虑您的子代理实际需要什么。代码审查员可能不需要编辑工具——它应该读取和分析代码，而不是更改代码。不过，您可能希望保持执行工具启用，以便它能更轻松地识别待处理的更改。

选择模型和颜色

配置完工具后，您需要选择为子代理提供支持的 Claude 模型。您的选项包括：

Haiku —— 最适合快速、轻量级的任务
Sonnet —— 在速度和深度之间取得良好平衡
Opus —— 最适合复杂分析
继承（Inherit） —— 使用您主对话正在运行的任何模型

最后，您选择一种颜色。这会显示在 UI 中，以便您能快速分辨哪个子代理处于活动状态。这是一个小细节，但当您同时运行多个子代理时会很有帮助。

代理创建的"选择背景颜色"步骤，显示颜色列表以及以青色高亮显示的 code-quality-reviewer 名称预览

配置文件

创建完成后，子代理配置文件会保存在您所选作用域对应的文件夹中（对于项目级子代理，通常是 .claude/agents/your-agent-name.md）。以下是一个典型子代理配置的样子：

markdown

---
name: code-quality-reviewer
description: Use this agent when you need to review recently written or modified code for quality, security, and best practice compliance.
tools: Bash, Glob, Grep, Read, WebFetch, WebSearch
model: sonnet
color: purple
---

You are an expert code reviewer specializing in quality assurance, security best practices, and
adherence to project standards. Your role is to thoroughly examine recently written or modified code
and identify issues that could impact reliability, security, maintainability, or performance.

让我们逐一分解每个字段：

name —— 子代理的唯一标识符。这是您引用它的方式，可以直接向 Claude 提问，也可以在消息中输入 @agent-code-quality-reviewer。
description —— 控制 Claude 何时决定使用该子代理。这必须是单行内容（如果需要换行，请使用转义的换行符 \n）。您可以在此处包含示例对话，以帮助 Claude 理解何时适合委派任务。
tools —— 列出子代理可以访问的工具。Claude 会根据您的请求填写此项，但您可以随时在此处编辑该列表。
model —— 指定要使用的 Claude 模型：可以是别名（sonnet、opus、haiku 或 fable）、完整的模型 ID（如 claude-sonnet-5），或 inherit。
color —— 用于标识子代理的 UI 颜色。

系统提示

markdown 文件的正文（YAML 前置元数据以下的所有内容）就是系统提示。您在这里为子代理提供指令：它应该关注什么、应该如何分析事物，以及应该如何向主代理报告发现。

一个写得好的系统提示，决定了子代理是有用的还是偏离重点的。请具体说明子代理应该寻找什么，以及应该如何组织其输出。

让 Claude 自动使用您的子代理

如果您希望 Claude 在您没有明确要求的情况下将任务委派给该子代理，请在描述字段中包含"proactively"（主动地）一词。例如：

yaml

description: Proactively suggest running this agent after major code changes...

您还可以在描述中添加示例对话，以帮助 Claude 理解应该使用该子代理的具体场景。您的示例越具体，Claude 就越能准确判断何时该委派任务。

测试您的子代理

创建子代理后，通过进行一些代码更改并要求 Claude 审查这些更改来测试它。如果在您的会话开始时 agents 文件夹还不存在，请先重启 Claude Code 以加载新的子代理。

一个打开了 FastAPI 项目的代码编辑器，侧边面板中的 Claude Code 被要求使用 code-reviewer 子代理来审查最近的更改

如果子代理在您期望使用它时没有被使用，请返回检查描述内容。添加更具体的示例和触发场景有助于 Claude 理解何时应将工作委派给您的子代理。