Claude Code 子代理（subagents）怎么建、怎么用

这篇适合谁、读完能做到什么

主会话已经被大量搜索结果、日志或文件内容塞满，或者想要一个只能读、不能改的审查者的人。读完你应该能写出一个子代理文件，限定它能用的工具，知道该把它放在哪一层目录，并会用三种方式调用它。^[1]

子代理是什么，什么时候该用

子代理是专门处理某类任务的 AI 助手。它有自己的上下文窗口、自定义的系统提示、可用的工具和独立的权限。当一个支线任务会把主会话塞满你以后不会再引用的搜索结果、日志或文件内容时，就适合交给它。它处理完只把结果带回来。^[1]

文档列出的好处有五点：把探索和实现移出主对话、用工具限制约束它的行为、用户级子代理在多个项目间复用、用专门的提示词让它擅长某个领域，以及把任务分给更快、更便宜的模型（比如 Haiku）来控制成本。^[1] 它自己发出的请求也计入同一套用量。^[1]

子代理文件怎么写

子代理是带 YAML frontmatter 的 Markdown 文件。最少只需要 name 和 description，正文就是它的系统提示。一个代码审查者的例子是：^[1]

---
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.

子代理只接收自己的系统提示，外加工作目录这类基本的环境信息。^[1] description 决定 Claude 什么时候把任务委派给它，所以要写清楚。文档提醒，描述会占用上下文，所有非内置子代理的描述合计超过 15,000 token 时，启动时会有警告。^[1]

常用的 frontmatter 字段包括 tools、disallowedTools、model（可选 sonnet、opus、haiku、fable、完整模型 ID 或 inherit）、permissionMode、maxTurns、skills、mcpServers、hooks、memory、effort、isolation（设为 worktree 时在临时 git worktree 里运行）等。^[1] 字段名是驼峰式的，必须和文档完全一致。Claude Code 对不认识的字段不会报错，要找拼错的字段，可以用 claude --debug 启动后在调试日志里搜索 does not recognize or apply。^[1]

子代理文件放在哪里

子代理文件放在不同位置，作用范围不同。从高到低的优先级是：组织的托管设置、命令行的 --agents 参数（只对当前会话有效）、项目里的 .claude/agents/、个人的 ~/.claude/agents/，最低是插件的 agents/ 目录。同名时，优先级高的生效。^[1]

项目子代理适合放进版本控制，让团队一起用和改进。个人子代理放在 ~/.claude/agents/，所有项目都能用。^[1] 用 --agents 传入 JSON 定义的子代理只存在于那一次会话里，不会写进磁盘，适合临时测试或脚本。^[1]

Claude Code 会监视 ~/.claude/agents/ 和 .claude/agents/，改动几秒内就会生效。但如果某个目录在会话开始时还不存在，第一次建的子代理文件需要重启才能加载。^[1]

有一些文件会被静默跳过：没有 name 的、name 以 - 开头、含 : 或超过 256 个字符的、有 name 没有 description 的、YAML 无法解析的。文档建议用 claude plugin validate 检查目录。^[1]

怎么限制子代理的工具和权限

tools 是白名单，disallowedTools 是黑名单。两者都设置时，先应用黑名单，再在剩下的工具里解析白名单。^[1] 文档的例子是把 tools 设为 Read、Grep、Glob 和 Bash，这样它不能编辑或写入文件，也不能使用任何 MCP 工具。^[1]

permissionMode 可以设为 default（手动，会请求权限）、acceptEdits、auto、dontAsk、bypassPermissions 或 plan，其中 manual 是 default 的别名。但如果主会话已经处于 bypassPermissions、acceptEdits 或自动模式，子代理就跟着用主会话的模式，它自己的设置会被忽略。^[1]

maxTurns 限制它最多能跑几轮。达到上限时，输出会被标记为不完整，Claude 可以把它恢复继续。^[1] skills 会在启动时把列出的 skill 的完整内容预先放进它的上下文。^[1]

插件里的子代理不支持 hooks、mcpServers 和 permissionMode 字段，从插件加载时这些字段会被忽略。^[1]

子代理怎么调用

有三种方式。第一种是直接在提示里点名，比如「Use the test-runner subagent to fix failing tests」，Claude 通常会委派给它。第二种是用 @ 点名，这样一定会让那个子代理来做这一件事，写法是 @"code-reviewer (agent)" look at the auth changes。第三种是整个会话都由它来担当，用 claude --agent code-reviewer 启动。^[1]

想让某个子代理成为项目的默认，可以在 .claude/settings.json 里写 "agent": "code-reviewer"。命令行的 --agent 参数会覆盖这个设置。^[1]

前台和后台子代理有什么不同

前台子代理会阻塞主对话，直到它完成，权限请求也会直接交给你。后台子代理与你的主对话并行运行。它需要权限时，Claude Code 会在主会话里弹出提示，并注明是哪个子代理在请求。^[1]

一个常见用法是把测试输出隔离在子代理里：「Use a subagent to run the test suite and report only the failing tests with their error messages」。这样冗长的输出不会留在主会话里，只带回失败的测试和错误信息。^[1]