Claude Code 子 Agent 怎么配：agents 文件、工具与模型

在 Claude Code 里跑测试、翻日志、查一遍代码库，输出很快把主对话的上下文塞满。子 Agent（subagents）专接这种活：在自己的上下文窗口里干完，只把摘要交回来。官方文档写明，同一类活反复派、指令也一样时，就该把它写成自定义子 Agent。下面按 Claude Code 官方 subagents 文档（2026-10-29 北京时间查阅）整理文件写法、字段、调用方式和常见坑。

前置条件：一个能用的 Claude Code，加一个你反复在派的活

• 已安装并登录 Claude Code。文中一些行为标了最低版本，例如 claude plugin validate 检查 agents 目录要 v2.1.233 及以上。
• 先想好要拆出去的是哪类活。官方的判断标准：会产生大量你之后不再看的输出、要单独限制工具、能独立做完只交摘要的，适合子 Agent；需要来回改、多个阶段共享大量上下文、或者改一行就完事的，留在主对话。
• 子 Agent 自己发请求，算在你同一份用量额度里。并行开得多，额度也花得快。

先认识内置的三个：Explore、Plan、general-purpose

不写任何文件，Claude Code 也会自动派子 Agent：

你在用户或项目目录里放一个同名的 Explore，就会覆盖内置版本并用你写的 model，比如设成 haiku 让探索跑在便宜模型上。不想让 Claude 用某个内置类型，在设置里 permissions.deny 加 "Agent(Explore)" 即可。

第一步：建文件，选好作用域

子 Agent 是带 YAML frontmatter 的 Markdown 文件。放的位置决定谁能用，同名时优先级高的生效：

项目级的提交进 git，团队一起用、一起改。目录会递归扫描，可以按 agents/review/、agents/research/ 分子文件夹，但调用名只看 name 字段，和路径无关。

一个只读代码审查员，放进 .claude/agents/code-reviewer.md：

---
name: code-reviewer
description: Expert code reviewer. Use proactively after code changes.
tools: Read, Grep, Glob, Bash
model: sonnet
---

You are a senior code reviewer. Run git diff, focus on modified files,
and report issues as Critical / Warning / Suggestion with concrete fixes.

正文就是这个子 Agent 的系统提示。它拿不到 Claude Code 自己的系统提示，只有这段话加工作目录等环境信息，要交代的规矩都得写在这里。

只想临时试一下，不落盘，用 --agents 传 JSON：

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  }
}'

第二步：把 description 写成路由规则

Claude 靠 description 决定什么时候派活。想让它主动派，官方建议在描述里写「use proactively」这类说法。描述会常驻上下文：除内置的之外，所有子 Agent 的描述加起来超过 15,000 token，启动时会报警告。细节挪到正文系统提示里，正文只在这个子 Agent 运行时才加载。

description 管「什么时候找它」，正文管「找来以后怎么干」。混在一起写，每个会话都得多背一段。

第三步：收紧工具、选模型、定权限

• tools / disallowedTools：tools 是白名单，不写就继承子 Agent 能用的全部工具；disallowedTools 是黑名单。两个都写时先删黑名单，再在剩下的里按白名单取。整台 MCP 服务器可以写 mcp__github__*（给）或 mcp__github（拿走）。
• model：可写 sonnet、opus、haiku、完整模型 ID 或 inherit。生效顺序：Claude 单次调用时传的 model → frontmatter 的 model → 环境变量 CLAUDE_CODE_SUBAGENT_MODEL → 主对话模型。要所有子 Agent 强制同一个模型，再加 CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1。
• permissionMode：可选 default、acceptEdits、auto、dontAsk、bypassPermissions、plan。主对话处在 bypassPermissions、acceptEdits 或 auto 模式时，子 Agent 跟随主对话，你写的值不起作用。
• maxTurns：限制轮数，到上限后输出标成 partial，Claude 可以续跑。

工具级做不到的细粒度控制交给 hooks：在 frontmatter 里挂 PreToolUse，脚本以退出码 2 拦下命令。官方示例是只放行 SELECT 的数据库只读子 Agent。

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

第四步：给子 Agent 预装 Skills、MCP 和记忆

• skills：列出的 Skill 启动时把全文注入子 Agent 上下文，最多取前 32 个名字。设了 disable-model-invocation: true 的 Skill 不能预装。
• mcpServers：可以引用已配置的服务器名，也可以内联定义。内联的只在子 Agent 启动时连接，结束就断开；想让某个 MCP 的工具描述别占主对话上下文，就把它只写在这里，不写进 .mcp.json。
• memory：user、project、local 三种作用域，官方推荐默认 project。开启后系统提示会带上记忆目录里 MEMORY.md 的前 200 行或前 25KB（先到为准）。
• isolation: worktree：让子 Agent 在临时 git worktree 里干活，没改东西就自动清理。

Skill 和子 Agent 怎么分工，可以对照站内Claude Code 斜杠命令怎么写：Skill 跑在主对话上下文里，子 Agent 有自己的窗口。

第五步：调用和验收

官方给了从弱到强三种调用方式：

# 1) 自然语言点名，Claude 决定要不要派
Use the code-reviewer subagent to look at my recent changes

# 2) @ 提及，这一次一定由它来跑
@"code-reviewer (agent)" look at the auth changes

# 3) 整个会话切成这个子 Agent
claude --agent code-reviewer

想让项目默认就用某个子 Agent，在 .claude/settings.json 写 {"agent": "code-reviewer"}，命令行参数会覆盖它。运行中的子 Agent 用 /tasks 查看，行上会标出它实际用的模型。

文件写完先查一遍：

claude plugin validate .claude/agents
claude --debug

plugin validate 会找出 frontmatter 解析失败的文件（不会提示缺 name）。v2.1.296 起，--debug 日志里搜 does not recognize or apply，能看到最多 5 个没认出的字段名，名字接近时还附上可能的正确写法。

常见坑

• 字段拼错没报错：多词字段是驼峰写法，maxTurns、disallowedTools 要一字不差；认不出的字段直接被忽略。
• 文件被静默跳过：没有 name、开头的 --- 不在第一行、name 以 - 开头或含 :、有 name 没 description、YAML 解析失败，这几种都会跳过且会话里不提示。
• 新建目录后找不到：会话启动时 ~/.claude/agents/ 还不存在，就监听不到，重启 Claude Code 再试。已存在的目录里增改文件，几秒内生效。
• 插件里的字段失效：出于安全考虑，插件子 Agent 会忽略 hooks、mcpServers、permissionMode。要用就把文件复制到 .claude/agents/。
• 等着 /agents 弹向导：新版本里 /agents 只提示你让 Claude 写或直接改目录；交互向导停在 v2.1.197 及更早。
• 嵌套开太多：默认子 Agent 最多往下嵌三层，同时跑满 20 个后再派会报 Concurrent subagent limit reached。分别用 CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH、CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS 调整。

拦危险命令别只靠子 Agent 的提示词，项目级的 Hooks 在子 Agent 里同样生效。

完成标准

• .claude/agents/ 或 ~/.claude/agents/ 里至少有一个带 name、description 的子 Agent 文件。
• claude plugin validate .claude/agents 通过，--debug 日志里没有未识别字段的提示。
• 用 @ 提及能派到它，transcript 里出现 code-reviewer(…) 这样的工具调用行。
• 能说清这个子 Agent 的工具白名单、模型来源和权限模式各是什么。

最后

挑一件你最常派、输出又最长的活，先写成只读子 Agent，跑顺了再加工具。什么时候该把子 Agent 折回主循环，看这篇官方思路整理。