这东西有什么用聊到它底下是怎么跑的一篇讲完。目录入门篇一个比喻理解 SubAgentSubAgent 解决的三个核心问题你可能已经在使用了什么时候该用什么时候不该用实践篇三步创建自定义 SubAgent配置文件完全指南前台、后台与恢复最佳实践Prompt 怎么写原理篇为什么 SubAgent 是一个微型会话两条路径的设计取舍专业化 vs 缓存效率权限模型单向棘轮原则工具池设计最小权限原则的实际落地生命周期管理Agent 定义的加载策略信任的梯度MCP Server 的隔离策略共享 vs 专属的取舍Worktree 隔离让子代理在自己的沙箱里改代码从 Sub-Agent 到 Multi-Agent架构选型的三角博弈附录总结一下源码里藏着的设计巧思源码关键文件索引入门篇1. 一个比喻理解 SubAgent想象你是一个项目经理主 Agent手下有几个专员SubAgent。你不会自己去翻 200 个文件找答案——你会把任务交给调研专员让他去翻他翻完了最终再把结论汇报给你。这就是 SubAgent 做的事主 Agent 把任务派给一个独立的子进程去执行子进程干完后只把结论带回来。比如 Claude Code 内部的工具调用Agent({ SubAgent_type: Explore, prompt: 搜索整个代码库找出所有 API 端点定义 })这段调用会启动一个 Explore 类型的子代理它自己去搜索、读取文件、分析代码最后把结果摘要返回。主 Agent 只看到结论不看到过程。一句话总结SubAgent 一个拥有独立上下文窗口的自治 Worker干完活只交结论。2. SubAgent 解决的三个核心问题问题一上下文污染Claude 的上下文窗口再大也是有限的。如果让主 Agent 自己去搜 30 个文件那些搜索结果、文件内容、中间分析全部留在主对话里等真正要做决策时那上下文窗口可能已经快满了。SubAgent 的解决方案是让自己天然拥有一个独立的上下文窗口。即中间过程全都留在子代理里主对话只看结论。也就是说子代理执行完毕后这些中间内容就消失了。简单判断如果信息对当下执行是必要的但对后续决策是噪声——用子代理。问题二行为不可控主 Agent 通常拥有完整的工具权限读文件、写文件、执行命令。但某些任务你只想让它看不想让它改。对于这个问题 SubAgent 的解决方案是精确的工具权限控制。即我们可以定义一个只读型子代理只给它Read、Grep、Glob三个工具这样它想改也改不了了。# 只读型子代理代码审查 tools: Read, Grep, Glob # 开发型子代理bug 修复 tools: Read, Write, Edit, Bash # 研究型子代理技术调研 tools: Read, WebFetch, WebSearch问题三经验无法沉淀每次都要手动告诉 Claude 去查这个、用那个方式分析。这些操作步骤无法复用。针对这个问题 SubAgent 的解决方案是配置即文件。子代理的定义保存在.md文件中可以放进 Git 与团队共享好用的配置可以复制到其他项目。所以 SubAgent 可以用三个词概括隔离、约束、复用。那么再从更高层面看 SubAgent 的设计哲学其实就是将一个大脑拆成多个岗位角色每个岗位只做一件事并且有明确的权限边界。3. 你可能已经在使用了Claude Code 内置了几个 SubAgent。当你在对话里说”帮我看看代码库结构”、”先规划一下怎么做”、或者 Claude 自动走验证流程的时候这些 SubAgent 就在干活。而你可能根本没注意到。Explore代码库的搜索引擎Explore 是最常用的内置 SubAgent。它的定位很明确快速搜索、只读分析。当我们在对话里说比如”帮我找一下所有 API 端点的定义”或者”这个函数在哪些地方被调用了”Claude 就会启动 Explore 去干活。它会把成百上千行的 grep 结果、文件读取、路径分析全吞进自己的上下文里最后只给你一份干净的摘要。搜索深度分三档quick、medium默认、very thorough。这个档位是可以在 prompt 里指定的Explore 会据此调整搜多广。这不是代码层面的硬限制纯粹是 prompt 级别的指导quick 就是跑几条 grep 就收工适合”某个 class 在哪个文件”这种目标明确的问题medium 则会多搜几个路径、多读几个文件适合”这个模块的结构是怎样的”very thorough 会在多个目录和命名规范下反复搜尽量不留死角——适合”梳理认证流程从入口到数据库的完整调用链”。工具方面 Explore 能用 Glob按文件名搜、Grep按内容搜、Read读文件、Bash但只能跑只读命令。在前段时间 Claude Code 暴露的源码里使用disallowedTools硬性屏蔽了 Edit、Write、NotebookEdit。说明它确实改不了东西。外部用户跑 Explore 用的是 Haiku快且便宜。Anthropic 内部用户则会继承主 Agent 的模型。Claude Code 暴露的源码里有个不太起眼的阈值EXPLORE_AGENT_MIN_QUERIES 3。这个参数的作用是主 Agent 被告知任务只需要 1-2 次搜索就搞定的别启动 Explore直接用 Grep/Read只有明确需要 3 次以上查询时才值得派出去。另外Explore 默认省略 CLAUDE.md 和 gitStatus能到 40KB。只读代理不需要知道 commit 规范和 PR 流程自己会跑git status。这一项每周会省 5-15 Gtok。Plan动手之前先想清楚Plan 的定位是软件架构师。它不写代码专门在动手之前把方案想透。比如当我们跟 Claude 说”我想给系统加个支付模块”这个时候 Claude 就会先派 Plan 去调研Plan 会读现有代码、找已有的模式和约定、理清依赖关系、最后输出一份分步实施计划。系统提示给 Plan 定义了四步流程理解需求深入探索读代码、追踪调用链、参考已有实现设计方案考虑取舍输出计划分步策略、依赖关系、可能的坑。输出必须以”Critical Files for Implementation”结尾并列出最关键的 3-5 个文件这样主 Agent 拿到这份计划就知道下一步该读什么、改什么了。Plan 跟 Explore 一样只读——同样的使用了disallowedTools改不了文件。但模型不同Plan 继承主 Agent 的模型不会降级到 Haiku。架构设计需要更强的推理能力用便宜模型容易翻车。Explore 和 Plan 的分工边界是Explore 搜完就交结果Plan 搜完还要分析、权衡、给建议。找函数在哪用 Explore搞清”加这个功能要改哪些文件、按什么顺序改”用 Plan。General-purpose什么都干的全能选手Explore 和 Plan 都被硬性禁止了 Edit、Write 等工具但 General-purpose 没这个限制。tools: [*]即父 Agent 有什么它就能用什么这是它跟 Explore/Plan 的根本区别。搜索和规划是只读的活儿而 General-purpose 要真刀真枪改代码。系统提示很短两段话完事Given the users message, you should use the tools available to complete the task. Complete the task fully — dont gold-plate, but dont leave it half-done.意思是把活干完别画蛇添足但也别半途而废。General-purpose 适合的场景是那种连贯的多步骤流程先读代码定位问题、再改代码、再跑测试验证。比如”修复认证模块的登录 bug”这种任务。模型字段故意留空由getDefaultSubagentModel()在运行时决定是跟着会话配置走的。Claude Code Guide——产品文档专家Claude Code 还有一个不太起眼的内置 SubAgentclaude-code-guide。当你问”Claude Code 怎么配 hooks”、”Agent SDK 怎么用”的时候Claude 会派它去查官方文档。它的工具是 Glob、Grep、Read、WebFetch、WebSearch。Haiku 模型dontAsk 权限不弹确认框。干活流程是先抓code.claude.com和platform.claude.com的文档索引再定位到具体页面拿答案。Verification——专门来挑刺的Verification 的系统提示第一句话就说Your job is not to confirm the implementation works — its to try to break it.它不是来验证”代码能跑”的它是来找茬的。当主 Agent 完成一项实现任务后Verification 被自动调用。它会跑构建、测试、lint然后根据变更类型前端、后端、CLI、数据库迁移等各有各的检查套路做针对性验证还要跑边界值测试和对抗性探测。输出格式要求严格每条检查必须附带实际执行的命令和输出不能只说”看起来没问题”。最后给出 VERDICTPASS、FAIL 或 PARTIAL。默认后台运行模型继承主 Agent。这五个内置 SubAgent 各管一摊搜索、规划、执行、查文档、找茬。共同点是它们都把高噪声的工作留在子进程里不让垃圾信息堆到主对话中。4. 什么时候该用什么时候不该用其实判断标准很简单主对话需不需要承载过程本身适合用 SubAgent 的场景有高噪声输出的任务——主对话只关心结论不关心过程。比如搜索 30 个文件找一个 API 定义。角色边界非常明确的任务——天然需要和其他任务隔离开。比如代码审查只看不改。可以并行执行的研究型任务——比如同时调研三个模块的实现方式。可以拆成清晰阶段的流水线式任务——比如先调研再规划再实现。不适合用 SubAgent 的场景你想做的事该用什么读取一个已知路径的文件Read工具搜索 class Foo 在哪Grep工具在 2-3 个文件里找东西Read工具简单的文本修改Edit工具直接改重要提醒子代理不能再嵌套调用子代理。所有编排都必须由主对话完成流水线的调度中心只有一个。实践篇5. 三步创建自定义 SubAgent方式一交互式推荐新手在 Claude Code 中输入/agents按照向导操作即可。方式二手写配置文件推荐进阶直接创建.claude/agents/your-agent.md文件。优势是更精细的控制、方便版本管理、可以从其他项目复制。方式三CLI 参数临时创建适合 CI/CD通过--agents参数在启动时传入 JSON 格式的子代理定义。仅在当前会话中存在不会保存到磁盘。claude --agents [{name:lint-checker,tools:[Bash,Read]}]这种方式特别适合 CI/CD 自动化在流水线中临时创建任务专用的子代理。6. 配置文件完全指南一个完整的子代理配置文件长这样--- name: code-reviewer description: Review code for security issues and best practices. Use after code changes. tools: - Read - Grep - Glob permissionMode: plan model: sonnet skills: - chain-knowledge - recent-incidents hooks: PreToolUse: - matcher: Bash hooks: - type: command command: ./scripts/validate-readonly-query.sh --- 你是一个代码审查专家。 当被调用时 1. 首先理解代码变更的范围 2. 检查安全问题 3. 检查代码规范 4. 提供改进建议 输出格式 ## 审查结果 - 安全问题[列表] - 规范问题[列表] - 建议[列表]