如何在 Claude Code 里创建你的第一个 Subagent

如果你发现自己总是在让 Claude Code 重复做同一类专业任务，那就该用 subagent 了。Subagent 的作用，就是给 Claude 一个可复用的“专长角色”：它有自己的提示词、自己的工具权限，以及独立的上下文窗口。

这篇文章只讲最短路径，帮你做出第一个真正有用的 subagent。

Subagent 是什么

按照 Anthropic 官方文档的定义，subagent 是 Claude Code 可以委派给它处理特定任务的专用 AI 助手。每个 subagent：

• 有明确职责
• 使用独立上下文窗口
• 可以配置自己的工具权限
• 通过一个带 YAML frontmatter 的 Markdown 文件定义

这意味着，当你不想让 Claude 每次都从“通才模式”开始，而是希望它像审查员、调试员、迁移检查员那样稳定工作时，subagent 就非常合适。

什么时候值得建一个

当下面三件事同时成立时，就值得建：

• 这个任务会反复出现
• 这个任务适合用固定 checklist 处理
• 你希望主对话保持干净，不被细分任务冲乱

最适合作为第一批 subagent 的类型：

• 代码审查员
• 测试失败排查员
• 数据迁移检查员
• 安全审查员
• 文档更新员

最快的方法：直接用 /agents

最简单的入口是 Claude Code 内置界面：

/agents

然后：

1. 选择 “Create New subagent”
2. 取一个简短的小写名字
3. 写清楚它在什么情况下应该被调用
4. 选择它需要的工具
5. 保存

对第一只 subagent 来说，这是最省事的方式，因为 Claude Code 会把工具列表直接展示给你，能少踩很多格式坑。

也可以直接写文件：.claude/agents

如果你希望 subagent 能进版本控制，直接在下面目录里建文件：

.claude/agents/

Anthropic 官方文档里提到两种作用域：

• 项目级：.claude/agents/
• 用户级：~/.claude/agents/

如果同名，项目级优先。

一个够用的示例

创建 .claude/agents/code-reviewer.md：

---
name: code-reviewer
description: Review code changes for correctness, regression risk, and obvious security problems when asked to review a diff, module, or pull request.
tools: Read, Grep, Glob, Bash
---

You are a focused code review subagent.

Priorities:
- Find bugs before style issues
- Call out regression risk clearly
- Prefer concrete evidence from files or diffs
- Keep feedback short and specific

When reviewing changes:
1. Understand the intent of the change
2. Check for logic mistakes and missing edge cases
3. Check for unsafe assumptions and security issues
4. Flag missing tests when coverage looks weak
5. Return findings in priority order

这已经足够实用了。第一版不需要写成一篇大论文。

怎么调用它

你有两种调用方式。

让 Claude 自动选择

如果 description 写得够清楚，Claude Code 会自动判断是否应该委派给这个 subagent。

比如：

review my recent auth changes for regression risk
run all tests and investigate the failures

显式点名调用

你也可以直接说：

use the code-reviewer subagent to inspect the auth module
use the code-reviewer subagent on my current git diff

工具权限：先收紧，再放开

Anthropic 官方建议只给 subagent 它真正需要的工具。

一个实用原则：

• 读多写少的 subagent，优先给 Read、Grep、Glob
• 真的需要执行命令时再加 Bash
• 只有你明确想让它继承全部工具时，才省略 tools

第一只 subagent 最好偏“只读”，不要一开始就给太大权限。

常见错误

1. description 写得太虚

不好的写法：

• “helps with code”

更好的写法：

• “reviews schema migrations for rollback risk and missing indexes”

description 直接决定 Claude 能不能在合适的时候自动想到它。

2. 工具给太多

如果每个 subagent 都有满权限，那 subagent 最重要的两个价值就没了：安全边界和职责清晰。

3. 提示词写太长

第一版 prompt 应该像 checklist，不应该像宣言书。如果一只 subagent 需要六屏解释，往往说明任务范围还太大。

4. 把一次性任务也做成 subagent

如果只用一次，普通 prompt 就够了。Subagent 只有在任务会重复时才真正值回票价。

最适合的第一步

如果你想低风险试一次，最推荐这样做：

1. 先建一个 code-reviewer
2. 让它尽量只读
3. 先跑在你当前 diff 上
4. 连续用两三次后，再微调 description

通常 10 分钟内就能做出一只真正有价值的 subagent。

快速检查清单

• 从 /agents 开始
• 先只定义一个明确职责
• 把 description 写具体
• 工具权限尽量小
• prompt 保持短
• 拿真实任务测试
• 用过几次后再迭代

官方参考

• Subagents
• Common workflows