如何设计 Claude Code SubAgent 的隔离、专业化和权限？

提一嘴博主开源的以 Claude Code 为基础的 GUI 图形化桌面客户端应用 Misaka（ GitHub 地址：https://github.com/knqiufan/Misaka 项目完全开源，是个学习项目，还有比较多的地方待优化，欢迎大家来提 Issue 和 PR 另外 Claude Code 的其他相关文章： 关于完全指南： Claude Code 完全指南：使用方式、技巧与最佳实践 关于 Skill： 从对话到协作，Skills 如何改变我们与 AI 共事的方式 引言 从"这东西有什么用"聊到"它底下是怎么跑的"，一篇讲完。 目录 入门篇 一个比喻理解 SubAgent SubAgent 解决的三个核心问题 你可能已经在使用了 什么时候该用，什么时候不该用 实践篇 三步创建自定义 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。它的定位很明确：快速搜索、只读分析。