首页 › tutorials › 自定义Subagent三步成军

自定义 Subagent 三步成军：把 Claude Code 训成你的专属专家团队

概述

本教程面向已经会用 Claude Code 基础交互、想让 AI 真正"分工协作"的开发者。你将学会在 .claude/agents/ 下用一份 Markdown 文件定义一个"专家 Agent"——它拥有独立的上下文窗口、受限的工具集、专属的模型与记忆，能在主会话里被自动委派或显式召唤。学完后你能为仓库搭建一支各司其职的 Agent 团队，让主对话始终保持干净专注。

前置条件

已安装 Claude Code（本教程以 v2.1.x 为基准，文中特性标注了具体最低版本）
一个 Git 仓库作为演练场（用于演示 worktree 隔离与项目级 Agent）
了解 YAML frontmatter 基本语法
终端能正常运行 claude 命令

一、Subagent 到底解决了什么问题

先厘清一个常见误解：很多人把 Subagent 等同于"再开一个 Claude 窗口"。其实它的核心价值是上下文隔离与能力收敛。

当你在主会话里让 Claude"跑一遍测试套件并分析失败原因"，成百上千行日志会直接灌进主上下文，把后续的对话质量拖垮。Subagent 的做法是：把这类"高噪音、低复用"的任务甩给一个独立的工作者，它在自己干净的上下文里把活干完，只把摘要交回主会话。

更进一步，你可以为这个工作者设定： - 只能读、不能写（tools 白名单） - 用更便宜的模型（model: haiku） - 记住跨会话的项目经验（memory） - 套用一个专家人格（Markdown 正文即系统提示）

Claude Code 自带三个内置 Subagent，理解它们就理解了自定义的模板：

内置 Agent	模型	工具	用途
`Explore`	Haiku	只读	快速搜索/理解代码库，跳过 CLAUDE.md 与 git 状态，省时省钱
`Plan`	继承主会话	只读	计划模式下做代码库调研
`general-purpose`	继承主会话	全部工具	既要探索又要改动的复杂多步任务

关键细节：Explore 和 Plan 是仅有的两个会跳过 CLAUDE.md 和 git 状态的 Agent，目的是保持调研轻量。你自定义的 Agent 默认都会加载 CLAUDE.md 全层记忆——这是后面调优的要点。

二、第一份 Subagent：从手写到首次触发

2.1 选对作用域（Scope）

Subagent 是带 YAML frontmatter 的 Markdown 文件，放哪儿决定了它能被谁看到。优先级从高到低：

位置	作用域	优先级
托管设置（managed settings）	全组织	1（最高）
`--agents` CLI 参数	仅本次会话	2
`.claude/agents/`	当前项目	3
`~/.claude/agents/`	你所有项目	4
插件的 `agents/` 目录	插件启用处	5（最低）

实战建议：项目专属 Agent 放 .claude/agents/ 并提交到 Git，团队共享；跨项目通用的私人 Agent 放 ~/.claude/agents/。同名时高优先级覆盖低优先级；同一作用域内出现重名，Claude Code 会静默保留一个、丢弃另一个且不告警——所以务必保证 name 全树唯一。

2.2 手写第一个文件

在仓库根目录创建 .claude/agents/bug-hunter.md：

---
name: bug-hunter
description: 只读的代码缺陷与安全隐患猎人。在写完或改动代码后立即使用（use proactively）。聚焦可读性、重复逻辑、错误处理、密钥泄露与输入校验。
tools: Read, Grep, Glob, Bash
model: inherit
---

你是一位资深代码审查者，确保高质量与安全。被调用时：

1. 运行 `git diff` 查看最近改动
2. 聚焦被修改的文件，立即开始审查
3. 按优先级给出反馈：致命问题（必须修）、警告（应当修）、建议（可改进）
4. 每条结论附上具体位置与最小修复示例

你只能读不能改。不要给出"已修复"之类的承诺。

只有 name 和 description 是必填项。tools 不写则继承主会话全部工具；这里显式收窄到四个只读工具，天然禁止写文件。

2.3 一个关键陷阱：改了磁盘文件不生效

Subagent 在会话启动时加载。如果你直接在磁盘上新建或修改了 .md 文件，必须重启会话才会被加载。只有通过 /agents 交互界面创建或编辑的，才会即时生效、无需重启。

2.4 三种触发方式（从弱到强）

flowchart LR
    A[你的任务] --> B{触发方式}
    B -->|自然语言| C[Claude 自行决定是否委派]
    B -->|@提及| D[强制指定该 Agent 跑一次]
    B -->|--agent 会话级| E[整场会话都用它的人格]
    C --> F[bug-hunter 独立上下文工作]
    D --> F
    E --> F
    F --> G[仅把摘要交回主会话]

自然语言：在描述里点出 Agent 名字即可，无特殊语法：

用 bug-hunter 审一下 auth 模块的最近改动

@提及：输入 @ 从自动补全里挑出 bug-hunter (agent)，或手敲 @agent-bug-hunter。这保证指定的 Agent 一定跑，而非交给 Claude 自行判断。

会话级：用 --agent 启动，整场会话的主线程直接换上该 Agent 的人格、工具限制与模型：

claude --agent bug-hunter

此时它的系统提示完全替换默认的 Claude Code 系统提示（和 --system-prompt 同理），但 CLAUDE.md 与项目记忆照常加载。想把某个 Agent 设为项目默认，写入 .claude/settings.json：

{ "agent": "bug-hunter" }

CLI 参数优先于该设置。

预期结果：触发后，主会话出现一个 Agent 面板，bug-hunter 在独立上下文里跑 git diff、读文件、分析，结束后只把按优先级整理的清单返回主对话——主上下文里看不到它读取的几千行代码。

三、配置项全景：把专家调到恰到好处

3.1 frontmatter 字段速查

字段	必填	作用
`name`	是	唯一标识，小写+连字符；Hooks 里以 `agent_type` 收到此值
`description`	是	告诉 Claude 何时委派——写清楚触发场景
`tools`	否	工具白名单；省略则继承全部
`disallowedTools`	否	黑名单，先于 `tools` 生效
`model`	否	`sonnet`/`opus`/`haiku`/`fable`/完整 ID/`inherit`，默认 `inherit`
`permissionMode`	否	`default`/`acceptEdits`/`auto`/`dontAsk`/`bypassPermissions`/`plan`
`maxTurns`	否	最大轮次上限，防失控
`skills`	否	启动时预注入完整 Skill 内容到上下文
`mcpServers`	否	给该 Agent 专属的 MCP 服务器
`hooks`	否	仅在该 Agent 活跃时触发的生命周期钩子
`memory`	否	持久记忆：`user`/`project`/`local`
`effort`	否	`low`/`medium`/`high`/`xhigh`/`max`
`isolation`	否	`worktree`——在临时 git worktree 里跑
`background`	否	`true` 则总是后台运行
`color`	否	列表里的显示颜色
`initialPrompt`	否	作为主会话 Agent 时自动提交的首轮

3.2 模型路由：把便宜留给杂活，把贵留给难题

模型解析优先级（从高到低）：

环境变量 CLAUDE_CODE_SUBAGENT_MODEL
单次调用传入的 model 参数
Agent 文件里的 model 字段
主会话的模型

典型搭配：搜索/探索类 Agent 用 haiku 求快求省；深度安全审计、架构推理用 opus；写测试、补文档这类中等任务用 sonnet。

3.3 工具收窄的两种姿势

白名单（只给这几个）：

tools: Read, Grep, Glob, Bash

黑名单（继承全部，只摘掉写操作）：

disallowedTools: Write, Edit

两者同设时，先扣黑名单、再用白名单从剩余池里筛。MCP 工具支持通配：mcp__github 移除整个 github 服务的工具，mcp__* 移除所有 MCP 工具。

注意几个永远不可用的工具，即便写进 tools 也没用：AskUserQuestion、EnterPlanMode、ScheduleWakeup、WaitForMcpServers，以及非 plan 模式下的 ExitPlanMode——因为它们依赖主会话的交互态。

3.4 常见问题与对策

Q：Agent 改完代码后我才发现它跑偏了，怎么挽回？ 设 isolation: worktree，让它在临时 worktree（默认从默认分支拉）里改，主工作区不受污染；不改文件还会自动清理。

Q：Agent 总被委派，但我希望它只在特定场景出现。 问题出在 description 太宽泛。改成带明确触发词与示例的描述（参考下文实战案例的写法），并去掉 use proactively。

Q：怎么彻底关掉某个内置 Agent？ 在 settings 里禁用："permissions": { "deny": ["Agent(Explore)"] }，或命令行 claude --disallowedTools "Agent(Explore)"。要禁用全部内置、只留自定义，设 CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1。

四、实战案例：为仓库组建「PR 质量三人组」

下面搭一支三个 Agent 的流水线：bug-hunter（只读查缺陷）→ security-sentinel（深度安全审计）→ test-scaffolder（补测试骨架）。三者都放进 .claude/agents/ 并提交 Git。

4.1 1 号：bug-hunter（只读、继承模型）

即上文 2.2 的文件，此处略。

4.2 2 号：security-sentinel（opus、带项目级记忆）

.claude/agents/security-sentinel.md：

---
name: security-sentinel
description: 深度安全审计专家。当任务涉及认证、加密、权限校验、外部输入处理，或怀疑存在注入/越权/密钥泄露时使用。优先用 opus 做推理密集型分析。
tools: Read, Grep, Glob, Bash
model: opus
memory: project
color: red
---

你是安全审计专家。被调用时：

1. 先查阅你的 agent memory（`.claude/agent-memory/` 下），核对历史踩过的坑
2. 审计输入校验、鉴权链路、密钥硬编码、SQL/命令注入、反序列化
3. 给出风险等级、可利用路径、最小修复方案
4. 审计结束把新发现的模式与高危位置写入 memory，沉淀为项目知识

绝不臆测 API 细节——拿不准就明确标注"需验证"。

memory: project 会在 .claude/agent-memory/security-sentinel/ 下建持久目录，自动启用 Read/Write/Edit 并注入 MEMORY.md 前 200 行（或 25KB）。随用随记，团队通过 Git 共享审计经验。

4.3 3 号：test-scaffolder（sonnet、可写、加 PostToolUse 钩子）

.claude/agents/test-scaffolder.md：

---
name: test-scaffolder
description: 测试骨架生成器。为指定函数/模块生成可运行的单元测试骨架，遵循仓库现有测试风格。
tools: Read, Grep, Glob, Edit, Write, Bash
model: sonnet
hooks:
  PostToolUse:
    - matcher: "Edit|Write"
      hooks:
        - type: command
          command: "./scripts/run-linter.sh"
---

你专注写测试。被调用时：

1. 找到目标函数及其现有测试，复刻命名与断言风格
2. 覆盖正常路径、边界值、错误分支
3. 生成后运行 `npm test`（或等价命令）确认骨架可跑通
4. 失败就修到通过为止，只动测试文件

frontmatter 内的 hooks 只在该 Agent 活跃时触发；这里在每次写文件后自动跑 linter。注意：插件来源的 Agent 会忽略 hooks、mcpServers、permissionMode 三项——需要它们就放进 .claude/agents/ 而非插件。

4.4 串联成一条流水线

主会话里一句话编排：

先用 bug-hunter 找出 auth 改动里的缺陷，再用 security-sentinel 做深度安全审计，
最后用 test-scaffolder 为新加的鉴权函数补测试骨架

每个 Agent 干完把摘要交回主会话，主会话再把相关上下文递给下一个。主上下文里只剩三段精炼结论，而不是三个 Agent 各自读取的成千上万行代码。

4.5 用 CLI JSON 做一次性临时 Agent

不想落盘、只想临时跑一次（比如 CI 脚本里），用 --agents 传 JSON：

claude --agents '{
  "log-triage": {
    "description": "日志分诊专家，从测试输出里提炼失败原因。",
    "prompt": "你是日志分诊专家。从给定的日志中提取失败的用例、错误类型、可疑堆栈，按优先级输出清单。",
    "tools": ["Read", "Grep", "Bash"],
    "model": "haiku"
  }
}'

--agents 支持的全部字段与文件版一致（description/prompt/tools/disallowedTools/model/permissionMode/mcpServers/hooks/maxTurns/skills/initialPrompt/memory/effort/background/isolation/color），其中 prompt 等价于文件版的 Markdown 正文。

五、进阶：记忆、嵌套、Fork 与后台

5.1 给 Agent 装上持久记忆

memory 三档：

作用域	位置	何时用
`project`	`.claude/agent-memory/<name>/`	默认推荐，可随 Git 团队共享
`user`	`~/.claude/agent-memory/<name>/`	跨项目通用经验
`local`	`.claude/agent-memory-local/<name>/`	项目专属但不入版本库

记忆要主动维护——在正文里写明"完成任务后把学到的写入 memory"。也可以在主对话里点名提示它："审查这个 PR 前先翻翻你 memory 里记过的模式。"

5.2 嵌套 Subagent（v2.1.172+）

一个 Subagent 可以再生子 Subagent。比如审查者发现 5 个隐患，可以为每个隐患各派一个验证者并行复核，中间产物全不进主会话，只有顶层摘要回流。深度上限固定为 5 层（深度 5 的 Agent 不再获得 Agent 工具，不可再嵌套）；不想让它生崽就从 tools 拿掉 Agent 或加入 disallowedTools。

5.3 Fork：复用主上下文的分支（v2.1.117+）

普通 Subagent 从零起步，Fork 则继承当前整段对话——系统提示、工具、模型、历史全和主会话一致，因此首轮可复用主会话的 prompt cache，比新开一个更省。适合"在当前基础上分头试两种方案"。CLAUDE_CODE_FORK_SUBAGENT=1 开启，开 /fork 起草解析器的单测 即可派生一个后台分支。Fork 不能再生 Fork。

5.4 前台 vs 后台

前台 Subagent 阻塞主对话，权限提示会透传给你；后台 Subagent 并发跑，用会话已授的权限，遇提示则自动拒绝。想让任务后台化：直接说"在后台跑这个"，或对运行中的任务按 Ctrl+B。CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 可彻底关闭后台能力。

六、整体工作流架构

flowchart TB
    subgraph 主会话["主会话（保持干净）"]
      U[你的指令]
    end

    U --> D{委派决策}
    D -->|自动/自然语言| A1
    D -->|@提及/必跑| A2
    D -->|--agent 整场| A3

    subgraph Agents["独立上下文 Agent 团队"]
      A1[bug-hunter<br/>只读·继承]
      A2[security-sentinel<br/>opus·memory:project]
      A3[test-scaffolder<br/>sonnet·可写·PostToolUse钩子]
    end

    A2 -.沉淀经验.-> MEM[(agent-memory)]
    A1 --> R1[缺陷清单]
    A2 --> R2[风险报告]
    A3 --> R3[测试骨架]
    R1 & R2 & R3 -->|仅摘要回流| U

七、Subagent vs Skill vs CLAUDE.md：别用错

工具	跑在哪	何时选
CLAUDE.md	主会话，启动常驻	短小、恒真的项目规约（如"提交前跑 lint"）
Skill	主会话内，按需注入	可复用的富工作流（常带参考文件/脚本）
Subagent	独立上下文窗口	高噪音任务、需工具/权限收窄、需专属模型

一句话决策：任务会产出大量日志/搜索结果且你之后不再引用 → Subagent；想每次都让 Claude 自动套用某套规范 → CLAUDE.md 或 Skill。

训练营适用性评估

适合类型：企业研发效能训练营、DevOps 自动化训练营、AI 编程进阶营。学员需先掌握 Claude Code 基础交互与 CLAUDE.md 配置
教学时长：建议 3 课时。第 1 课时讲透"上下文隔离"动机与三大内置 Agent；第 2 课时手搓三人组并跑通触发链路；第 3 课时进阶记忆、Fork、嵌套与 CI 临时 Agent
可验收产出：每个学员/小组为自己的真实仓库提交一组 .claude/agents/*.md，并在 PR 流程里演示"主会话一句话、三人组自动接力、主上下文保持干净"的完整闭环

参考来源

Create custom subagents — Claude Code Docs — 官方权威文档，覆盖 frontmatter 全字段、作用域优先级、内置 Agent、记忆、Fork、嵌套等全部特性
Claude Code Customization Guide (2026): CLAUDE.md vs Skills vs Subagents — alexop.dev — 用同一问题对比四种定制方式，给出清晰决策矩阵
Build a Claude Code Custom Subagent: Step-by-Step Guide — Digital Applied — 从 .claude/agents/ Markdown 到首次触发的可复制实战示例
Claude Code Subagents: A 2026 Practical Guide — Tembo — 委派、隔离、摘要回流机制与并行研究的工程实践

[!tip] 51学通信知识星球 星主：爱卫生（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。 星球定位：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。 当前规模：5200 篇主题 / 990 个回答，198 元/年。 加入福利：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。 AI 加持：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。

51学通信知识星球海报-扫码加入