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. 检查性能问题N1 查询、不必要的循环、内存泄漏风险 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 或对应的测试命令确认能通过 不要生成那种只测试 112 的无效测试。重点测试业务逻辑的分支。这个需要写权限因为它要创建测试文件。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 不能再套 SubAgentSubAgent 内部不能再派 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/如果有两个文件声明了同一个 nameClaude Code 随机保留一个不会提示你。建议用不同的 name 值或者整理好目录结构。frontmatter 字段速查字段作用示例值nameSubAgent 标识符reviewerdescription触发条件描述代码审查 Agenttools允许使用的工具Read, Glob, Grep, BashdisallowedTools禁止使用的工具Write, Editmodel使用的模型haiku / sonnet / opuspermissionMode权限模式plan只读/ fullmaxTurns最大对话轮次10memory持久记忆范围user / project / nonehooks生命周期钩子同 Claude Code Hooksskills加载的技能文件[./skills/lint.md]colorUI 背景色blue什么时候该用 SubAgent不是什么任务都要拆成 SubAgent。判断标准这个任务会往上下文塞一堆你后面用不到的内容吗如果是拆出去。你经常重复给 Claude Code 同样的指令吗如果是做成 SubAgent。你想让某类任务用便宜的模型跑吗如果是做成 SubAgent 指定 Haiku。如果只是一个简单的帮我改这个函数直接在主对话里做别过度设计。配置文件都在 GitHub Gist 上存了一份搜 claude-code-subagents-config 能找到。有问题评论区聊。