用 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 配置，优先级从高到低：

位置	作用范围	优先级
组织级托管配置	整个组织	最高
--agents CLI 参数	当前会话	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" 能找到。有问题评论区聊。