Claude Code 子智能体 Subagents 教程（2026）

用 Claude Code 时你可能遇到过这种情况：让它跑一遍测试、搜一大片代码库，几百行日志和文件内容瞬间把主对话刷满，而这些你根本不会再看第二遍，宝贵的上下文窗口就这么被占掉了。Claude Code 的「子智能体」（Subagents，也叫子代理）就是为解决这个问题而生——它是拥有独立上下文窗口、独立工具权限的专用小助手，主会话把一件脏活累活委托给它，它在自己的上下文里干完，只把一份摘要交回来。这篇 Claude Code 子智能体教程讲清它是什么、内置的有哪些、怎么用一个 Markdown 文件造一个自己的，以及怎么调用和与技能（Skills）的区别。

子智能体是什么，解决什么问题

一个子智能体，就是主会话可以把任务委托出去的一个「专门工人」：它有自己的上下文窗口、自己的系统提示词、被限定的工具集和独立权限。当 Claude 遇到和某个子智能体「描述」匹配的任务时，会自动把活派给它；子智能体独立干完，只把结果返回主对话。它带来的好处很实在：

• 保护上下文：把探索、跑测试这类会产生大量输出的活留在子智能体的上下文里，主对话只收一份摘要，不被刷屏。
• 施加约束：可以限定某个子智能体只能用只读工具（不许改文件），让它安全地专职做审查或调研。
• 跨项目复用：写成用户级子智能体，你机器上所有项目都能用同一个。
• 控制成本：把简单任务路由到更快更便宜的模型（比如 Haiku），省 token。

内置子智能体：Explore / Plan / general-purpose

Claude Code 自带几个内置子智能体，会在合适的时候自动调用，你通常不用手动管：

内置子智能体默认从主对话继承模型（Explore、Plan 还会跳过 CLAUDE.md 和 git 状态以保持又快又省）。除了这几个内置的，你还能自己造专用子智能体。

创建自定义子智能体：一个 Markdown 文件

自定义子智能体就是一个带 YAML frontmatter（文件头）的 Markdown 文件：头部几行 YAML 定义它的名字、描述、能用的工具和模型，正文就是它的系统提示词。放在哪个目录，决定了谁能用它：放进项目的 .claude/agents/ 只在当前项目可用（可提交进 Git 与团队共享），放进 ~/.claude/agents/ 则你机器上所有项目都能用。最省事的做法是直接让 Claude 帮你写——描述你想要的子智能体和存放位置，它会按正确格式生成文件。

# 项目级：只在当前项目可用，建议提交进 Git 与团队共享
.claude/agents/code-reviewer.md

# 用户级：你机器上所有项目都可用
~/.claude/agents/code-reviewer.md

下面是一个「代码审查员」子智能体的完整例子：只读工具（不许改代码），专职审查最近的改动并按优先级给反馈。

---
name: code-reviewer
description: 代码审查专家。写完或改完代码后主动审查质量、安全与可维护性。
tools: Read, Grep, Glob, Bash
model: inherit
---

你是一名资深代码审查员。被调用时：
1. 运行 git diff 查看最近的改动
2. 聚焦被修改的文件
3. 立即开始审查

审查清单：命名是否清晰、有无重复代码、错误处理是否到位、
是否泄露密钥/API Key、输入是否校验、测试覆盖是否足够。

按优先级给反馈：严重问题（必须改）/ 警告（应该改）/ 建议（可以更好），
并对每条给出具体的修复示例。

frontmatter 常用字段

怎么调用子智能体

有了子智能体后，从「自动」到「强制」有几种用法：

• 自动委托：什么都不用做，Claude 根据你的请求和子智能体的 description 自动派活。
• 自然语言点名：在提示里直接叫它，比如「用 code-reviewer 子智能体审查我最近的改动」，Claude 通常就会委托。
• @ 提及：输入 @ 从提示里选中某个子智能体，保证这一次就用它。
• 整个会话作为某子智能体运行：用 claude --agent <名字> 启动，主线程直接采用它的系统提示、工具限制和模型。

# 自然语言点名（在 Claude Code 会话里直接说）
# 用 code-reviewer 子智能体审查我最近的改动
# 让 test-runner 子智能体只跑测试并汇报失败项

# 让整个会话作为某个子智能体运行
claude --agent code-reviewer

子智能体 vs 技能（Skills）vs 主对话

三者容易混。简单说：子智能体是「隔离出去、只回摘要」的独立上下文；技能（Skills）是「注入到当前上下文里复用的提示/工作流」；主对话则适合需要频繁来回、共享上下文的活。

子智能体是把 Claude Code 从「一个助手」用成「一个小团队」的关键一步：把探索、审查、测试这些脏活分派出去，主对话专注在真正的决策上。但工具再强，最终能不能交付，还是看你会不会拆任务、审代码、把 AI 的产出稳定用进真实项目。想系统掌握用 Claude Code 等 AI 工具做出能交付产品的方法，欢迎来 IMAI 看看我们的体系化实战课程。