Claude Code SubAgents 配置实战：4个现成配置，复制就能用
用 Claude Code 做项目有个烦人的事：上下文窗口不够用。
让它查一下某个模块的实现逻辑，它把 20 个文件的内容全塞进对话里。查完之后你说"好，现在改这个函数"，它告诉你上下文快满了，要不要压缩。
上周我重构一个 Express 项目，让 Claude Code 先摸清路由结构，再改中间件。光是"摸清"这一步，它读了 34 个文件，上下文用掉 60%。等到真正要改代码的时候，已经没多少空间了。
SubAgents 就是解决这个问题的。它让你把"查资料"和"干活"拆到不同的上下文窗口里。查完的 Agent 把结论给你，原始内容不会污染主对话。
Claude Code 自带的三个 SubAgent
装完 Claude Code 就有三个内置 SubAgent，不用配置：
Explore：用 Haiku 模型跑，只有读权限，不能改文件。你让 Claude Code 去了解一个不熟悉的代码库，它会自动把任务丢给 Explore。速度快，成本低，查完把摘要丢回来。
Plan：在 plan mode 下工作。你开了 plan mode 让 Claude Code 先做方案再动手，它会派 Plan 去读代码、收集信息，然后拿着信息回来给你做规划。用的是主对话的模型。
general-purpose：啥都能干，有完整的工具权限。当任务比较复杂、需要又读又写的时候，Claude Code 会用这个。
这三个是自动调度的，你不用手动指定。Claude Code 看任务类型自己选。
自定义 SubAgent：两种创建方式
方式一：命令行交互创建
在 Claude Code 里输入：
/agents切到 Library 标签页，选 Create new agent。它会问你几个问题：
- 放在哪里？Personal（存到
~/.claude/agents/，所有项目都能用）还是 Project（存到.claude/agents/，只在当前项目生效） - 要什么工具权限？只读、全部、还是自己选
- 用什么模型？Haiku 便宜快，Sonnet 平衡，Opus 贵但强
- 要不要持久记忆？开了的话 SubAgent 会在
~/.claude/agent-memory/存东西
方式二：直接写 Markdown 文件
在~/.claude/agents/或.claude/agents/下创建一个.md文件。格式是 YAML frontmatter + Markdown 正文：
--- name: my-agent description: 一句话描述这个 Agent 干什么 tools: Read, Glob, Grep, Bash model: sonnet --- 你是一个专门做 XX 事情的 Agent。 这里写系统提示词，告诉它该怎么工作。存好之后重启 Claude Code 生效。用/agents创建的不用重启，即时生效。
作用域和优先级
多个地方都能放 SubAgent 配置，优先级从高到低：
| 位置 | 作用范围 | 优先级 |
|---|---|---|
| 组织级托管配置 | 整个组织 | 最高 |
--agentsCLI 参数 | 当前会话 | 2 |
.claude/agents/ | 当前项目 | 3 |
~/.claude/agents/ | 所有项目 | 4 |
| 插件的 agents 目录 | 装了插件的项目 | 最低 |
同名时高优先级覆盖低优先级。
4 个直接能用的 SubAgent 配置
下面是我在用的 4 个 SubAgent，直接复制文件到~/.claude/agents/就行。
1. 代码审查 Agent
--- name: reviewer description: 代码审查，检查质量和安全问题。在代码修改后主动使用。 tools: Read, Glob, Grep, Bash model: sonnet --- 你是代码审查员。收到代码后做这几件事： 1. 检查有没有明显 bug（空指针、数组越界、未处理异常） 2. 检查安全问题（SQL 注入、XSS、硬编码密钥） 3. 检查性能问题（N+1 查询、不必要的循环、内存泄漏风险） 4. 风格问题只提严重的，别纠结缩进和命名偏好 输出格式： - 问题等级（严重/警告/建议） - 文件名和行号 - 问题描述 - 修复方案 不要说"代码整体写得不错"之类的话。有问题说问题，没问题就说没发现问题。这个 Agent 用 Sonnet 跑，够用了。给它只读权限加 Bash（用来跑 lint 或 grep），不给写权限，防止它一边审查一边改。
2. 测试生成 Agent
--- name: test-writer description: 给代码生成单元测试。在写完新函数或修改逻辑后使用。 tools: Read, Write, Edit, Glob, Grep, Bash model: sonnet --- 你是测试工程师。根据源代码生成测试用例。 规则： - 先读源文件，搞清楚函数的输入输出和边界条件 - 测试框架跟项目已有的保持一致（看 package.json 或 pom.xml） - 每个函数至少覆盖：正常输入、边界值、异常输入 - mock 外部依赖，不要让测试依赖数据库或网络 - 测试文件放在对应的 __tests__ 或 test 目录下 - 写完跑一遍 `npm test` 或对应的测试命令，确认能通过 不要生成那种只测试 "1+1=2" 的无效测试。重点测试业务逻辑的分支。这个需要写权限，因为它要创建测试文件。
3. 文档扫描 Agent
--- name: doc-scanner description: 扫描项目文档和 README，找出过时或缺失的内容。 tools: Read, Glob, Grep model: haiku --- 你是文档审计员。扫描项目的文档文件，检查这些问题： 1. README 里的安装步骤能不能跑通（对照 package.json 的 scripts） 2. API 文档里的参数和实际代码是否一致 3. 配置示例里的环境变量在代码里是否真的用到了 4. 有没有引用了已删除的文件或函数 输出一个清单，列出每个问题的位置和建议修复方式。用 Haiku 就够了，只需要读文件和匹配文本，不需要多强的推理。省钱。
4. Git 日志分析 Agent
--- name: git-analyst description: 分析 Git 历史，生成变更摘要或排查问题引入时间。 tools: Read, Bash, Grep model: haiku --- 你是 Git 历史分析员。通过 git log、git diff、git blame 分析仓库历史。 常见任务： - 生成最近 N 天的变更摘要（按模块分组） - 找出某个 bug 是哪个 commit 引入的 - 统计各开发者的提交频率和改动量 - 分析某个文件的修改历史 用 git 命令获取数据，然后整理成可读的报告。不要输出原始 git log，要做归纳。用 CLI 参数临时创建 SubAgent
不想写文件？用--agents参数启动 Claude Code 时临时定义：
claude --agents '{ "quick-grep": { "description": "快速搜索代码中的模式", "prompt": "你是代码搜索工具。用户给你一个搜索目标，你用 grep 和 glob 找到所有相关代码位置，输出文件路径和行号。", "tools": ["Read", "Grep", "Glob", "Bash"], "model": "haiku" } }'这个 SubAgent 只在当前会话存在，关掉就没了。适合临时用一次的场景。
踩坑记录
1. SubAgent 不能再套 SubAgent
SubAgent 内部不能再派 SubAgent。这是设计上的限制，防止无限嵌套。如果你的任务需要多层委派，考虑用 Agent Teams（多个 Agent 直接通信）或 Background Agents（并行跑多个独立会话）。
2. 文件创建后要重启
手写.md文件放到 agents 目录后，必须重启 Claude Code 才能加载。用/agents命令创建的不需要重启。我第一次用的时候写好文件，结果怎么都调不出来，折腾了半小时才发现要重启。
3. description 写清楚，不然 Claude 不知道啥时候用
Claude Code 看 description 决定什么时候调用这个 SubAgent。写太笼统（比如"一个有用的助手"），它可能永远不会用。写清楚具体场景："在代码修改后主动审查代码质量"，它才知道什么时候该派这个 Agent 出去。
4. 工具权限给少不给多
审查类的 Agent 别给写权限。我有一次给 reviewer 开了 Write，它一边审查一边把它觉得有问题的代码改了——没经过我确认。后来把 Write 去掉，改成只读，它老老实实只输出报告。
5. 同名冲突不报错
同一个 scope 下（比如~/.claude/agents/）如果有两个文件声明了同一个 name，Claude Code 随机保留一个，不会提示你。建议用不同的 name 值，或者整理好目录结构。
frontmatter 字段速查
| 字段 | 作用 | 示例值 |
|---|---|---|
| name | SubAgent 标识符 | reviewer |
| description | 触发条件描述 | 代码审查 Agent |
| tools | 允许使用的工具 | Read, Glob, Grep, Bash |
| disallowedTools | 禁止使用的工具 | Write, Edit |
| model | 使用的模型 | haiku / sonnet / opus |
| permissionMode | 权限模式 | plan（只读）/ full |
| maxTurns | 最大对话轮次 | 10 |
| memory | 持久记忆范围 | user / project / none |
| hooks | 生命周期钩子 | 同 Claude Code Hooks |
| skills | 加载的技能文件 | ["./skills/lint.md"] |
| color | UI 背景色 | blue |
什么时候该用 SubAgent
不是什么任务都要拆成 SubAgent。判断标准：
这个任务会往上下文塞一堆你后面用不到的内容吗？如果是，拆出去。
你经常重复给 Claude Code 同样的指令吗？如果是，做成 SubAgent。
你想让某类任务用便宜的模型跑吗？如果是，做成 SubAgent 指定 Haiku。
如果只是一个简单的"帮我改这个函数"，直接在主对话里做，别过度设计。
配置文件都在 GitHub Gist 上存了一份，搜 "claude-code-subagents-config" 能找到。有问题评论区聊。