Claude Code 自定义 Subagent 怎么写

2026-06-17

Subagent 是 Claude Code 里一个带独立上下文窗口、专门干一类活的”子代理”。 你给它写一份说明书（它是谁、什么时候叫它、能用哪些工具），主对话遇到对口的任务就把活儿派给它，干完只把结论带回来，过程中的一堆中间信息不会污染你的主上下文。

这篇带你搞懂 claude code subagent 写法：文件放哪、frontmatter 几个字段各是什么意思、系统提示怎么写才好用，以及什么场景值得专门开一个 subagent。还没装好工具的，先看 Claude Code 教程把基础跑通；想了解 Claude Code 的整体定位也可以先扫一眼。

为什么要用 subagent

一句话：省主上下文、给专门活儿配专门人。

主对话的上下文窗口是有限的。当你让 Claude 去”翻 20 个文件找出所有调用某函数的地方”，这个搜索过程会塞进几千行无关内容，把你真正在乎的对话挤掉。Subagent 解决的就是这个——它在自己的窗口里翻完，只把”找到这几处”的结论交回来。

值得专门开 subagent 的典型场景：

隔离脏活：大范围代码搜索、日志排查、跑一堆测试——过程冗长，结论简短。
专业分工：代码审查、写测试、安全检查，各配一份角色化的系统提示，比通用对话更专注。
并行处理：几个互不依赖的任务可以同时派给多个 subagent 一起跑，比串行快。
复用规范：把团队的审查清单、命名约定写进 subagent 的提示里，谁用都一致。

Subagent 放在哪、长什么样

Subagent 就是一个 Markdown 文件，放在两个位置之一：

位置	路径	作用范围
项目级	`.claude/agents/`	只对当前项目生效，可提交进 git 团队共享
用户级	`~/.claude/agents/`	对你所有项目生效

同名时项目级优先。文件名（去掉 .md）就是这个 subagent 的标识。

文件结构是「frontmatter + 系统提示正文」，和写一篇带元信息的文档一样：

---
name: code-reviewer
description: 代码审查专家。写完一段功能、提交前调用它做审查
tools: Read, Grep, Glob
model: sonnet
---

你是一名严格的资深代码审查员。收到任务后：

1. 用 Grep / Glob 定位改动相关的文件并通读
2. 重点检查：边界条件、错误处理、命名、重复逻辑、明显的安全问题
3. 按「严重 / 建议 / 可选」三档输出问题清单，每条给出文件位置和修改建议
4. 不要改代码，只给评审意见

发现没问题时也明确说"未发现明显问题"，不要含糊。

具体字段名、可选值和最新写法以 Claude Code 官方文档为准，本文给的是稳定的核心结构。

四个核心字段怎么配

description——最关键的字段

description 决定 Claude 什么时候会自动叫这个 subagent。主模型读它来判断”当前任务该不该派给你”。

写法要点：用任务和触发时机来写，别只写身份。

❌ 太模糊：一个测试助手
✅ 够具体：编写和补全单元测试。当用户要求加测试、或新增了函数还没覆盖测试时调用

想让它更倾向被自动选中，可以在描述里加上 主动使用、务必使用 这类措辞。

tools——给它能用的工具

tools 是逗号分隔的工具白名单。不写这个字段，subagent 默认继承主对话的全部工具（包括 MCP 工具）。

要不要收紧？看活儿：

审查、检索类：只给 Read, Grep, Glob 这种只读工具，从机制上保证它不会乱改代码——比口头叮嘱”别改”可靠得多。
执行类（跑测试、装依赖）：才需要放开 Bash、Edit 等。

最小权限原则：能只读就别给写，能不给 Bash 就不给。

model——给它配多大的脑子

model 指定这个 subagent 用哪档模型。简单机械的活（如格式化搜索结果）用小模型省钱提速，复杂推理（如架构审查）用强模型。不写则一般跟随主对话的模型。具体可选的模型档位以官方文档为准。

name 与正文系统提示

name 是标识，建议用 kebab-case（test-writer、security-auditor），和文件名对应。

正文就是这个 subagent 的系统提示，决定它干活的质量。写好它的关键：

第一句给身份和专业边界（“你是一名……，只负责……”）。
给出步骤：收到任务先做什么、再做什么，让它有章法。
规定输出格式：要清单就说清单，要分级就定档位——结论结构化，主对话才好接。
划红线：明确”不要做什么”（如审查员不改代码）。

怎么调用 subagent

两种方式：

自动委派：你正常对话，Claude 根据各 subagent 的 description 判断要不要派活。这是 description 写得好不好的回报时刻。
显式点名：直接说”用 code-reviewer 审查刚才的改动”，强制指定。

想看当前有哪些 subagent、或交互式新建，用内置的 /agents 命令。它和你自己写的斜杠命令是两套东西——后者看 Claude Code 斜杠命令怎么写（规划中）。

怎么验证它在正常工作

写完一个 subagent，按这几步确认：

能被发现：运行 /agents，看新写的有没有出现在列表里。没出现先查文件路径和 frontmatter 格式。
能被点名：显式说”用 xxx 做……”，看它是否接管任务。
能被自动选中：描述一个对口任务（别点名），看 Claude 会不会主动委派——不会就回去把 description 写得更贴近真实触发场景。
结论干净：确认它带回来的是结论，而不是把一堆中间过程倒进主对话。

常见坑与排查

现象	原因	解法
`/agents` 里看不到	文件没放对目录 / frontmatter YAML 格式错	确认在 `.claude/agents/`，检查冒号是半角、缩进正确
从不被自动调用	`description` 太笼统，主模型判断不出何时用	改写成「具体任务 + 触发时机」，必要时加”主动使用”
它擅自改了代码	`tools` 没限制，继承了写权限	显式只给 `Read, Grep, Glob` 等只读工具
跑得慢又费钱	简单活配了强模型	把 `model` 降到小档位
主上下文还是被撑爆	把活儿写进了主提示而非派给 subagent	确认任务是「委派给 subagent」而非主对话自己干

常见问题

Q：subagent 和斜杠命令有什么区别？ 斜杠命令是你手动触发的提示词模板，本质是往当前对话塞一段预设指令；subagent 是有独立上下文的代理，能被自动委派、并行运行。前者管”少打字”，后者管”隔离上下文 + 专业分工”。

Q：项目里写的 subagent 怎么给团队共享？ 放进 .claude/agents/ 并提交到 git 即可，克隆仓库的人自动拥有同一套 subagent。放 ~/.claude/agents/ 的只对你自己生效。

Q：一个任务会同时用上多个 subagent 吗？ 会。互不依赖的子任务，Claude 可以并行派给多个 subagent 同时跑，再汇总结果——这正是 subagent 在大型重构、多文件排查里提速的原因。

Q：必须写 tools 字段吗？ 不必须。不写就继承主对话的全部工具。但审查、检索这类只读场景强烈建议显式收紧，用最小权限挡住误改风险。

Q：subagent 看得到我主对话的历史吗？ 看不到完整历史。它在独立上下文里工作，主对话把任务”打包”交给它，它只拿到这次任务需要的信息，干完回传结论——这正是它省主上下文的机制所在。

👉 看看我们的 AI 编程实战体系课，或逛 AI 编程教程大全把基本功打扎实。