创建 Claude Code 子智能体：从 YAML 配置到触发条件设计

把重复任务交给 Claude Code 子智能体，关键不在于写一段更长的提示词，而在于把“什么时候调用、负责什么、能看到什么、最后返回什么”分别定义清楚。一个可维护的子智能体，通常由 YAML frontmatter、智能体文件位置、触发条件和系统提示词四部分组成。

先确定子智能体的职责边界

适合交给子智能体的任务，通常具有三个特点：重复出现、可以单独判断、完成后只需要返回结构化结果。比如检查一组文件的变更影响、整理代码审查意见、提取文档中的待办事项，都是相对独立的任务。

不适合直接交给子智能体的，是需要持续掌握整个项目背景、频繁改变总体方案，或者必须由主智能体统一决策的工作。子智能体拥有独立的上下文范围，隔离可以减少无关信息干扰，但也意味着它不会自动了解主任务中的所有背景。

本文使用一个抽象任务作为示例：创建一个“变更检查”子智能体。它的职责是读取主任务提供的相关内容，判断变更可能影响哪些部分，列出需要人工确认的问题，并返回简洁的检查结果。它不负责修改文件，也不负责替主智能体决定最终方案。

在动手写配置前，先用一句话回答下面的问题：

这个子智能体只解决哪一种可重复的问题？

如果这句话中同时出现了“分析、修改、发布、测试、总结”等多个动作，说明职责可能过宽，需要进一步拆分。

创建智能体文件与 YAML frontmatter

Claude Code 的自定义子智能体使用 Markdown 文件定义，项目级文件放在 .claude/agents/ 目录中。文件顶部是 YAML frontmatter，后面的 Markdown 正文会作为这个子智能体的系统提示词。

可以先创建如下文件：

.claude/agents/change-reviewer.md

文件内容示例：

---
name: change-reviewer
description: 当任务需要评估一组文件变更的影响、发现潜在风险或整理待确认事项时使用。适合进行独立检查，不负责直接修改文件，也不负责决定最终实施方案。
---

你是一个专门负责变更检查的子智能体。

你的任务是：
1. 阅读主任务提供的变更内容和相关背景。
2. 判断变更可能影响的功能、流程或相邻文件。
3. 区分已经确认的问题、合理推测和需要人工确认的事项。
4. 不直接修改文件，不替主智能体做最终决策。
5. 如果输入信息不足，明确指出缺少哪些内容，不要自行补全事实。

请按以下结构返回结果：

## 检查结论

用简短文字说明是否发现明显风险。

## 影响范围

列出受影响的文件、模块或流程；如果资料不足，请说明无法判断的部分。

## 风险与依据

说明每个风险的判断依据，避免只给出没有解释的结论。

## 待确认事项

列出需要主任务继续确认的问题。

## 建议动作

只给出与检查结果直接相关的下一步建议，不要扩展到无关任务。

这里有四个值得区分的部分。

name 负责标识

name 是子智能体的名称，建议使用简短、稳定、能够体现职责的英文标识，例如 change-reviewer。它主要用于识别这个文件代表的角色，不应该把复杂的触发逻辑全部塞进名称中。

description 负责说明何时使用

description 是触发设计的核心。它需要同时说明适用场景和不适用范围，而不是只写“检查代码”这种过于宽泛的描述。

好的描述应当回答：

• 什么类型的任务需要它？




• 它要解决的具体问题是什么？




• 哪些工作明确不属于它的职责？

例如，“当任务需要评估一组文件变更的影响时使用”比“帮助开发”更容易让主智能体判断是否应该调用它。资料中提到，描述信息会影响子智能体的调用，而子智能体正文中的系统提示词则决定它启动后如何工作。

Markdown 正文负责行为

frontmatter 后面的正文就是子智能体的系统提示词。它不应该重复介绍 Claude Code 的基础用法，而应直接规定角色、输入处理方式、禁止事项和输出格式。

如果某项要求只写在 description 中，子智能体启动后未必会严格按照该要求执行；如果某项要求只写在系统提示词中，主智能体又可能难以在调用前判断它是否适合当前任务。因此，触发范围写在 description，执行细节写在系统提示词，二者不要混为一谈。

设计触发条件，而不是堆关键词

子智能体的触发条件可以分为两种思路：明确调用和自动判断。

明确调用适合那些需要开发者主动控制的任务。例如，只有当你明确要求“对这组变更做独立检查”时，才让对应子智能体参与。它的优点是可控，适合涉及敏感文件、复杂上下文或较高决策成本的任务。

自动判断适合重复性较高、边界清晰的任务。主智能体可以根据子智能体的 description，判断当前请求是否符合其职责。此时，描述越具体，误触发和漏触发的可能性越低。

触发条件要包含任务和边界

可以按照下面的逻辑编写描述：

当出现什么任务 → 子智能体要做什么 → 哪些事情不做

以示例中的变更检查为例：

当任务需要评估文件变更的影响、发现潜在风险或整理待确认事项时使用；不负责直接修改文件，也不负责决定最终实施方案。

这段描述比单纯写“代码审查助手”更完整，因为它同时定义了触发场景和排除条件。

还要避免把触发条件写成无法判断的主观词，例如“遇到复杂问题时使用”“需要时调用”。“复杂”和“需要”没有明确标准，主智能体很难稳定判断。可以改为具体任务类型，例如“需要比较多个文件之间的变更影响时使用”。

用系统提示词隔离上下文

上下文隔离不是简单地少给一些内容，而是主动规定子智能体只处理完成当前任务所必需的信息。

在变更检查示例中，系统提示词可以通过以下方式保持边界：

第一，明确输入范围。子智能体只读取主任务提供的变更内容和相关背景，不要求它自行推测没有提供的业务规则。

第二，明确判断层级。它需要区分已确认事实、基于内容作出的推测，以及尚待确认的问题。这样可以避免把猜测写成确定结论。

第三，明确权限边界。示例中规定“不直接修改文件”，意味着它只负责分析和返回结果，修改动作仍由主智能体或开发者决定。

第四，明确上下文不足时的处理方式。与其让子智能体自行补全缺失信息，不如要求它列出缺少的文件、背景或判断依据。

这种隔离方式尤其适合审查、分析、归纳和检查类任务。它能让子智能体专注于一个侧任务，同时减少主任务中的其他信息对判断结果的干扰。

设计稳定的返回格式

子智能体的输出应当服务于主任务，而不是只追求“看起来完整”。一个实用的返回格式至少要让主智能体快速知道三件事：

• 是否发现需要关注的问题；




• 问题影响了哪些范围；




• 下一步需要确认或处理什么。

示例中的返回结构分为“检查结论”“影响范围”“风险与依据”“待确认事项”和“建议动作”。这样的顺序是从判断到依据，再到行动，便于主智能体继续处理。

返回格式不宜过度复杂。如果任务只需要一个判断结果，就不必强行要求多个章节；如果每个风险都需要解释依据，则不能只要求子智能体输出一串结论。格式的详细程度，应当与任务的判断成本匹配。

还可以在系统提示词中加入以下约束：

如果没有发现风险，请明确写出“未发现明显风险”，并说明检查依据。
如果无法判断，请写出缺少的信息，不要用肯定语气替代判断。
不要重复转述全部输入，只保留会影响决策的内容。

这些要求能够减少两类常见问题：没有问题时输出含糊结论，以及资料不足时凭空补全。

需要限制工具时再增加配置

资料显示，子智能体除了 name 和 description 外，还可以根据需要配置模型、工具访问权限等可选字段。是否增加这些配置，应当由任务的权限边界决定，而不是为了让文件看起来更专业而全部填写。

如果子智能体只负责阅读和分析，就应优先保持配置简单。只有在确实需要特定工具或权限时，才根据当前 Claude Code 文档支持的字段进行配置，并逐项验证效果。

不要在没有确认字段格式时自行添加复杂配置。一个无法解析的可选字段，可能比缺少该字段更难排查。初版先使用最小可行配置，确认触发和输出稳定后，再逐步增加限制，通常更容易维护。

用一个最小任务验证配置

创建文件后，不要一开始就拿最复杂的项目任务测试。先准备一个范围明确的输入，验证下面四件事：

1. 主任务能否根据 description 判断是否应该调用该子智能体。




2. 子智能体是否只处理变更检查，而没有越权修改或扩展任务。




3. 输入信息不足时，是否会明确指出缺口。




4. 返回结果是否符合约定结构，能否被主任务继续使用。

可以准备两组对照场景。

第一组是应该触发的场景：提供一组文件变更，并要求判断影响范围、风险和待确认事项。这与 change-reviewer 的职责直接匹配。

第二组是不应该触发的场景：要求直接修改文件，或者要求设计完整实施方案。前者超出了“只检查、不修改”的限制，后者也不属于该子智能体的核心职责。通过对照测试，可以发现 description 是否写得过宽。

如果测试结果中出现大量无关背景、结论没有依据，或者子智能体频繁替主任务做决定，优先修改系统提示词，而不是继续增加更多关键词。触发问题看 description，执行问题看系统提示词，这是排查时最重要的区分。

配置检查清单

发布或长期使用前，可以逐项检查：

• [ ] 文件是否放在 .claude/agents/ 目录中。




• [ ] 文件是否使用 Markdown 格式。




• [ ] YAML frontmatter 是否位于文件顶部，并且与正文分隔清楚。




• [ ] name 是否简短、稳定，能够体现职责。




• [ ] description 是否说明了适用场景。




• [ ] description 是否写出了明确的排除范围。




• [ ] 系统提示词是否说明了子智能体的唯一核心任务。




• [ ] 系统提示词是否规定了输入范围和上下文边界。




• [ ] 是否明确哪些事情不能做，例如不能修改文件或替主任务决策。




• [ ] 是否规定了信息不足时的处理方式。




• [ ] 返回格式是否能直接服务于主任务的下一步判断。




• [ ] 是否用一个应触发场景和一个不应触发场景做过验证。




• [ ] 可选的模型或工具配置是否确有必要，并符合当前文档支持的格式。

一个好的子智能体文件不一定很长，但必须让职责、触发条件、隔离边界和返回结果彼此对应。description 决定“什么时候找它”，系统提示词决定“找到它以后怎么做”，而稳定的返回格式决定“结果能否真正接回主任务”。只要这条链路清楚，后续再拆分其他重复任务时，就可以复用同样的设计方法。

如需核对 Claude Code 当前支持的字段和配置方式，可以参考官方自定义子智能体文档。