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 agentClaude 会自动识别 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 code2. 工具权限要最小化
给 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，是比每次用自然语言描述高效得多的做法。
相关推荐
AI-first 创业公司，为什么只需要一种编程语言？
技术架构越简单 = AI Coding 效率越高。从 Java 的"防人"设计到 TypeScript 全栈通吃，聊聊 AI 时代创业公司的编程语言选择。
cc-ping：一行命令 Ping 所有 Claude Code 配置
用多个 Claude Code API Key 或中继？cc-ping 帮你管理配置、一键切换，还能并行 Ping 所有节点比速度。
震惊！程序员用这个工具，4分钟干完95分钟的活！效率暴涨24倍
躺床上发3条消息，4分钟搞定3个项目。传统方式需要95分钟，这就是冷兵器和热兵器的差距。
CCBot - 研发提效 24 倍
通过 IM 机器人控制 Claude Code，3 个项目 4 分钟全部搞定。传统编程需要 95 分钟，效率提升 24 倍。
Claude Code /add-dir：被低估的 Monorepo 神器
Claude Code 默认只能看到当前目录。/add-dir 打破这个限制——分享我每天跨 5 个仓库使用的经验。
Claude Code 省 Token 小技巧：感叹号的妙用
一个简单却容易被忽略的技巧——用感叹号直接执行命令，省 token、提速度、更可控。
我做了个机器人，让团队在飞书里用 Claude Code
CCBot 让你的团队在飞书群聊里直接用 Claude Code——不需要终端、不需要 SSH。开源、自部署、五分钟搞定。
Claude Code /btw 命令详解：不打扰主线的快问快答
详细介绍 Claude Code 的 /btw 命令——它是什么、怎么用、什么时候该用，以及它和子代理、/compact 的区别。
Claude Code /compact：释放上下文，不丢进度
任务做到一半上下文满了？/compact 帮你压缩对话继续干活——和 /clear、/rewind 的区别一次讲清。
Claude Code /config：一文搞懂所有可调设置
用 Claude Code 却从没打开过 /config？这篇带你逐项拆解——从权限模式到自动压缩，从主题切换到通知配置，帮你打造最顺手的 AI 编程环境。
Claude Code /context：你的上下文都被什么吃了？
对话到一半 Claude Code 说上下文不够了？/context 用一张可视化网格告诉你：上下文被什么占了、占了多少、怎么优化。
Claude Code /diff：这次对话改了什么，一目了然
Claude Code 帮你改了一堆文件，但你不确定到底改了什么？/diff 用交互式界面展示所有改动——既有 git 视角的全量 diff，也有按对话轮次拆分的逐步 diff。
Claude Code /fast：同样的 Opus，两倍速——值不值？
/fast 不会降级模型，还是 Opus，只是更快。什么时候该开、什么时候该关，以及实际体验差异。
Claude Code 引用外部知识的最佳实践：GitHub MCP + Context7
用 GitHub MCP 和 Context7 MCP 两个工具组合，解决 Claude Code 知识过时导致的代码错误问题。
Claude Code /hooks：让 AI 按你的规矩办事
想在 Claude Code 执行命令前自动检查？想在任务完成后自动通知？/hooks 让你用脚本、AI 甚至 HTTP 请求，在关键节点插入自定义逻辑。
Claude Code /init：10 秒自动生成 CLAUDE.md
别再手写 CLAUDE.md 了。看看 /init 自动生成的效果、怎么自定义输出，以及一个让 Claude Code 效率翻倍的小技巧。
Claude Code MCP：让 AI 连接 GitHub、数据库等一切工具
MCP 把 Claude Code 从代码阅读器升级为全栈 Agent。哪些 MCP 服务器值得装、配置怎么写，实测分享。
Claude Code /memory 详解：让 AI 真正记住你的项目
详细介绍 Claude Code 的 /memory 命令和记忆系统——CLAUDE.md 手动指令、Auto Memory 自动记忆、模块化规则，让 Claude 跨会话记住项目规范和个人偏好。
Claude Code /model：Opus、Sonnet、Haiku 怎么选？
不是每个任务都需要 Opus。怎么切换模型、哪个场景用哪个、怎么省 token 又不掉质量。
Claude Code /permissions：谁能干什么，你说了算
每次 Claude Code 要跑命令都弹窗问你？嫌烦又不敢全放开？/permissions 帮你精细控制每个工具的权限——该放的放，该拦的拦。
Claude Code /plan 详解：先想清楚再动手
详细介绍 Claude Code 的 /plan 命令和 Plan Mode——只读规划模式，让 Claude 先分析代码、制定方案，确认后再动手，避免复杂任务翻车。
Claude Code + Playwright MCP：AI 终于能"看见"页面了
一个 Modal 溢出的 bug，Claude Code 反复修了 5 次都没搞定。直到接入 Playwright MCP 让它真正看到页面，一次定位，一次修复。
Claude Code /resume 命令详解：别让对话白聊
详细介绍 Claude Code 的 /resume 命令——恢复历史对话、管理会话、实用技巧，让你的每一轮对话都不浪费。
Claude Code /review：让 AI 帮你做 Code Review
提了 PR 没人看？想在合并前多一道把关？/review 让 Claude Code 像一个资深开发者一样审查你的代码——还有 /ultrareview 和 /security-review 两个进阶选择。
Claude Code Skills 详解：打造你的专属命令库
详细介绍 Claude Code 的 Skills 功能——创建自定义斜杠命令、复用提示词模板、共享团队最佳实践，让 AI 编程更高效更一致。
Claude Code /stats：看看 AI 到底帮你写了多少代码
好奇 Claude Code 到底写了多少行代码？/stats 给你完整数据——token、编辑次数、工具调用，教你怎么看。
Claude Code /status 命令详解：一眼看清会话全貌
详细介绍 Claude Code 的 /status 命令——它是什么、怎么用、能看到哪些信息，以及它在日常工作流中的实际价值。
Claude Code /tasks 命令详解：后台任务尽在掌控
详细介绍 Claude Code 的 /tasks 命令——查看后台任务、管理并行 Agent、掌控长时间运行的进程，让多任务开发井井有条。
Claude Code /usage 命令详解：你的额度还剩多少
详细介绍 Claude Code 的 /usage 命令——查看用量、了解限额、避免突然被限速，让你对自己的额度心中有数。
Claude Code /vim：在 AI 编程助手里用 Vim 键位
习惯了 Vim 的操作方式？/vim 让你在 Claude Code 的输入框里用 hjkl 移动、dd 删行、ciw 替换单词——不用改变肌肉记忆。
Claude Code 使用指南：从安装到实战，一篇就够（2026）
用了半年 Claude Code 的经验总结——5 分钟安装配置、最常用的命令、CLAUDE.md 编写技巧，以及没人告诉你的实战心得。
Claude 全家桶：从聊天到写代码到自动办公，一文讲清楚
一篇文章带你了解 Anthropic 的 Claude 全家桶——Claude.ai、Claude Code、Claude Cowork，以及 Opus、Sonnet、Haiku 三大模型家族。
Claude Code /doctor 详解：一键诊断你的开发环境
详细介绍 Claude Code 的 /doctor 命令——自动检测安装状态、API 连接、MCP 配置、上下文用量等问题，帮你快速定位和修复环境故障。
Claude Code /effort 详解：控制 AI 思考的深度
详细介绍 Claude Code 的 /effort 命令——调节 Claude 的推理努力程度，在速度和质量之间找到最佳平衡点，让每一次对话都恰到好处。
Claude Code /cost 详解：你的 AI 编程到底花了多少钱
详细介绍 Claude Code 的 /cost 命令——实时查看会话 API 成本，了解各模型定价和 Token 消耗明细，让每一分钱都花得明明白白。
Claude Code /export 详解：把 AI 对话带走
详细介绍 Claude Code 的 /export 命令——将对话导出为文件或复制到剪贴板，方便分享、存档和复盘，让每一次有价值的对话都不浪费。
Claude Code /rewind 详解：AI 改错了？一键回退
详细介绍 Claude Code 的 /rewind 命令——将代码和对话回退到任意历史节点，支持只回退代码、只回退对话、或两者同时回退，是你和 AI 协作时的后悔药。
Claude Code /plugin 详解：给你的 AI 编程助手装插件
详细介绍 Claude Code 的 /plugin 命令——管理插件的安装、启用、禁用和更新，通过插件扩展 Claude Code 的命令、技能、Agent 和 Hook，打造你专属的 AI 编程工具链。
Claude Code /theme 详解：给你的终端换个好看的皮肤
详细介绍 Claude Code 的 /theme 命令——6 种预设主题 + 自动模式，支持深色/浅色、色盲友好、ANSI 兼容，60+ 色值覆盖终端全部 UI 元素。
Claude Code /insights 详解：用 AI 分析你自己用 AI 的方式
详细介绍 Claude Code 的 /insights 命令——五阶段数据分析流水线、七大洞察章节、多维度会话统计，用 Claude Opus 生成专属 HTML 使用报告。
Claude Code /rename 详解：给你的会话取个有意义的名字
详细介绍 Claude Code 的 /rename 命令——手动命名、AI 自动生成（Haiku 模型）、启动参数命名、Plan 模式自动命名，以及双标题系统与 Bridge 同步机制。
Claude Code settings.json 详解（一）：配置文件在哪里、谁说了算
全面介绍 Claude Code 的配置文件体系——五个配置来源的路径、优先级规则、数组合并与单值覆盖的区别、企业管理设置的多种下发方式。
Claude Code settings.json 详解（二）：permissions 权限系统全解析
深入解析 Claude Code 的 permissions 配置——allow/deny/ask 三类规则、通配符语法、MCP 工具权限、defaultMode 各模式含义，以及 additionalDirectories 的作用。
Claude Code settings.json 详解（三）：hooks 钩子全解析
深入解析 Claude Code 的 hooks 配置——四种钩子类型、核心事件（PreToolUse/PostToolUse/Stop/Notification）、stdin/stdout 协议、exit code 语义，以及实用配置示例。
Claude Code settings.json 详解（四）：env、模型、认证与其他实用字段
全面介绍 Claude Code settings.json 中的 env 环境变量注入、模型配置、身份认证辅助、Git 提交署名、会话清理、语言与界面、思考深度、自动更新、记忆系统等实用字段。
Claude Code Agent Loop：拆解 AI 编程助手的心脏
Claude Code 是怎么一步步理解你的需求、调用工具、自我修复的？从源码角度拆解 Agent Loop 的核心架构——流式响应、并行工具执行、自动压缩、错误恢复，一次讲透。