Claude学院

Claude Code 子代理（Subagent）怎么用？实战教程

Claude Code 的子代理（Subagent）是拥有独立上下文窗口、独立系统提示词和独立工具权限的专用 AI 助手。你可以为「代码审查」「写测试」「排查 bug」各建一个子代理，主代理在遇到对应任务时把活儿派给它们，每个子代理在自己的会话里干完再把结果汇报回来，从而避免主对话被无关上下文塞满。

子代理到底解决什么问题

普通会话里所有任务共享同一个上下文，跑几轮代码审查就把窗口占掉一大半。子代理的核心价值有三点：

  • 上下文隔离：子代理在自己的窗口里工作，调试时翻几十个文件也不会污染主对话。
  • 专用提示词：每个子代理有定制的系统提示词，比如「你是严格的安全审查员，只看注入和越权」，行为更聚焦。
  • 工具与模型可控：可以单独限制某个子代理只能读文件不能执行命令，也能给简单任务指定更便宜的模型。

第一步：用 /agents 创建子代理

启动 Claude Code 后，在交互界面输入斜杠命令：

/agents

会进入子代理管理面板，选择 Create New Agent，依次决定：

  1. 作用域：项目级（存到 .claude/agents/）还是用户级（存到 ~/.claude/agents/）。项目级跟着仓库走、可提交到 Git 团队共享；用户级对你所有项目生效。
  2. 名称与描述：建议让 Claude 帮你起草，再手动微调。
  3. 工具权限：勾选这个子代理能用哪些工具，不勾则默认继承主代理的全部工具。
  4. 模型：为该子代理指定模型，留空则跟随主会话。

如果你还没装好 Claude Code，先看 Claude Code 怎么安装？Windows 完整安装教程（2026） 或 Claude Code Mac 安装教程：从零配置到首次运行。其他斜杠命令可参考 Claude Code 常用命令大全（附使用场景）。

第二步：看懂并手写配置文件

子代理本质是一个带 YAML frontmatter 的 Markdown 文件。下面是一个项目级代码审查子代理 .claude/agents/code-reviewer.md 的完整内容：

---
name: code-reviewer
description: 代码审查专家。在编写或修改代码后主动调用，检查质量、安全与可维护性。
tools: Read, Grep, Glob, Bash
model: sonnet
---

你是一名资深代码审查工程师。被调用时，请按以下流程工作：

1. 先用 git diff 查看最近改动，聚焦被修改的文件。
2. 逐项检查：命名是否清晰、有无重复代码、错误处理是否完整、
   有无硬编码密钥、输入是否做了校验、有无明显性能问题。
3. 按「严重 / 警告 / 建议」三档输出问题，每条给出文件名、
   行号和具体修复方案。
4. 不要泛泛而谈，只报告你确实在代码里看到的问题。

frontmatter 各字段说明：

字段是否必填说明
name必填子代理唯一标识，用小写字母和连字符。
description必填用自然语言描述「何时该用它」。主代理靠这句话决定要不要自动委派，写得越具体越容易被正确触发，可加「主动使用 / proactively」等措辞。
tools选填逗号分隔的工具白名单。省略则继承主代理全部工具（含已连接的 MCP 工具）。
model选填填 opus、sonnet、haiku 或具体模型 ID，也可填 inherit 跟随主会话。

第三步：触发子代理的两种方式

自动委派：当你的请求与某个子代理的 description 匹配时，主代理会自动把任务交过去。比如你说「帮我审查刚才写的支付模块」，上面的 code-reviewer 就会被唤起。想提高命中率，就把 description 写清楚触发场景。

显式调用：在对话里直接点名，控制最确定：

请用 code-reviewer 子代理审查 src/payment.ts

多个子代理还能并行运行。例如你要同时跑安全审查和性能审查，主代理可以一次性派发两个子代理并发执行，再汇总结果，比串行快很多。注意每个子代理都是全新的空白上下文，它看不到主对话的历史，所以任务描述要自带必要信息。

第四步：按任务选模型，控成本

2026 年 Claude 主力模型为 Claude Opus 4.8、Claude Sonnet 4.6、Claude Haiku 4.5。子代理可以单独指定，按难度分配能明显省钱：

  • haiku（Haiku 4.5）：跑测试、批量改格式、整理 changelog 这类机械任务。
  • sonnet（Sonnet 4.6）：日常代码审查、写单测、文档生成，速度与质量平衡。
  • opus（Opus 4.8）：架构设计、复杂跨文件调试、棘手并发问题，要最强推理时用。

具体怎么权衡可看 Claude 模型怎么选？Opus / Sonnet / Haiku 选型指南，省 Token 思路见 Claude API 怎么省钱？5 个降低 Token 成本的方法。各模型计费具体以 Anthropic 官网为准。

实战建议

  • 单一职责：一个子代理只干一件事，不要造「全能助手」，否则 description 难写、委派不准。
  • 最小工具集：审查类子代理只给 Read / Grep / Glob，别给写文件和执行命令的权限，更安全。
  • 系统提示词写流程：在正文里写清「分几步、输出什么格式」，效果远好于一句话定义。
  • 配合 CLAUDE.md：把团队规范沉淀进 Claude Code CLAUDE.md 配置文件怎么写？完整模板，子代理也会读取，行为更一致。
  • 结合 Hooks 自动化：想让子代理在特定时机自动跑，可搭配 Claude Code Hooks 怎么配置？自动化工作流实战。

常见问题

子代理和自定义斜杠命令有什么区别？

斜杠命令是把一段提示词模板插入当前会话，仍然共享主上下文；子代理则是开一个独立上下文窗口、带专属系统提示词和工具权限的「子会话」。需要隔离上下文、并行处理或限制权限时用子代理；只是想复用一段提示词就用斜杠命令，详见 Claude Code 自定义斜杠命令教程（附实用示例）。

为什么我的子代理没有被自动调用？

九成是 description 写得太笼统，主代理判断不出该不该委派。把它改成明确的触发条件，例如「在修改数据库迁移文件后主动调用，校验 schema 兼容性」。实在不行就显式点名调用。更多排查思路见 Claude Code 报错不工作？常见问题排查清单。

子代理能调用 MCP 服务器提供的工具吗？

可以。如果 frontmatter 省略 tools 字段，子代理会继承主代理的全部工具，包括已连接的 MCP 工具；若显式写了 tools，就把需要的 MCP 工具名也加进白名单。MCP 配置参考 Claude Code 配置 MCP 服务器完整步骤。

← Claude Code