用 Claude Code 干活的人多少都遇到过这种场面：让它查一个依赖的来源、扫一遍目录结构、总结一组报错日志，主对话里刷出一屏又一屏的中间输出，上下文肉眼可见地膨胀，token 账单跟着涨。更麻烦的是，这些查询结果会一直赖在上下文里，对后面的每一步决策形成干扰。子代理就是为这个问题准备的机制：主代理把脏活派出去，子代理在独立上下文里跑完，只回传一段摘要，主上下文保持干净。这篇 SOP 带你在终端里养一支这样的分身工程队，从创建、字段配置、模型路由到常见翻车，按步骤走完就能上手。文中所有口径截至 2026 年 10 月 8 日，版本与价格以官方页面实时显示为准。
先交代本批的时点背景：Anthropic 在 2026 年 10 月 7 日刚发布 Claude Haiku 5.5，走量档价格杀到每百万 token 输入 0.10 美元、输出 0.50 美元，上下文扩到 1M，还成为首个支持可调 effort 的 Haiku 级模型。这对子代理玩法是直接利好，因为子代理恰恰是 Haiku 这类小模型的主战场。发布热点与本篇互补：那篇算的是模型本身的账，见 Claude Haiku 5.5 发布热点解读；这篇解决怎么在 Claude Code 里把它用起来。
第零步：先对表你的可用状态
动手前先确认三件事，避免配到一半发现基础不齐。
- 检查 Claude Code 版本。在终端执行：
claude --version预期结果：显示版本号。子代理的 effort 参数需要 v2.1.292 及以上（10 月 7 日 release note 口径），版本旧了先升级，再跑一遍确认。
-
确认子代理功能入口。在 Claude Code 交互界面输入 /agents，预期结果：弹出子代理管理面板，能看到 Create、Edit、Delete、View 四个动作，以及内置代理列表。
-
认识三个内置代理，它们不用配置就能用。Explore 是只读搜索代理，跑在 Haiku 上，支持 Quick、Medium、Very thorough 三档力度，适合「帮我找到所有用到这个函数的地方」这类查询；Plan 负责在进入 plan mode 前收集上下文；General-purpose 跑在 Sonnet 上、带全部工具，适合一次性的多步任务。预期结果：你心里有一张现成的人力表——通用查询先派 Explore，定制化需求再自己养分身。
对表完成的标准：版本达标、/agents 面板能打开、三个内置代理的分工能一句话说清。三项全过，进入第一步。
第一步：用 /agents 创建，搞清两个文件位置
创建有两条路，殊途同归，产物都是带 YAML frontmatter 的 markdown 文件。
路线一：对话式创建。 在 Claude Code 里输入 /agents 选 Create，用自然语言描述你要的代理，让 Claude 帮你生成初稿。这一步的建议是先让 Claude 生成，再按 e 进入编辑手改——初稿给你结构，细节自己调，比从零写省事。
路线二：直接写文件。 文件位置有两个，优先级是关键考点：
- 项目级 .claude/agents/：只对当前项目生效，团队可随仓库共享，优先级更高。
- 用户级 ~/.claude/agents/：对你所有项目生效，适合个人通用工具。
同名冲突时项目级覆盖用户级。预期结果：把文件放进对应目录后，在 /agents 面板里能看到它，状态正常。
一个最小可用的分身长这样（这就是后面所有配置的骨架）：
---
name: code-reviewer
description: 代码审查专家。写完代码后主动调用，检查质量、安全与可维护性。
tools: Read, Grep, Glob
model: sonnet
---
你是资深代码审查专家。收到代码后按安全、正确性、可维护性三个维度审查，
输出问题清单与修改建议，不要直接改动任何文件。预期结果：保存后主代理能在合适的场景自动委派它，或者你点名让它干活。存进 .claude/agents/ 并提交仓库，整个团队都能吃到这份配置。
第二步：frontmatter 字段逐个讲透
创建只是把壳立起来，真正的功夫在 frontmatter 的每个字段上。逐个过：
**name：**小写加连字符，如 code-reviewer、log-triage。这是主代理点名调用的 ID，起名要见名知义。
**description：**最值钱的字段。它决定主代理会不会自动把任务派给你这个分身。写法要点：第一，说清这个代理干什么、什么时候用；第二，想让它被主动委派，就写上 Use PROACTIVELY 或 MUST BE USED 这类触发语。反例是「一个助手」，主代理看了也不知道什么时候该派它。
**tools：**最小权限原则的落点。省略则继承全部工具，这是最省事也最危险的选择。只读审查类给 Read、Grep、Glob 就够；测试类可以给 Bash。预期结果：即便模型跑偏，也没有越权工具可用。
**model：**路由的核心字段，取值 sonnet、opus、haiku 或 inherit。省略时默认 sonnet。怎么选放到第三步细讲。
**permissionMode：**权限模式，default 是最稳的档，acceptEdits 自动接受文件编辑，bypassPermissions 跳过全部确认——后者只给你完全信任的封闭任务用，别当默认值。
**skills：**子代理的技能清单。注意它不继承父级的 skills，需要什么就显式写什么，别默认它会。
**hooks：**支持 PreToolUse、PostToolUse、Stop 三类，可以在分身的工具调用前后和收尾时挂校验逻辑。注意 once 触发方式不支持，需要一次性动作就写进系统提示词里。
预期结果：你能对着任何一个现成分身的配置，说出每个字段为什么这么填。字段全部过一遍后，你的分身才从「能跑」升级到「可控」。
第三步：模型路由，把每种模型用在刀刃上
子代理最大的杠杆是模型路由：脏活不必都派旗舰。社区生产实践里已经沉淀出一套分工口径——注意这是社区单源口径，不是官方数据，参考量级即可：同一类查找任务，Haiku 约 8 秒完成、成本 0.03 美元、一次通过率 60%；Sonnet 约 45 秒、0.24 美元、85%；Opus 约 2 分钟、1.20 美元、95%。三档差距接近四十倍成本，路由选对等于直接省钱。
按社区总结的经验法则，default to Haiku for subagents unless the task requires reasoning，具体分工：
| 任务类型 | 模型 | 理由 |
|---|---|---|
| 查找、摘要、分类、抽取 | haiku | 便宜快速，错了重跑也不心疼 |
| 多文件改动、调试 | sonnet | 平衡智力与成本的主力档 |
| 架构决策、复杂推理 | opus | 只留给真正需要深度的活 |
预期结果：你的工程队里 Haiku 型分身占大多数，Sonnet 型管主力执行，Opus 型一两个压舱。对照价格感受一下这套搭配的威力：Sonnet 5.5 是每百万 token 输入 2 美元、输出 10 美元，缓存读在随发调价后减半到 0.10 美元；Haiku 5.5 输入价只有它的二十分之一。主代理用 Sonnet 级控场，查找摘要全部下沉给 Haiku 分身，一个典型开发日的 token 账单结构就完全不同了。两款模型的定位差异，本站在 Claude Sonnet 5.5 发布热点 里对照拆过，可配合阅读。
第四步：与 Haiku 5.5 联动，吃满新模型红利
这一步是本批的时点红利，配对了能直接改你的成本结构。
第一件事：model 字段直接填 haiku。 这个值指向的是当前最新的 Haiku——也就是说 10 月 7 日 Haiku 5.5 发布后，你存量配置里所有 model: haiku 的分身自动吃上新模型，一行不用改。Haiku 5.5 的 1M 上下文意味着查找类分身现在可以吞下大仓库的检索结果再压缩回传，这在上一代的 200K 上限下是做不到的。价格账在第三步已经算过，这里是执行动作：检查你现有的分身配置，凡是查找摘要类，确认没有错写成 sonnet。
第二件事：升级到 v2.1.292 用 effort 参数。 按 10 月 7 日 release note 口径，这个版本给 Agent tool 加了 effort 参数，还新增了 claude plugin install --marketplace 的插件安装路径。effort 的价值在于成本与智能可以在同一请求内二选一：批量分类、格式抽取这类机械活把 effort 调低，token 消耗进一步下降；偶尔遇到要细抠的任务再调高。它是第一个下放到 Haiku 级别的可调档位，意味着你那支 Haiku 分身队整体多了一个省钱旋钮。
预期结果：claude --version 显示不低于 v2.1.292；查找类分身跑在 Haiku 5.5 上；高吞吐场景下 effort 档位按任务机械程度调节。预算紧张、想在 Claude Code 里接第三方模型的读者，本站的 DeepSeek-V4-Pro 跑通 Claude Code 实战 给了另一条省钱路线，两条路不冲突。
第五步：常见翻车，四个坑一个都别踩
配置层面踩的坑，社区反馈里高度集中，逐个列：
坑一：子代理再派子代理。 子代理拿不到 Task 工具，它无法再往下派分身。如果你的系统提示词里写了「必要时创建其他代理来协助」，这条指令在子代理内部是死代码。预期改法：分身只负责自己那一层，层级编排全部留在主代理。
坑二：description 写得太泛。 「通用助手」「帮忙干活」这类描述，主代理无从判断委派时机，结果要么从不被自动调用，要么什么活都往它身上派。预期改法：描述里写清任务类型加触发时机，关键代理加上 Use PROACTIVELY。
坑三：tools 全开。 省略 tools 继承全部工具虽然省事，但一个只做日志摘要的分身握着全部工具，等于给每次委派都留了越权口子。预期改法：按第二步的最小权限原则逐个收窄。
坑四：把实现任务留给子代理。 Anthropic 的 Adam Wolf 说过一个判断：子代理最适合查信息加少量摘要回传，实现类任务应该留在主代理。子代理改代码，你看到的只是它的转述，过程不可见、方向纠不了。预期改法：查找、审查、测试跑分身，写代码的活主代理自己干。
还有一条隐性坑：把重复上下文塞给每个分身。有社区案例统计过，系统提示词里冗长的项目背景在多个分身间重复，单次会话能白白烧掉 700K 以上的 token。分身的系统提示词写职责，项目背景靠主上下文传递，别复制粘贴。
预期结果：对照这四加一条自查你的配置，每条都能给出明确的改法或不犯的理由。
可复用骨架：四类分身直接抄
最后给一套拿来即用的骨架，按需增删：
---
name: security-reviewer
description: 安全审查员。MUST BE USED：涉及鉴权、输入处理、依赖变更的代码必须调用。
tools: Read, Grep, Glob
model: sonnet
---
你是安全审查专家。只读代码，重点检查注入、越权、敏感信息泄漏，
按严重程度输出问题清单，不修改任何文件。---
name: log-triage
description: 日志分诊员。Use PROACTIVELY：需要从大段日志中定位错误模式时调用。
tools: Read, Grep, Bash
model: haiku
---
你是日志分析员。从给定日志中提取错误、频次与可疑模式，
用不超过十行回传结论，保留关键行号。debugger 与 test-writer 同理：debugger 给 sonnet 加 Bash 用于复现，test-writer 给 sonnet 加 Read 与 Write。骨架的共同规律就一句话——职责单一、工具最小、模型按需。想在动手前先看看别的编码工具怎么选型薅额度，本站的 AI 编码工具免费额度横评 可以对照着看。
常见问题
**Q1：**子代理和直接在主对话里让 Claude 干活，到底差在哪？ A1：核心差别是上下文隔离。子代理有独立的上下文窗口，相当于 fork 了一份项目视图，跑完只回传摘要，主上下文不被中间过程污染。查询、扫描、审查这类会产生大量中间输出的活，派子代理既省主上下文的空间，也让主代理的决策不被噪音干扰。
**Q2：**model 字段省略不写，子代理用什么模型？ A2：省略时默认 sonnet。所以想让查找类分身吃到 Haiku 5.5 的低价，必须显式写 model: haiku，不写它就按 Sonnet 计费。inherit 则表示跟随主代理当前模型，适合想让分身与主代理保持同智力的场景。
**Q3：**项目级和用户级分身同名了，用哪个？ A3：项目级优先。.claude/agents/ 里的同名配置会覆盖用户级 ~/.claude/agents/ 的。团队协作的标准做法是通用工具放用户级，项目专用分身放项目级并提交到仓库，成员克隆即得。
**Q4：**子代理能帮我写代码吗？ A4：技术上能，但不建议。子代理的隔离机制决定它改完代码你只能看到转述，过程不可见。Anthropic 的建议口径是子代理最适合查信息加摘要回传，实现类任务留在主代理。审查、测试这类只读或低风险任务才适合派出去。
**Q5：**不想付 Anthropic API 费用，这套玩法还有别的路吗？ A5：有两条替代线。一是本站写过的 DeepSeek-V4-Pro 接入 Claude Code 的环境变量方案，用第三方兼容接口跑同一套子代理机制；二是先薅各编码工具的免费额度练手，横评见 AI 编码工具免费额度横评。子代理的配置方法本身是通用的，换了底层模型照用。
参考来源
- Anthropic 官方文档与 2026-10-07 release note：/agents 命令、frontmatter 字段、文件位置与优先级、v2.1.292 effort 参数与 plugin install --marketplace
- Claude Haiku 5.5 发布信息（2026-10-07，官方口径）：定价、1M 上下文、可调 effort、API id claude-haiku-5-5
- 社区生产实践与第三方博客（单源口径，已标注）：模型路由分工与成本对比数据
- Anthropic Adam Wolf 关于子代理适用边界的公开表述；GitHub issue 社区反馈：常见错误清单
本文基于官方文档与社区口径整理（截至 2026-10-08），成本数据为标注过的社区单源口径，非官方基准；版本能力与价格以官方页面实时显示为准。