你的 AI 员工团队
Mission 关联：前两课你学会了自动化（hooks）和复用（skills）。这一课将教你分工——让你的"AI 员工"各自有专长、独立工作，不再什么事都挤在主会话里做。
Subagent 是 Claude Code 的隔离工作器。每个 subagent 拥有独立的上下文窗口、可自定义的工具集、甚至不同的模型和权限。 你可以把它想象成"雇了一个专门做某件事的实习生"——你把任务派给他，他独立完成，只把结果汇报给你。
Claude Code 自带一些内置 subagent 类型，你也可以创建自定义的：
| Agent | 来源 | 用途 | 可自定义？ |
|---|---|---|---|
Explore |
内置 | 只读搜索，快速扫描代码库 | ❌ |
Plan |
内置 | 架构设计，规划实现方案 | ❌ |
General-purpose |
内置 | 全能型，默认 agent | ❌ |
| 自定义 Agent | agents/*.md |
你想要什么就是什么 | ✅ 全部 |
和 skill 一样，agent 也支持全局和项目两级：
| 位置 | 作用域 | 特点 |
|---|---|---|
~/.claude/agents/<name>.md |
全局 | 你个人的 AI 员工，跨项目可用 |
.claude/agents/<name>.md |
项目级 | 可提交到仓库，团队共享 |
每个 agent 是一个 .md 文件，YAML frontmatter 定义元数据，markdown 正文定义它的"角色设定"：
---
name: code-reviewer
description: "Review code changes for quality and security"
tools: Read, Edit, Grep, Bash
disallowedTools: Write, WebSearch
model: sonnet
permissionMode: acceptEdits
maxTurns: 20
skills:
- security-review
- code-style
mcpServers:
- database
memory: project
isolation: worktree
color: cyan
background: true
---
你是一个资深的代码审查专家，专注于正确性和安全性。
## 审查原则
1. 优先发现逻辑错误和安全隐患
2. 对每一条意见给出具体的代码示例
3. 用中文输出审查结果
4. 最后给出总体评分（1-10）和修改建议优先级
## 输出格式
- **问题**: [严重度: 高/中/低] 问题描述
- **位置**: 文件名:行号
- **建议**: 修改方案
| 字段 | 必填？ | 说明 | 示例 |
|---|---|---|---|
name |
✅ | Agent 名称，用于 @name 调用 |
code-reviewer |
description |
✅ | 描述何时使用（Claude 据此自动触发） | Review code changes... |
tools |
❌ | 可用的工具列表（逗号分隔） | Read, Edit, Grep |
disallowedTools |
❌ | 拒绝使用的工具 | Write |
model |
❌ | 模型覆盖（haiku / sonnet / opus） | haiku |
permissionMode |
❌ | 权限模式 | acceptEdits |
maxTurns |
❌ | 最大交互轮数 | 20 |
skills |
❌ | 此 agent 可用的 skill 列表 | [security-review, code-style] |
mcpServers |
❌ | 此 agent 可用的 MCP server | [database] |
memory |
❌ | 持久记忆作用域 | user | project | local |
isolation |
❌ | 工作树隔离 | worktree |
color |
❌ | 终端显示颜色 | cyan | green | yellow |
background |
❌ | 默认后台运行 | true |
控制 subagent 的权限行为：
| 值 | 含义 |
|---|---|
acceptEdits | 自动接受文件修改，无需逐条确认 |
acceptAll | 允许所有操作 |
| 不设置 | 每次操作都询问你（默认行为） |
让 subagent 跨会话记住信息：
| 值 | 作用域 | 适用场景 |
|---|---|---|
user | 你的所有项目 | 个人偏好、常用配置 |
project | 当前项目 | 项目特有知识 |
local | 仅当前会话 | <�>临时记忆，用完即弃
让 subagent 在独立的 Git 工作树中工作，实现真正的并行编辑不冲突。
适合：多个 subagent 同时修改不同文件的场景。完成后会自动提交 + push + 创建 PR。
Subagent 默认前台运行。设为 true 后将在后台默默工作，你可以在主会话继续做其他事。
可以给 subagent"注入"特定的技能和外部服务连接。比如一个数据查询 agent 可以自带 database MCP server 的权限。
description 判断当前任务适合哪个 agent，自动启动@agent-name 你的任务 手动调用docs-writer Agent场景：你希望有一个专门写文档的 agent——它只读代码、写 markdown，不修改源码。
步骤：
在 ~/.claude/agents/docs-writer.md：
---
name: docs-writer
description: "Write and update documentation"
tools: Read, Grep, Glob, Write, Edit
disallowedTools: Bash
model: haiku
memory: project
---
你是一个技术文档写手。根据代码生成或更新文档。
## 规则
1. 只读代码，不改代码
2. 用中文撰写，清晰简洁
3. 输出格式：Markdown
4. 包含使用示例
## 工作流程
1. 先阅读相关代码文件理解功能
2. 检查是否已有文档（有则更新，无则新建）
3. 生成文档，包含：概述、安装/引入方式、API/使用说明、示例代码在任意项目中，告诉 Claude：@docs-writer 给这个项目的 main 函数写文档
观察：它是否只读了代码、没改代码、写了文档？
文档撰写不费脑，用 model: haiku 就够了（更便宜更快）。
但如果是架构设计文档，可以改成 model: sonnet。
Subagent 内部还可以再启动 subagent（最多 5 层嵌套）。这让你能构建出复杂的协作结构：
你 (主会话)
└─ @project-audit (审计 agent)
├─ @security-check (安全检查 subagent)
├─ @perf-check (性能检查 subagent)
└─ @style-check (风格检查 subagent)
└─ @eslint-helper (ESLint 规则咨询 subagent) ← 嵌套的第三层| Skill | Subagent | |
|---|---|---|
| 上下文 | 共享主会话上下文（或 fork 隔离） | 完全独立的上下文窗口 |
| 工具 | 通过 allowedTools 限制 | 自定义工具集 + 可禁用工具 |
| 模型 | 可覆盖 | 可覆盖 |
| 记忆 | 无持久记忆 | 支持 user/project/local 持久记忆 |
| 并行 | 串行执行 | 可后台并行运行 |
| 隔离 | context: fork | worktree 物理隔离 |
| 最佳用途 | 复用工作流、快速脚本 | 独立复杂任务、长时间运行、并行处理 |
tools 只给需要的，disallowedTools 阻断危险的background: true 让 agent 默默干活不打断你有任何问题随时问！Subagent 是 Claude Code 进阶中最强大的功能之一，理解透彻了后面学 workflow 会非常轻松。
学完这课你就有自己的 AI 员工了——试试给不同任务创建不同的 agent，体验一下"当领导"的感觉 😎