TL;DRSubagent 不是更聪明的 Claude。它是一块隔离的执行沙箱独立上下文窗口、独立系统提示词、独立工具白名单。用来做完成后汇报的专门任务而不是替代主会话做持续编辑。问题主会话在处理复杂项目时面临三重压力Subagent 解决的核心问题不是让 AI 更聪明而是让 AI 在受限环境里做一件专门的事然后把结论带回来。系统设计视角Subagent 的架构可以用四个隔离维度来描述。理解这四个维度是正确使用 subagent 的前提因为每一个维度都对应一个具体的工程决策。┌─────────────────────────────────────────────────┐ │ 主会话 │ │ ┌─────────────────────────────────────────────┐ │ │ │ 系统提示CLAUDE.md rules session hist │ │ │ │ 工具集全部可用工具 │ │ │ │ 上下文所有累积对话 文件内容 │ │ │ └─────────────┬───────────────────────────────┘ ││ │ 派发任务 │ │ ▼ │ │ ┌─────────────────────────────────────────────┐ │ │ │ Subagent 执行沙箱 │ │ │ │ │ │ │ │ 系统提示agent .md 文件中的角色指令 │ │ │ │ 工具集tools 字段声明的白名单 │ │ │ │ 上下文空白起步只读任务相关的文件 │ │ │ │ 模型可独立指定轻量任务用快模型 │ │ │ │ │ │ │ └─────────────┬───────────────────────────────┘ │ │ │ 结构化结果返回 │ │ ▼ │ │ 主会话继续后续工作 │ └─────────────────────────────────────────────────┘上下文隔离是 subagent 最重要的属性。Subagent 从空白上下文开始运行它看不到主会话中已经发生的对话、已经读取的文件内容、已经做出的决策。反过来主会话也不会自动获得 subagent 运行过程中产生的中间产物——读取的文件、搜索的结果、推理的中间步骤。双方之间的唯一通信通道是 subagent 完成任务后返回的那一条结构化消息。这种隔离的设计意图不是保密而是隔离噪音。安全审查过程中读过的四十个文件不需要留在主会话的上下文里继续占用空间。角色绑定意味着每个 subagent 的系统提示词就是它的完整身份定义。提示词里写了什么它就知道什么。安全审查员不知道项目的部署流程、测试命令或分支策略因为它的提示词里没有这些信息。测试运行器不需要关心代码风格规则因为它的角色定义里没有风格检查的职责。这种只知道自己该知道的设计减少了角色混淆导致的越界行为。工具白名单通过tools字段实现。配置中显式列出的工具是 subagent 唯一可以调用的工具不在列表里的工具对它来说不存在。这是行为约束的最底层防线——即使角色指令写得不够明确工具权限也能硬性阻止越界操作。一个只有 Read、Grep、Glob 的 subagent 物理上无法修改文件无论它的提示词怎么写。模型路由允许不同 subagent 使用不同的底层模型。对精度要求高的安全审计可以指定更强的模型对速度要求高的代码探索可以指定更快的模型。这个维度在成本敏感的生产环境中尤其重要。三个真实 Agent 配置示例 Asecurity-reviewer——只读安全审计# .claude/agents/security-reviewer.md---name:security-reviewerdescription:审查代码变更中的安全漏洞。 在认证、权限、数据处理的改动后使用。tools:Read,Grep,Glob---## 角色你是安全审计员。你的任务是发现代码中的安全风险不是修复它们。## 检查范围-认证绕过session 校验缺失、token 验证跳过-注入攻击SQL 拼接、命令注入、XSS 模板拼接-敏感数据暴露日志中的密钥、API 响应中的内部 ID、硬编码凭据-不安全默认值缺失的权限校验、宽松的 CORS、未设过期时间的 token## 输出格式对每个发现输出 1. 严重级别critical / high / medium / low 2. 文件路径和行号 3. 问题描述一行 4. 影响范围一句话 5. 修复建议具体到操作不要泛泛而谈## 禁止事项-不要修改任何文件-不要输出完整的修复代码只输出建议-不要对没有文件证据的风险做推测性判断这个配置的核心约束在tools: Read, Grep, Glob。三个工具全部是只读操作Read 读取文件内容Grep 搜索文件内容中的模式Glob 按文件名模式查找文件。没有 Edit、Write 或 Bash审计员发现问题的能力和它修复问题的能力被硬性分离。这种分离不是限制而是精确匹配——安全审计的交付物是发现列表不是修复补丁。示例 Btest-runner——测试执行与失败分析# .claude/agents/test-runner.md---name:test-runnerdescription:运行测试并分析失败原因。 在实现完成后验证或 CI 失败后定位问题。tools:Read,Grep,Glob,Bash---## 角色你是测试工程师。运行测试、归纳失败、定位根因。## 工作流程1. 先读 CLAUDE.md 获取项目测试命令 2. 运行测试等待结果 3. 对每个失败用例 a. 读失败的测试文件和对应源文件 b. 分析是断言错误、环境问题还是代码 bug c. 定位最小可复现路径 4. 归纳失败模式同类失败合并不要逐条罗列## 输出格式## 测试结果概要-通过:X / 总计:Y-失败模式:[列表]## 失败分析### 模式 1: [名称]-涉及测试:[列表]-根因:[描述]-涉及文件:[路径列表]-最小复现:[具体命令或步骤]!--codex:illustration 12-subagents-mental-model/04-compare-guardrails.svg--!--/codex:illustration--## 未覆盖风险-[列出跑不通或跳过的测试]## Bash 使用限制-只允许运行测试相关命令test,jest,vitest,pytest 等-不允许运行安装、构建、部署命令-不允许修改任何文件与 security-reviewer 的区别在于tools里多了Bash因为测试分析需要实际执行测试命令来获取运行结果。但 Bash 是一个高权限工具——理论上可以执行任意命令——所以角色指令里对 Bash 的使用范围做了明确约束只允许运行测试相关命令不允许运行安装、构建或部署命令更不允许用它来修改文件。这种给权限但约束范围的做法比完全不给权限更合理因为测试分析的核心价值就在于实际运行测试并解读输出只读代码文件无法替代真实的测试执行结果。示例 Capi-explorer——API 契约与集成分析# .claude/agents/api-explorer.md---name:api-explorerdescription:分析 API 契约和集成关系。 在接口变更、新增端点或排查集成问题时使用。tools:Read,Grep,Glob---## 角色你是 API 架构分析师。分析接口定义、调用关系和契约一致性。## 检查范围1. 找到所有 API 端点定义路由文件、controller、handler 2. 对每个端点提取HTTP 方法、路径、请求参数、响应结构 3. 找到所有调用方前端调用、其他服务调用 4. 检查契约一致性参数类型是否匹配、必填项是否对齐、错误处理是否覆盖## 输出格式## API 地图|端点|方法|路径|调用方|契约状态||------|------|------|--------|---------|## 契约不一致-[端点A]:[具体不一致描述]-[端点B]:[具体不一致描述]## 未覆盖的集成点-[列表]## 约束-只读分析不修改文件-不做性能评估只做契约一致性检查-如果项目没有明确的 API 层说明情况后停止这三个配置有共同结构角色定义 → 检查范围 → 输出格式 → 约束。这个结构不是僵硬的模板而是角色有效性的最低要求。没有明确检查范围的角色会输出泛泛建议——比如一个没有写明只查认证漏洞的安全审查员可能把代码风格、性能、可读性全部评论一遍淹没了真正重要的安全问题。没有输出格式的角色会返回不可操作的大段自然语言文字主会话难以从中提取可执行信息。没有约束的角色会越界——这在后面的失败案例中会详细说明。共同结构的另一个好处是可维护性。当团队有十几个 subagent 配置时统一的结构让新成员能快速理解每个角色的职责边界也便于在 code review 中检查配置是否完整。主会话 vs Subagent 决策矩阵|维度|留在主会话|派发给 Subagent|| — | — | — ||任务范围|单模块、少量文件|多模块、大量文件||上下文污染风险|低读几个文件|高需要遍历几十个文件||角色专业化|通用实现任务|专门角色安全、测试、API||工具需求|与主会话一致|需要限制工具集||结果类型|直接执行动作|返回报告/建议||是否需要并行|单线程即可|多方向并行探索||上下文依赖|依赖当前会话状态|可以独立完成||交互频率|需要频繁人工确认|完成后一次性汇报||错误成本|低容易回退|低subagent 不改文件时零风险|实际使用中的判断逻辑任务来了 │ ├─ 需要改文件吗 │ ├─ 否 → 考虑 subagent审查、分析、探索 │ └─ 是 → 需要改很多文件吗 │ ├─1-3 个 → 主会话直接做 │ └─10 个 → 拆成探索subagent 实现主会话 │ ├─ 需要读很多文件但只返回结论吗 │ ├─ 是 → subagent │ └─ 否 → 主会话 │ └─ 需要并行做多方向调研吗 ├─ 是 → 多个 subagent └─ 否 → 主会话上下文隔离的量化分析主会话的上下文窗口是有限资源。以下是一个真实的 token 消耗对比场景安全审查一次涉及 40 个文件的认证模块重构主会话直做 ┌──────────────────────────────────────────────┐ │ 基础上下文CLAUDE.md rules 对话历史 │ ~25K tokens │ 审查过程读取40个文件的内容 │ ~80K tokens │ 审查结论 │ ~3K tokens │ ───────────────────────────────────── │ │ 合计 │ ~108K tokens │ 后续实现可用的上下文空间 │ ~92K tokens假设 200K 窗口 │ │ │ 问题审查过程的 80K tokens 会持续占据上下文 │ │ 即使后续实现只需要其中 5K 的结论部分。 │ └──────────────────────────────────────────────┘ Subagent 方案 ┌──────────────────────────────────────────────┐ │ 主会话 │ │ 基础上下文 │ ~25K tokens │ 审查结论subagent 返回的摘要 │ ~3K tokens │ ───────────────────────────────────── │ │ 合计 │ ~28K tokens │ 后续实现可用的上下文空间 │ ~172K tokens │ │ │ Subagent 内部用完即弃 │ │ 角色指令 │ ~1K tokens │ 读取的文件内容 │ ~80K tokens │ 中间分析过程 │ ~20K tokens │ │ │ 净效果主会话省下 ~80K tokens 的上下文空间 │ └──────────────────────────────────────────────┘关键数字subagent 的 80K tokens 中间产物不会进入主会话。主会话只接收 3K tokens 的结构化结论。这在大型项目中是决定能做还是做不了的差异。通信协议Subagent 到主会话的通信是单向的。Subagent 完成任务后返回一条消息这条消息成为主会话的输入。协议设计要点Subagent 输出模板嵌入 agent 配置的输出格式部分## 任务结果### 摘要[一段话总结核心发现]### 详细发现|# | 类型 | 严重级别 | 文件 | 描述 ||---|------|---------|------|------||1|...|...|...|...|### 建议1.[具体操作建议]2.[具体操作建议]### 未确认项-[无法确认但可疑的点]主会话如何使用返回结果!-- 主会话收到 subagent 返回后的处理流程 -- 1. 检查摘要是否回答了原始问题 2. 如果发现项有 critical/high 级别 → 优先处理 3. 如果建议可直接执行 → 按建议修改 4. 如果未确认项影响决策 → 追加调查或人工确认 5. 不要把 subagent 的建议当真理需要根据当前上下文判断优先级失败情况的处理subagent 执行超时、工具调用失败或无法完成任务时返回的是错误信息而不是结构化报告。主会话需要处理这两种情况成功返回 → 解析结构化报告 → 继续工作 失败返回 → 判断是否重试 / 切换方案 / 留给人工失败案例工具权限未限制场景。团队创建了一个code-reviewersubagent配置如下# 原始配置有问题---name:code-reviewerdescription:Review code changes for bugs and style issues.# 注意没有 tools 字段---Review the current diff for bugs,style violations,and missing tests. Return findings with severity and file references.发生了什么。团队在 PR 审查流程中使用这个 subagent期望它输出审查报告。但运行后发现根因。配置中没有tools字段。Subagent 继承了主会话的全部工具权限包括 Edit、Write 和 Bash。角色指令里说Return findings但工具权限没有强制约束这个行为。LLM 面对可以编辑文件的能力时倾向于直接修复而不是只报告。修复# 修复后的配置---name:code-reviewerdescription:Review code changes for bugs and style issues.tools:Read,Grep,Glob# 显式限制为只读---Review the current diff for bugs,style violations,and missing tests. Return findings with severity and file references.## 禁止事项-不要修改任何文件-不要输出修复代码只输出发现和建议教训。角色指令是建议工具权限是约束。两者必须配合使用。当两者发生冲突时——提示词说只报告但工具权限允许编辑——LLM 会倾向于使用它能使用的工具因为能修就直接修看起来比发现问题但不修更有效率。这是一个典型的能力与职责不匹配问题。只读角色的tools字段必须显式排除 Edit、Write 和 Bash 等写操作工具不能依赖提示词里的不要修改文件来约束行为。这个问题在团队中反复出现的变体包括探索型 subagent 因为有 Bash 权限而开始运行构建命令审查型 subagent 因为有 Edit 权限而直接修改代码风格。解决方案都一样在tools字段里只声明完成任务所需的最小工具集。资源竞争分析Subagent 与主会话共享 API 速率限制和账户 token 预算。并行调度多个 subagent 时如果不考虑资源竞争会导致主会话的请求被限流甚至整个工作流因为 429 错误而中断。资源竞争不是理论问题而是在实际使用中频繁遇到的工程约束。速率限制竞争假设 API 限制:60requests/min 主会话正常使用: ~20 requests/min Subagent A(安全审查): ~15 requests/min Subagent B(测试运行): ~10 requests/min Subagent C(API 分析): ~12 requests/min 并行运行:2015101257requests/min → 接近限制主会话可能出现429错误管理策略|策略|做法|适用场景|| — | — | — ||串行调度|一个 subagent 完成后再启动下一个|速率限制严格时||有限并行|最多 2-3 个 subagent 同时运行|常规场景||优先级队列|高优先级 subagent 先执行低优先级等结果|有明确优先级的任务||结果缓存|相似任务的 subagent 结果复用|重复性审查|Token 预算竞争每个 subagent 的执行都消耗 token。三个并行 subagent 各消耗 30K tokens总计 90K tokens。这笔消耗不会从主会话的上下文窗口中扣除因为上下文是隔离的但会从账户的 API 预算中扣除。在设计工作流时需要根据任务价值来评估 token 投入是否合理。一个影响全局安全性的审计任务值得投入 30K tokens但一个格式检查任务可能不值得单独启动一个 subagent。实际建议落地清单开始使用 subagent 前按以下顺序确认• [ ]角色定义。每个 subagent 有明确的一句话职责描述。如果说不清它只做什么说明角色太宽。• [ ]工具白名单。每个 subagent 的tools字段显式声明。只读角色排除 Edit、Write、Bash。• [ ]输出格式。subagent 返回结构化结果不是自然语言段落。主会话需要能解析结论。• [ ]触发条件。description字段写清楚什么时候该用这个 subagent。这是主会话的路由依据。• [ ]失败处理。subagent 超时或失败时主会话知道该怎么继续重试 / 切换 / 人工。• [ ]资源预算。并行 subagent 不超过 3 个。单次任务的总 token 预算有上限。• [ ]验证。第一次使用新 subagent 时检查它是否遵守了工具限制和输出格式。不要假设配置生效。延伸阅读• 13 - 三类高价值 Subagent[1]最值得先做的三种 subagent——explorer、reviewer、test-runner——的设计模式和配置• 14 - 工具权限[2]只读审计代理为什么不能有写权限权限分级和最小权限原则• 15 - 并行探索[3]多个 subagent 并行研究不同方向的编排策略和结果汇总方法• 25 - Subagent Hooks[4]启动时注入规则、结束时收集结果的 Hook 配置权衡Subagent 的核心价值是上下文隔离和角色专业化但它也引入了调度成本和结果整合成本。任务越模糊subagent 越容易输出泛泛建议。角色必须窄——一个只查认证漏洞的安全审查员比一个什么都查的安全专家更有效。不要为了使用 subagent 而拆分任务。判断标准不是这个任务够不够复杂而是隔离上下文和限制工具能不能让结果更可控。如果答案是否定的留在主会话更稳妥。引用链接[1]13 - 三类高价值 Subagent:./13-high-value-subagents.md[2]14 - 工具权限:./14-subagent-tool-permissions.md[3]15 - 并行探索:./15-parallel-exploration.md[4]25 - Subagent Hooks:./25-subagent-hooks.md