Claude Code /agents 详解：自定义 AI 子代理，各司其职

为什么需要 /agents

用 Claude Code 做开发，你一定用过 Agent tool——Claude 会自动派出一个”子代理”帮你做搜索、读代码、执行子任务。

但你有没有想过：这些子代理到底是谁？它们能做什么？能不能自己定义一个？

举几个真实场景：

你想让 Claude 探索一个不熟悉的代码库，但不想让它一边看一边改文件
你想让 Claude 做架构规划，但不想让它跳过规划直接动手
你想创建一个”测试专家”，每次只跑测试、分析失败原因，不碰业务代码
你的团队有一套特定的代码审查规则，想让 Claude 按照这套规则来审

默认的通用子代理做不到这些。你需要的是：为不同任务创建不同角色的专属 Agent。

这就是 /agents 的价值。

/agents 是什么

/agents 是 Claude Code 的 Agent 管理命令。输入这个命令，你会看到当前所有可用的 Agent 列表，包括内置的和你自定义的。

在交互模式下输入：

/agents

会显示一个交互式菜单，列出所有 Agent，按来源分组（内置、项目级、个人级、插件），并展示每个 Agent 的描述、可用工具和模型配置。

内置 Agent

Claude Code 自带了几个内置 Agent，你不需要任何配置就能直接用：

general-purpose（通用型）

这是默认的子代理，当你不指定 subagent_type 时就会用它。

能做什么：几乎所有事——搜索代码、读写文件、执行命令、调用所有工具
工具权限：*（全部工具）
模型：默认 Sonnet（子代理默认用较快的模型以节省成本）
适用场景：通用任务、多步骤操作、不确定该用哪个 Agent 时

Explore（探索型）

专门用来快速了解代码库的只读 Agent。

能做什么：搜索文件、读代码、分析结构
不能做什么：不能编辑文件、不能写文件、不能派子代理
模型：Haiku（速度快、成本低）
特点：会跳过 CLAUDE.md 加载，启动更快，上下文更干净
适用场景：快速搜索关键字、理解文件结构、回答”这段代码在哪”之类的问题

Plan（规划型）

专门用来做架构规划的只读 Agent。

能做什么：读代码、分析架构、制定实施方案
不能做什么：不能编辑文件、不能写文件、不能派子代理
模型：继承父级模型（通常是 Opus）
特点：只读，但会深入分析，适合需要认真思考的任务
适用场景：设计实施方案、评估架构权衡、分析关键文件

这几个内置 Agent 对应了开发中最常见的模式：通用干活、快速查找、深入规划。

自定义 Agent

内置 Agent 满足不了你的需求？你可以创建自己的 Agent。

创建方式

自定义 Agent 就是一个 Markdown 文件，放在 .claude/agents/ 目录下：

# 项目级 Agent（所有协作者共享）
.claude/agents/my-agent.md

# 个人级 Agent（只有你自己能用）
~/.claude/agents/my-agent.md

文件结构很简单：YAML frontmatter + 系统提示词。

完整示例：测试专家

---
name: test-expert
description: Run tests, analyze failures, suggest fixes without touching business code
model: sonnet
tools: [Bash, Read, Glob, Grep]
disallowedTools: [Edit, Write]
---

You are a testing specialist. Your job is to:

1. Run the test suite using the project's test command
2. Analyze any test failures in detail
3. Read the relevant source code to understand the failure
4. Suggest specific fixes, but NEVER modify files yourself

Always report:

- Which tests failed and why
- The root cause (not just the symptom)
- A concrete fix suggestion with code snippets

保存为 .claude/agents/test-expert.md 后，Claude 就能通过 Agent tool 调用它了：

帮我跑一下测试，用 test-expert agent

Claude 会自动识别 subagent_type: "test-expert" 并使用你定义的规则。

配置项详解

frontmatter 里可以配置的字段：

字段	说明	示例
`name`	Agent 名称	`test-expert`
`description`	描述（决定 Claude 何时使用它）	`Run and analyze tests`
`model`	使用的模型	`opus`、`sonnet`、`haiku`、`inherit`
`tools`	允许使用的工具白名单	`[Bash, Read, Glob, Grep]`
`disallowedTools`	禁止使用的工具黑名单	`[Edit, Write, Agent]`
`maxTurns`	最大对话轮数	`200`
`memory`	持久记忆范围	`user`、`project`、`local`
`isolation`	隔离模式	`worktree`
`background`	是否默认后台运行	`true`
`permissionMode`	权限模式	`plan`、`acceptEdits`、`bubble`
`mcpServers`	需要的 MCP 服务器	`[slack]`

几个关键配置的解释：

model: inherit：继承父级对话使用的模型。如果你的主对话用的是 Opus，子代理也用 Opus。

isolation: worktree：在独立的 git worktree 中运行。Agent 的所有文件操作都在一个隔离副本中进行，不会影响你的工作目录。如果 Agent 没改任何文件，worktree 会自动清理；如果改了，会保留分支和路径供你审查。

permissionMode：控制 Agent 的权限行为。plan 表示只读，acceptEdits 表示自动接受编辑，bubble 表示权限请求冒泡给父级处理。

memory：让 Agent 拥有持久记忆。设为 project 后，Agent 会记住跨会话的项目上下文。

实用 Agent 示例

代码审查员

---
name: reviewer
description: Review code changes for quality, security, and best practices
model: opus
tools: [Bash, Read, Glob, Grep]
disallowedTools: [Edit, Write, Agent]
---

You are a senior code reviewer. Review the current diff and check for:

1. Logic errors and edge cases
2. Security vulnerabilities (OWASP Top 10)
3. Performance issues
4. Code style violations
5. Missing error handling

Be specific: cite file paths and line numbers. Rate severity as critical / warning / suggestion.

文档同步器

---
name: doc-sync
description: Update documentation to match code changes
model: sonnet
tools: [Read, Write, Edit, Glob, Grep]
disallowedTools: [Bash, Agent]
---

You are a documentation specialist. Your job is to:

1. Read the recent code changes (git diff)
2. Find all related documentation files
3. Update docs to reflect the code changes
4. Ensure README, API docs, and inline comments are in sync

Never run commands. Only read code and update docs.

隔离实验员

---
name: experiment
description: Try experimental changes in an isolated worktree
model: opus
isolation: worktree
background: true
---

You are an experimental agent. You work in an isolated git worktree,
so your changes won't affect the main working directory.

Try the approach described in the prompt. If it works, report the
worktree path and branch name so the user can review and merge.
If it fails, explain why and suggest alternatives.

Agent 的优先级

当同名 Agent 出现在多个来源时，Claude Code 按以下优先级选择（从高到低）：

个人级 — ~/.claude/agents/
项目级 — .claude/agents/
插件 — 通过插件加载的 Agent
内置 — Claude Code 自带的 Agent

这意味着你可以用同名文件”覆盖”内置 Agent 的行为。比如创建一个 ~/.claude/agents/general-purpose.md，就能自定义默认子代理的行为。

Agent 和 Skills 的区别

初看起来，Agent 和 Skills 很像——都是 Markdown 文件，都能自定义行为。但它们解决的是完全不同的问题：

	Agent	Skill
本质	独立的 AI 角色	提示词模板
运行方式	子进程，有自己的上下文	在当前对话中展开
工具权限	可限制（白名单/黑名单）	继承当前对话的权限
模型	可指定不同模型	使用当前对话的模型
隔离	支持 worktree 隔离	无隔离
适用场景	需要独立执行的子任务	需要复用的提示词

简单判断：如果你只是想复用一段提示词，用 Skill。如果你需要一个有独立权限和工具限制的 AI 角色来执行子任务，用 Agent。

后台 Agent

Agent 可以在后台运行，不阻塞你的主对话。

两种方式启用：

Agent 定义中设置：background: true
调用时指定：Claude 在 Agent tool 中设置 run_in_background: true

后台 Agent 启动后，你可以继续和 Claude 对话。Agent 完成后会自动通知你结果。配合 /tasks 命令可以查看所有后台 Agent 的运行状态。

使用技巧

1. description 要写好

Claude 决定用哪个 Agent，主要靠 description 字段。写得越精确，Claude 越能在正确的场景自动选用。

# 太模糊
description: Helper agent

# 精确描述
description: Run and analyze test failures, suggest fixes without modifying code

2. 工具权限要最小化

给 Agent 的工具权限应该是完成任务所需的最小集合。一个只读的探索 Agent 不需要 Write 和 Edit，一个文档 Agent 不需要 Bash。

3. 善用 worktree 隔离

对于实验性的修改，设置 isolation: worktree。这样即使 Agent 搞砸了，你的工作目录也不受影响。

4. 团队共享

把 Agent 定义放在 .claude/agents/ 下并提交到 Git，整个团队就能共享同一套 Agent 角色。这是统一团队 AI 使用方式的好办法。

写在最后

/agents 的核心思想是角色分工。

通用 Agent 什么都能做，但什么都不精。自定义 Agent 让你为不同任务创建专门的角色——有的只看不改，有的专注测试，有的在隔离环境里做实验。

就像一个团队里有前端、后端、QA、架构师，每个人有自己的职责和权限。Claude Code 的 Agent 系统让你用同样的思路管理 AI 助手。

把重复的角色定义写成 Agent，是比每次用自然语言描述高效得多的做法。