本文根据 Claude Code 官方《Create custom subagents》整理，资料核对于 2026-11-05。配图为本站整理的示意图，不是界面截图。测试员和调试员的提示词是本站自己拟的示例。本站（bigolab.com）不是 Anthropic 官方网站。
适用于谁
- 已经看过 /guides/claude-code-subagents，知道子代理是什么，但不知道具体怎么写的人；
- 想让「跑测试、查报错」这类输出很啰嗦的工作留在独立上下文里，不污染主对话的人；
- 想给子代理加上硬性限制（比如只能读数据库）的人。
结论先说
- 子代理就是一个带前置字段的 Markdown 文件，放在
.claude/agents/（当前项目）或~/.claude/agents/（你所有项目）。只有name和description是必填。 - description 决定会不会被自动调用：官方说 Claude 按它来判断是否委派，加上「use proactively」这类措辞能促进自动调用。
- 权限靠 tools 收窄：只读的角色只给
Read、Grep、Glob；官方写明省略tools就继承所有可用工具。 - 想拦截具体命令，用 hook 而不是 tools：官方明确说
disallowedTools: Bash(git push *)这种带参数的写法会把整个 Bash 去掉，要拦具体命令需要permissions.deny规则或 PreToolUse hook。 - 子代理用的是同一份额度：官方写明子代理请求计入与主对话相同的用量限制，所以别建太多、别让它们跑太久。
图：本站根据 Claude Code 官方《Create custom subagents》 整理的示意图
代码审查员的写法已经在 /guides/claude-code-subagents 里给过，本文不重复，只补它没有的角色。
一、测试员：test-runner
适用场景：跑完整测试输出几百行，你只想知道哪几个失败、为什么。让子代理去跑，只把摘要带回主对话，这正是官方说子代理能「把冗长输出留在主对话之外」的用法。
.claude/agents/test-runner.md：
markdown
---
name: test-runner
description: 运行测试并汇报结果。修改代码后或用户要求跑测试时主动使用（use proactively）。
tools: Read, Grep, Glob, Bash
model: sonnet
maxTurns: 15
---
你是测试执行员。被调用时：
1. 先用 Glob 和 Grep 找出与改动相关的测试文件
2. 运行相关测试（优先单个文件，其次全量），命令见项目的 CLAUDE.md
3. 只汇报：通过数、失败数；每个失败用例的名字、断言信息、最可能的原因
4. 不要修改任何文件，不要自己修复
输出格式：先给一行总结，再列失败项。几点说明：
tools里没有Edit和Write，所以它只能跑命令和读文件，改不了代码，这个「不要修改」就有了硬保证；maxTurns: 15是官方字段，限制它最多走多少个回合，到上限时输出会被标记为部分结果，可以继续；model: sonnet用别名固定模型。官方给出的解析顺序是：调用时传入的别名、frontmatter 的model、环境变量CLAUDE_CODE_SUBAGENT_MODEL、最后才是主对话的模型。
二、调试员：debugger
调试员要能改代码，所以不写 tools，让它继承全部工具：
markdown
---
name: debugger
description: 排查报错和测试失败的专家。遇到异常、堆栈或失败的测试时主动使用。
---
你是调试专家。被调用时：
1. 先复现问题：读报错信息和堆栈，找到出错位置
2. 提出最多三个可能的原因，逐个用代码或日志验证
3. 找到根因后做最小改动修复，再重新运行相关测试确认
4. 汇报：根因是什么、改了哪里、如何验证官方文档里有一个最简的 debugger 示例用于 --agents 参数，只写了说明和一句提示词；上面这份更详细的版本是本站拟的。什么时候用它：问题需要「读—猜—改—验」反复多轮，主对话的上下文不想被中间过程占满。如果只是想让它给建议不改代码，就改成只读版本，见下一节。
三、只读调研员
官方的 safe-researcher 示例原样如下：
yaml
---
name: safe-researcher
description: Research agent with restricted capabilities
tools: Read, Grep, Glob, Bash
---想「继承全部工具但禁止写文件」，官方给的另一种写法是用黑名单：
yaml
---
name: no-writes
description: Inherits the available tools except file writes
disallowedTools: Write, Edit
---两种写法的区别：白名单 tools 只给你列的；黑名单 disallowedTools 是先从继承的全部工具里去掉，如果同一个工具在两处都出现，会被去掉。MCP 工具也一样，官方写法是 disallowedTools: mcp__github 去掉某个 MCP 服务器的全部工具。
四、只读数据库员：用 hook 拦截写操作
只放行 SELECT，是官方《子代理》页给出的完整示例。子代理只给 Bash，再挂一个 PreToolUse hook：
yaml
---
name: db-reader
description: Execute read-only database queries
tools: Bash
hooks:
PreToolUse:
- matcher: "Bash"
hooks:
- type: command
command: "./scripts/validate-readonly-query.sh"
---校验脚本（需要用 chmod +x 设为可执行，官方说明 macOS 和 Linux 上必须如此）：
bash
#!/bin/bash
# ./scripts/validate-readonly-query.sh
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
# Block SQL write operations (case-insensitive)
if echo "$COMMAND" | grep -iE '\b(INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE)\b' > /dev/null; then
echo "Blocked: Only SELECT queries are allowed" >&2
exit 2
fi
exit 0关键点：脚本以退出码 2 结束并把原因写到 stderr，就会阻止这次工具调用；退出码 0 放行。frontmatter 里的 hook 只在这个子代理运行期间生效；对于放在项目里的子代理文件，官方还说明需要先接受工作区信任对话框，hook 才会运行。hook 的基础见 /guides/claude-code-hooks。
五、怎么调用它们
图：本站根据 Claude Code 官方《Create custom subagents》 整理的示意图
官方列了三种方式，由弱到强：
- 自然语言点名：例如「用 test-runner 子代理跑一下失败的测试」，Claude 通常会委派；
- @ 提及：输入
@选子代理，例如@"code-reviewer (agent)" 看一下认证相关的改动。你的整条消息仍然交给 Claude，由它来写给子代理的任务提示； - 整个会话换成它：
claude --agent code-reviewer，主线程会采用该子代理的工具限制和模型；在.claude/settings.json里写"agent": "code-reviewer"可设为项目默认，命令行参数优先于设置。
现在的 /agents 命令只提醒你让 Claude 创建或直接编辑目录，交互向导只在 v2.1.197 及更早版本里有。
如果你想让测试员和调试员联动，不必自己写调度逻辑：官方说明子代理默认可以再启动子代理，最多往下三层，可用环境变量 CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH 调整，设为 1 则禁用嵌套。
常见问题
Q：子代理没有被自动调用？
先看 description 是否写清了触发场景；再用「用 xxx 子代理……」明确点名试一次。名字以 name 字段为准，不是文件名。
Q：子代理 vs 技能 vs hook 怎么选？
需要独立上下文、隔离冗长输出用子代理；固定流程用技能；硬性拦截用 hook，对比见 /guides/skill-vs-mcp-vs-subagent-vs-hook。
Q：会不会很费额度？
会。每个子代理都有自己的上下文窗口和调用，并计入同一份用量。需要更多额度可以了解 Claude Code 订阅方案；同时给每个子代理设 maxTurns 和便宜的 model。
参考资料
- Claude Code 官方：Create custom subagents — https://code.claude.com/docs/en/sub-agents
0 条评论
还没有评论，来抢沙发～