Claude Code Subagent：用专门助手升级你的开发工作流

在前面的几篇文章里，我们已经从整体上了解了 Claude Code 的能力，也分别聊过 Plugins、Skill 等扩展机制。今天这篇，专门来讲一个很多人「听过名字，但没系统用过」的功能：Subagent（子代理）。

如果把 Claude Code 比作你的「主力 AI 结对编程伙伴」，那 Subagent 更像是你手下的一群专门助手：有人擅长代码审查、有人专门跑测试、有人只负责查资料、有人帮你做架构分析。你只要分派任务，然后坐等这些助手汇报结果。

这篇文章会从以下几个维度来拆解 Subagent：

• 什么是 Subagent，它和主对话有什么区别？
• 内置子代理都做什么事？
• 如何创建属于自己的 Subagent？
• 怎么给 Subagent 限制权限、选择模型？
• 实战：给自己配一套好用的 Subagent 组合

一、Subagent 是什么？

先用一句话概括：

Subagent = 带独立上下文 + 自定义系统提示 + 独立工具权限的专门 AI 助手。

几个关键特性：

• 独立上下文：每个 Subagent 在自己的窗口里思考，不会把中间过程撑爆你的主对话。
• 单一职责：你可以给它非常具体的角色设定，只做一类事情。
• 工具可控：可以只给它只读工具，也可以让它拥有完整权限。
• 可复用：用户级 Subagent 一次配置，在所有项目中通用。
• 可组合：多个 Subagent 可以像流水线一样串联起来，完成复杂任务。

和直接在主对话里「啥都让 Claude 干」相比，Subagent 更像是你把一部分工作流程「模块化」了，交给专门的角色长期负责。

二、内置子代理：先用好系统自带的

Claude Code 默认已经内置了几类常用 Subagent，不用你额外配置，就能直接受益。

1. Explore：只读探索专家

• 模型：Haiku（速度快，成本低）
• 工具：只读工具（Read、Grep、Glob 等）
• 适合场景：
  • 初次接手一个大项目，想先熟悉结构
  • 搜索某个功能相关的所有代码路径
  • 做技术调研、对比不同实现

特点是：不会改动任何文件，你可以放心让它大胆乱翻代码库。

2. Plan：规划阶段研究员

• 模型：继承主对话
• 工具：只读工具
• 使用场景：你启用 /plan 模式时，Claude 会自动把「代码库调研」这部分工作委托给 Plan Subagent。

这个子代理的作用是：在真正动手改代码前，帮你把上下文摸清楚，输出一份可执行的实现方案。

3. General-purpose：全能执行助手

• 模型：继承主对话
• 工具：所有可用工具
• 适合场景：
  • 需要一边查代码一边修改的复杂任务
  • 涉及多步操作的重构、迁移
  • 需要读写多个文件、运行命令的工作

一般来说，当任务本身比较「长流程」且需要同时探索 + 修改时，Claude 会倾向于用这个子代理来执行。

4. 其他系统子代理

除了上面这些，你在文档里还能看到一些更「专项」的内置子代理，比如：

• Bash：在独立上下文中运行终端命令
• Claude Code Guide：专门回答 Claude Code 相关问题
• statusline-setup：帮你配置状态栏

这些通常不需要你直接点名调用，Claude 会在合适的时候自动使用。

三、什么时候该用 Subagent，而不是主对话？

很多人第一次接触 Subagent 时都会问：我直接在主对话里让 Claude 做事不就好了？为什么还要多这一层？

可以从几个典型场景来判断：

场景	推荐方式
需要频繁互动、一步步讨论	主对话
长期、多阶段共享上下文（规划→实现→测试）	主对话
很小的改动、一次性问答	主对话
任务会产生大量输出，只想要摘要	Subagent
想严格限制工具/权限（只读、禁用 Bash 等）	Subagent
工作是「包工头模式」——丢任务给助手，等结果	Subagent

可以这么理解：

• 主对话 适合「你在现场盯着，一起干活」；
• Subagent 适合「你当经理，派个专人去搞，搞完汇报」。

四、Subagent 的存放位置与作用范围

Subagent 本质上是一个带 YAML frontmatter 的 Markdown 文件。它放在哪里，决定了它的作用范围：

位置	范围	典型用途
~/.claude/agents/	用户级	你所有项目通用的个人助手
.claude/agents/	项目级	仅当前项目使用，可提交到版本库
插件的 agents/ 目录	插件级	随插件一起分发的通用助手
--agents CLI 标志	当前会话	用完即走的临时代理

一般建议：

• 个人固定工作流 → 放在 ~/.claude/agents/
• 项目特定规范 / 领域知识 → 放在项目的 .claude/agents/
• 要分享给团队甚至社区 → 打包成插件里的 agents/

五、用 /agents 可视化管理 Subagent

虽然 Subagent 文件可以手动写，但更推荐你先习惯一个命令：

/agents

进入这个界面后，你可以：

• 查看所有可用的子代理（内置 + 用户级 + 项目级 + 插件）
• 使用向导创建新的 Subagent
• 编辑已有子代理的配置（工具、模型、权限模式等）
• 删除不再需要的子代理
• 查看在重名时，当前会话实际会用哪一个

对大多数用户来说，用 /agents 创建，是上手 Subagent 的最佳路径。

六、创建你的第一个 Subagent

下面用一个非常典型的场景来做演示：给自己配一个「代码改进顾问」。

这类子代理的需求通常是：

• 能扫描项目中的指定文件/目录
• 帮你找出可读性、性能、工程规范方面的问题
• 给出更好的实现建议，最好能附上改进版的代码

1. 打开 Subagent 管理界面

在 Claude Code 中运行：

/agents

选择「Create new agent」，然后选择「User-level」，让它在所有项目里可用。

2. 让 Claude 帮你生成配置

选择「Generate with Claude」，在提示里输入类似描述：

A code improvement agent that scans files and suggests improvements
for readability, performance, and best practices. It should explain
each issue, show the current code, and provide an improved version.

Claude 会基于这段描述生成：

• 一段系统提示（描述这个子代理的角色与工作方式）
• 一份 YAML frontmatter 配置（name、description、tools、model 等）

你可以按 e 打开编辑器，按需要微调。

3. 选择工具与模型

对于这个示例子代理，我比较推荐的配置：

• 工具：
  • 如果只做「代码建议」，不允许直接改文件 → 只勾选 Read、Grep、Glob 之类的只读工具。
  • 如果希望它可以自动改代码 → 保留 Write/Edit 相关工具。
• 模型：
  • 需要高质量代码审查 → 选 sonnet 或 opus
  • 只做轻量扫描提示 → 选 haiku

如果你不确定，就先用默认的「inherit」，和主对话保持一致也没问题。

4. 保存并测试

保存后，这个子代理就立即可用了，不需要重启。

你可以在会话里直接说：

Use the code-improver agent to suggest improvements in this project

Claude 会自动委托给你新建的 Subagent，扫描代码并给出建议。

七、手写一个 Subagent 文件长什么样？

当你熟悉了 /agents 界面之后，其实就可以直接手写 Subagent 文件了。一个最小可用的 Subagent 大概长这样：

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

上半部分的 YAML frontmatter 是「配置」，下半部分的正文则是这个子代理的「系统提示」。Subagent 启动时只会看到这一段提示，而不会继承你在主对话里的全部系统设置。

常用 frontmatter 字段说明

常见可配置字段包括：

• name：子代理的唯一名称，推荐用小写 + 连字符
• description：一句话说明「什么时候应该用它」
• tools：允许使用的工具白名单
• disallowedTools：在继承父级工具集合的基础上，再禁用一些
• model：使用的模型（sonnet / opus / haiku / inherit）
• permissionMode：权限模式（后文展开）
• skills：预加载到子代理上下文中的技能列表
• hooks：仅在该子代理生命周期内生效的 hooks
• memory：是否启用持久内存，以及范围（user / project / local）

通过这些字段，你可以精细控制每个 Subagent 的能力边界。

八、控制 Subagent 的能力与权限

对工程团队来说，使用 Subagent 最大的一个好处就是：可以更严格地控制 AI 能做什么、不能做什么。

1. 工具白名单 / 黑名单

如果你想做一个「只读研究员」：

---
name: safe-researcher
description: Research agent with restricted capabilities
tools: Read, Grep, Glob, Bash
disallowedTools: Write, Edit
---

这样它即便再聪明，也无法直接改代码，只能给你分析结果和建议。

2. 权限模式（permissionMode）

permissionMode 控制子代理在需要权限时的行为，大致有几种常用模式：

• default：遵循主对话的默认行为，遇到敏感操作时会向你确认。
• acceptEdits：自动接受文件编辑，非常适合高频小改动。
• dontAsk：自动拒绝所有需要额外授权的操作，适合做「纯顾问」。
• bypassPermissions：跳过权限检查，所有操作直接执行（慎用）。
• plan：Plan 模式，仅做只读探索。

一般建议：

• 团队公共环境、生产仓库 → 避免使用 bypassPermissions
• 需要自动跑大量重构的个人项目 → 可以考虑给特定子代理开启 acceptEdits

3. 给 Subagent 预加载 Skills

你可以通过 skills 字段，把某些 Skill 的内容在启动时直接塞进 Subagent 的上下文，相当于给它附加一套「领域知识手册」：

---
name: api-developer
description: Implement API endpoints following team conventions
skills:
  - api-conventions
  - error-handling-patterns
---

Implement API endpoints. Follow the conventions and patterns from the preloaded skills.

和主对话不同的是：Subagent 不会自动继承父对话里的 Skills，你必须手动列出来。好处是，每个子代理可以有自己专门的知识配置。

4. 启用持久内存：让 Subagent 越用越聪明

memory 字段可以让 Subagent 在多个会话之间积累经验，比如：

---
name: code-reviewer
description: Reviews code for quality and best practices
memory: user
---

You are a code reviewer. As you review code, update your agent memory with
patterns, conventions, and recurring issues you discover.

根据不同的记忆范围，数据会存到不同目录：

• user：~/.claude/agent-memory/<name-of-agent>/，适合跨项目通用的经验。
• project：.claude/agent-memory/<name-of-agent>/，适合项目内共享，能进版本库。
• local：.claude/agent-memory-local/<name-of-agent>/，项目特定但不提交。

启用后，Subagent 会按照文档里的规则自动维护自己的 MEMORY.md，你也可以在系统提示里专门提醒它「重要结论记得写进内存」。

九、用 Hooks 精细化管控 Subagent 行为

更进阶一点，你可以通过 Hooks 在 Subagent 生命周期的关键节点插入自己的逻辑。

1. 在 frontmatter 中定义 Hooks

比如下面这个子代理：

---
name: db-reader
description: Execute read-only database queries
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly-query.sh"
---

它会在每次运行 Bash 前，执行你提供的脚本，脚本可以解析传入的 JSON，检查是否包含写 SQL，一旦检测到 INSERT/UPDATE/DELETE... 之类的语句就直接拦截。

再比如一个自动跑 Lint 的代码审查子代理：

---
name: code-reviewer
description: Review code changes with automatic linting
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-command.sh $TOOL_INPUT"
  PostToolUse:
    - matcher: "Edit|Write"
      hooks:
        - type: command
          command: "./scripts/run-linter.sh"
---

• 在执行 Bash 前，先校验命令是否合法；
• 在完成文件编辑后，自动帮你跑一遍 Linter。

2. 项目级 Hooks：感知 Subagent 启停

你也可以在项目的 settings.json 里，监听 Subagent 的启动 / 停止事件，例如：

• SubagentStart：当特定类型的 Subagent 被启动时触发
• SubagentStop：当任何 Subagent 完成时触发

这样可以实现类似：

• 某个数据库 Subagent 启动时自动导出环境变量
• 任何 Subagent 结束时自动做一次资源清理/日志记录

十、几种实用的 Subagent 组合思路

最后给几个我自己比较常用、也比较适合落地的组合思路，供你参考：

1. 「代码质量流水线」

• code-reviewer：只读审查，给出问题列表和建议。
• optimizer：在 acceptEdits 模式下，执行可控范围内的自动优化。
• test-runner：负责运行测试，只返回失败用例和关键信息。

典型工作流：

1. 先用 code-reviewer 找问题。
2. 对其中部分问题，让 optimizer 自动修复。
3. 最后用 test-runner 跑测试，确认没有回归。

2. 「安全敏感项目」

• 所有改动都在主对话 + 人工确认下进行。
• Subagent 全部配置为只读模式（禁用 Write/Edit）。
• 通过 Hooks 和 Bash 校验脚本，限制可能有风险的命令。

这样可以让 AI 帮你做大量研究与分析工作，但真正的写操作仍由你掌控。

3. 「文档驱动开发助手」

结合 Skill 与 Subagent：

• 项目里维护一套 CLAUDE.md + Skills 作为知识库。
• 子代理通过 skills 预加载这些规范。
• 每次评审、生成文档，都由特定 Subagent 执行，并按团队约定的格式输出。

随着时间推移，这些 Subagent 会越来越贴合你团队自己的工程文化。

写在最后

从工程角度看，Subagent 的价值并不仅仅在于「更智能」，而是在于：

• 把 AI 能力结构化、模块化，变成一个个可复用的角色；
• 通过配置精细控制风险，让它在安全边界内高效工作；
• 配合 Skills、Plugins、Hooks、持久内存，构建出真正属于你团队的「AI 开发平台」。

如果你已经习惯了在主对话里让 Claude 帮你写代码、查问题，不妨从今天开始，尝试给自己配置一两个 Subagent——

• 一个专门帮你做代码审查；
• 一个专门跑测试并整理报告；
• 一个专门研究陌生项目结构；

当你真正把这些角色用顺手之后，会发现：Subagent 带来的不仅是效率提升，还有整个开发工作流的思维方式变化。