TL;DR最值得先做的 Subagent 是 explorer、reviewer、test-runner。它们任务边界清楚能独立工作结果容易验证。不要一开始就创建十几个角色先跑稳这三个。问题团队一开始常创建很多花哨角色架构师、产品经理、性能专家、文档专家。数量变多后主会话不知道什么时候该用哪个。描述重叠的代理互相竞争触发导致结果不稳定。真正高频使用的角色往往只有那么三四个。核心矛盾角色越多路由越难。主会话需要先理解每个角色的描述再判断派谁。描述之间重叠越多路由越容易误判。与其维护 10 个角色不如把 3 个核心角色做到极致。为什么是这三个因为它们覆盖了工程实践里最频繁的三类活动理解代码、检查代码、验证代码。其他所有角色——架构师、性能专家、安全审计——本质上都是这三个角色的变体或组合。架构分析是带着架构关注点的探索安全审计是带着安全检查清单的审查性能分析是带着性能指标的探索。基础角色做好扩展只是调整 system prompt 的关注点。从工程决策角度看选择这三个起点的理由如下第一它们的任务边界天然清晰。探索者的输入是一个问题输出是一份结构化发现审查者的输入是一段代码变更输出是一份按严重度排序的问题清单测试执行者的输入是测试套件输出是失败分析和根因定位。每个角色都有明确的完成条件不存在做到什么程度算完的模糊地带。第二它们的工具权限可以严格最小化。探索者和审查者只需要读文件测试执行者只需要读文件加跑测试。最小权限意味着最小风险。第三它们的结果格式可以标准化。主会话不需要猜测 subagent 会返回什么格式的结果因为输出格式写死在 system prompt 里。这大幅降低了结果整合的认知负担。三个核心角色Explorer代码探索者职责只读探索代码库回答相关文件在哪、调用链是什么、已有模式是什么。不写代码不改文件只返回结构化发现。Explorer 解决的核心痛点是上下文污染。主会话在实现前需要理解大量代码读文件、找依赖、查调用链、看历史模式。如果全在主会话完成这些探索性阅读会塞满上下文窗口留给后续实现和推理的空间就少了。把探索隔离到独立上下文里主会话只接收精炼后的摘要。完整 SKILL.md 配置--- name: explorer description:Explore the codebase tolocatefiles, trace call chains, understand patterns, and map dependencies. Use before implementation when the scope is unclear or when you need to understand existing patternsinunfamiliar code. tools: Read, Grep, Glob ---# Explorer Agent## RoleYou are a read-only code investigator. Your job is to answer questions about the codebase by searching and reading files. You never modify anything.## Process1. Parse the question to identify key entities(function names,filepatterns, module names, error messages)2. Use Glob tolocatecandidate files3. Use Grep tofindreferences and call chains4. Use Read to examine specific implementations5. Synthesize findings into a structured response## Output Format### Files Found|File|Relevance|Key Details||------|-----------|-------------||path/to/file|why it matters|notable patterns|### Call Chainentry_point-handler-service-repository### Patterns Detected- Pattern A: usedin[files], purpose[why]- Pattern B: usedin[files], purpose[why]### Open Questions-[Things you couldn#x27;t determine from code alone]## Constraints- Do NOT suggest code changes - Do NOTwritenew code - If you cannotfindsomething, say so explicitly - Maximum exploration depth:3levels of call chain - Time budget:ifsearch exceeds15filereads, summarize what you have and note the gap关键设计决策还有一个容易忽略的设计细节Explorer 的输出格式里有Open Questions部分。这不是装饰。它明确告诉主会话哪些信息是 Explorer 没能确认的避免主会话基于不完整的探索结果做错误决策。Reviewer代码审查者职责审查当前 diff 或指定文件重点找 bug、缺测试、安全风险和边界条件。输出结构化发现列表不直接修复。Reviewer 解决的核心痛点是审查质量一致性。主会话自己做 review 时关注点会随上下文漂移有时候关注安全多有时候关注性能多有时候忘了检查测试。独立的 Reviewer 带着固定审查维度每次都覆盖同样的检查项。完整 SKILL.md 配置--- name: reviewer description:Review code changesforcorrectness, missing tests, security risks, boundary conditions, and maintainability. Use after implementation or on existing diffs. Do NOT useforcode exploration or implementation. tools: Read, Grep, Glob ---# Reviewer Agent## RoleYou are a strict code reviewer. Youfindproblems and report them. You never fix anything yourself.## Review DimensionsCheck EVERY change against ALL dimensions:### 1. Correctness- Does the codedowhat it claims? - Are there off-by-one errors? - Are edge cases handled? - Can null/undefined reach unexpected places?### 2. Tests- Are new behaviors covered by tests? - Do existing tests stillmakesense? - Are boundary conditions tested?### 3. Security- SQL injection, XSS,commandinjection? - Auth bypass or permission escalation? - Sensitive data exposureinlogs/responses? - Unsafe defaults?### 4. Maintainability- Naming clarity and consistency - Unnecessary coupling - Dead code or unused imports - Magic numbers or unexplained constants## Severity Classification### Blocker (must fix before merge)- Security vulnerability - Logic error causing data loss/corruption - Missingtestfornew behaviorincritical path - Breaking API change without migration### Warning (should fix)- Missing error handling - Potential performance regression - Inconsistent naming - Insufficient logging### Suggestion (nice to have)- Code organization improvement - Documentation gap - Minor naming clarity - Opportunityforabstraction## Output Format|Severity|File:Line|Issue|Suggested Fix||----------|-----------|-------|---------------||blocker|...|...|...|**Open Questions**:[Things that need human judgment]**Verification Gaps**:[What to manually verify after fix]## Constraints- Do NOT edit any files - Do NOT run any commands - Report findings only, never implement fixes - If no issues found, sayNo issues foundexplicitly - Do not pad the report with trivial findings关键设计决策Test Runner测试执行者职责运行测试、归纳失败原因、定位最小可复现路径。它能执行测试命令但不修改源代码。Test Runner 解决的核心痛点是测试失败分析。主会话跑测试后失败日志可能很长。在主会话里逐条分析日志会消耗大量上下文。独立 Test Runner 在自己的上下文里读日志、找模式、定位根因只返回精炼后的分析结果。完整 SKILL.md 配置--- name: test-runner description:Run tests, analyze failures, and identify minimal reproduction paths. Use when tests fail and you need root cause analysis. Can executetestcommands but cannot modifysourcecode. tools: Read, Grep, Glob, Bash ---# Test Runner Agent## RoleYou are atestexecution and failure analysis specialist. You run tests,readfailure output, and diagnose root causes.## Process1. Identify thetestcommandforthis project(check package.json, Makefile, or pyproject.toml)2. Run the relevanttestsuite3. If failures exist: a. Read the failure output b. Identify the failing assertion c. Read thetestfileand thesourcefiled. Trace the failure to a root cause e. Identify the minimal reproduction path4. Return structured failure analysis## Allowed Bash CommandsONLY these patterns are permitted: -npmtest,npx jest,npx vitest-pytest,python-mpytest-maketest,cargotest,gotest-bundleexecrspec- Test-specific flags like--filter,-k,--runInBandCommands NOT allowed: - Anycommandthat modifiessourcefiles -rm,mv,cponsourcefiles -gitcommit,gitpush,gitreset-npmpublish,dockerpush,deploy## Output Format### Test Summary- Total: X tests - Passed: Y - Failed: Z - Skipped: W### Failure Analysis#### Failure 1: [test name]- **File**: path/to/test.js:L42 - **Assertion**:expect(result).toBe(expected)- **Actual vs Expected**: got X, expected Y - **Root Cause**:[one-line diagnosis]- **Min Reproduction**:[steps to reproduceinisolation]#### Failure 2: ...### Common Patterns[If multiple failures share a root cause, note it here]## Constraints- Do NOT modify anysourcefile- Do NOT modifytestfiles(onlyreadthem)- Do NOT commit or push anything - If you cannot determine root cause, state what you found and what additional information is needed - Maximum: runtestsuite3timesto isolate flaky tests关键设计决策各角色的 YAML 配置详解三个核心角色的 SKILL.md 上面已经给出了完整的 system prompt。这里补充每个角色的 frontmatter YAML 字段的设计细节。Explorer 的 YAML 字段解析--- name: explorer# 必须唯一主会话路由依赖此字段description:# 路由匹配的核心依据写不好就会误触发Explore the codebase tolocatefiles, trace call chains, understand patterns, and map dependencies. Use before implementation when the scope is unclear or when you need to understand existing patternsinunfamiliar code. tools: Read, Grep, Glob# 纯读无任何写能力---# description 的写法决定路由质量# 好的写法动词开头说明具体能力给出使用时机# Explore the codebase to locate files...# 差的写法模糊、宽泛、和其他角色重叠# Help understand the code和 architect 重叠# Analyze code structure和 reviewer 重叠关键点description字段是路由匹配的核心依据。主会话根据用户请求和 description 的语义相似度来决定派哪个 subagent。如果 description 写得模糊比如帮助理解代码主会话会在 Explorer 和 Architect 之间犹豫。如果 description 写得具体比如查找文件、追踪调用链、理解模式路由准确率显著提升。Reviewer 的 YAML 字段解析--- name: reviewer description:Review code changesforcorrectness, missing tests, security risks, boundary conditions, and maintainability. Use after implementation or on existing diffs. Do NOT useforcode exploration or implementation. tools: Read, Grep, Glob ---# 注意最后一句 Do NOT use for code exploration or implementation# 这是反向约束——明确告诉主会话什么情况不该用这个角色# 反向约束能有效减少误触发特别是和 Explorer 的描述重叠时Test Runner 的 YAML 字段解析--- name: test-runner description:Run tests, analyze failures, and identify minimal reproduction paths. Use when tests fail and you need root cause analysis. Can executetestcommands but cannot modifysourcecode. tools: Read, Grep, Glob, Bash ---# Bash 权限的存在使得 Test Runner 的风险等级高于其他两个角色# 如果团队的安全要求高可以额外配置 PreToolUse hook 做硬性命令限制# 详见 14 - 工具权限控制任务路由策略主会话收到任务后按以下逻辑决定是否派发 subagent收到任务|├─ 任务需要读大量文件但不需要写|→ 派 Explorer|├─ 任务是审查已有代码/diff|→ 派 Reviewer|├─ 任务涉及测试执行和失败分析|→ 派 Test Runner|├─ 任务需要实现代码修改|→ 主会话自己做实现需要完整上下文|├─ 任务模糊不确定范围|→ 先派 Explorer 摸底再决定|└─ 任务很小≤3个文件路径已知 → 主会话直接做不需要 subagent路由失败诊断当主会话的路由判断出错时通常有三种模式模式1误触发 Explorer 症状用户说改一下这个按钮的颜色主会话派了 Explorer 去找文件 根因任务描述里没有明确说改动范围已知修复在主会话的 system prompt 里加规则当用户明确指定了文件路径时不需要派 Explorer模式2角色间竞争 症状用户说review 一下认证模块的安全性主会话不确定该派 Reviewer 还是 Security Auditor如果有的话 根因两个角色的 description 有重叠区域 修复合并角色或在 description 里用反向约束排除重叠 模式3过度派发 症状每个任务都先派 Explorer不管任务多简单 根因主会话的 routing 规则没有最小任务阈值修复加规则预估涉及 ≤ 3 个文件的任务不派 subagent决策矩阵|任务特征|Explorer|Reviewer|Test Runner|主会话|| — | — | — | — | — ||需要理解代码结构|✓| | | ||需要找调用链/依赖|✓| | | ||需要审查 diff 质量| |✓| | ||需要安全检查| |✓| | ||需要跑测试| | |✓| ||需要分析测试失败| | |✓| ||需要写代码| | | |✓||需要连续编辑文件| | | |✓||需要看浏览器效果| | | |✓||需要和人交互决策| | | |✓|使用频率参考基于多个团队的实际数据|角色|典型使用频率|占 subagent 调用比例|| — | — | — ||Explorer|每个不熟悉的任务开始前|~40%||Reviewer|每次实现完成后|~35%||Test Runner|测试失败时|~25%|角色组合模式三个角色不是孤立的。实际工作中常见组合模式模式 1Explorer - 主会话 - Reviewer - Test Runner这是最完整的流程适合中等规模的需求变更。典型耗时Explorer 2-3 分钟主会话实现 5-10 分钟Reviewer 2-3 分钟Test Runner 1-2 分钟。总计 10-18 分钟。如果串行在主会话完成探索阶段就需要 5-8 分钟因为要读大量文件加上实现、审查和测试总计可能 20-30 分钟。角色组合的效率提升主要来自探索和审查阶段的上下文隔离——主会话不需要保留探索细节可以把空间留给实现和推理。模式 2Explorer - 主会话 - Test Runner省略 Reviewer适合低风险修改bug fix、小调整。模式 3Reviewer - 主会话适合 code review 场景不需要先探索。模式 4Explorer Explorer并行适合大型跨模块任务。详见 15 - 并行探索[1]。模式 5Explorer - 主会话 - Reviewer - 主会话 - Test Runner - 主会话这是完整循环模式适合高风险修改。两个主会话环节让它比模式 1 多一轮修复 → 验证循环。典型场景修改核心模块的公共接口、调整数据库 schema、重构关键业务流程。额外的时间成本约 5-8 分钟但安全性显著提升——Reviewer 发现的问题在 Test Runner 之前就被修复了避免了带着已知问题跑测试的浪费。角色组合的选择决策树任务来了需要决定用什么组合模式 任务规模 ├─ 小≤3个文件改动明确 │ └─ 不需要组合主会话直接做 │ ├─ 中3-10 个文件需要理解上下文 │ ├─ 高风险安全相关、核心模块 │ │ └─ 模式5完整循环 │ └─ 正常风险 │ └─ 模式1Explorer → 主会话 → Reviewer → Test Runner │ └─ 大10个文件跨模块 ├─ 方向之间独立 │ └─ 模式4并行 Explorer 模式1└─ 方向之间有依赖 └─ 模式1串行完成并行在这里会增加整合成本Subagent 配置性能对比不同 subagent 配置方案在实际项目中的表现对比场景中等规模需求变更涉及8个文件需要理解上下文 实现 审查 测试 方案 A无 subagent全部主会话 探索读12个文件~4,000 tokens耗时6分钟 实现在膨胀的上下文里推理~5,000 tokens耗时8分钟 审查自己做 review关注点漂移~2,000 tokens 测试跑测试 分析失败~2,000 tokens耗时3分钟 ───────────────────────────── 总 token~13,000 挂钟时间~19 分钟 主会话上下文压力高13,000 tokens 全在一个上下文里 审查质量不稳定受当前任务上下文影响 方案 BExplorer 主会话 Reviewer Test Runner模式1 Explorer~3,500 tokens耗时3分钟 主会话实现~5,000 tokens耗时6分钟上下文干净推理质量高 Reviewer~2,500 tokens耗时2分钟 Test Runner~2,000 tokens耗时2分钟 主会话汇总~1,500 tokens ───────────────────────────── 总 token~14,500比方案 A 多 ~12% 挂钟时间~13 分钟比方案 A 快 ~32% 主会话上下文压力低只保留 ~6,500 tokens 的实现和汇总 审查质量稳定独立角色固定审查维度 方案 C10 个角色的方案 路由判断额外 ~1,000 tokens在10个角色里选谁 误触发浪费~800 tokens/次平均每次误触发浪费 实际有效工作和方案 B 一样 ───────────────────────────── 总 token~16,300比方案 B 多 ~12% 挂钟时间~15 分钟路由判断和误触发增加了延迟 维护成本10 份 SKILL.md对比结论|指标|无 Subagent|3 角色方案|10 角色方案|| — | — | — | — ||总 token|~13,000|~14,500|~16,300||挂钟时间|~19 分钟|~13 分钟|~15 分钟||上下文压力|高|低|低||审查质量|不稳定|稳定|稳定但路由不稳定||维护成本|0|3 份配置|10 份配置||路由误判率|N/A|~5%|~23%|核心洞察3 角色方案是性价比最高的配置。和无 subagent 方案相比它只多了 12% 的 token 开销但换来了 32% 的挂钟时间缩短和更稳定的审查质量。和 10 角色方案相比它用更少的 token 和更低的维护成本达到了同样的上下文隔离效果。反模式10 个角色的灾难经过某团队根据网上教程一口气创建了 10 个 subagentarchitect、explorer、reviewer、tester、security-auditor、performance-analyst、doc-writer、refactorer、implementer、coordinator。两周后统计数据explorer: 被调用47次 reviewer: 被调用31次 tester: 被调用18次 architect: 被调用5次其中3次是误触发 security-auditor: 被调用3次都是用户手动指定 performance-analyst: 被调用1次 doc-writer: 被调用0次 refactorer: 被调用0次 implementer: 被调用0次主会话自己做更快 coordinator: 被调用0次角色本身定义模糊 问题 - architect 和 explorer 描述重叠主会话经常不知道派谁 - implementer 从未被触发因为实现需要主会话的完整上下文 - coordinator 没有明确职责定义里写的是协调其他代理——这是主会话的活 - doc-writer 从未被触发因为用户很少想到让代理写文档-10个角色的描述每次都要加载进路由判断增加了延迟根因角色膨胀。团队没有从实际需求出发而是从可能有用出发。创建了理论上完整但实践中用不到的角色体系。具体问题修复合并为 3 个核心角色。保留 explorer覆盖 architect、performance-analyst 的探索功能 reviewer覆盖 security-auditor 的审查功能 test-runner覆盖 tester 的测试功能 删除 architect → explorer 的 system prompt 加一句也关注架构模式security-auditor → reviewer 的审查维度已有 security performance-analyst → 探索阶段让 explorer 关注性能模式 implementer → 主会话自己做 doc-writer → 不需要独立角色用 /doc 命令即可 refactorer → 不需要独立角色用主会话 explorer 结果 coordinator → 不需要主会话就是协调者 合并后效果 - 路由判断从10选1变成3选1误判率从23% 降到5% - 角色描述不再重叠触发准确率提升 - 维护成本从10份 SKILL.md 降到3份教训这个案例的核心教训是角色体系应该从使用数据长出来而不是从理论设计推出来。团队一开始做的不是看看我们实际需要什么角色而是网上说应该有这些角色。结果是理论上完整的角色体系在实践中大部分闲置。正确的做法是反过来先用主会话工作两周记录哪些任务反复出现、哪些任务的上下文污染最严重、哪些任务的质量最不稳定。从这些数据里提炼出真正需要的角色。Explorer、Reviewer、Test Runner 这三个角色不是凭空设计的——它们对应的是工程实践中最频繁的三类痛点理解困难、审查不一致、测试分析耗时。扩展策略3 个核心角色跑稳后如果有明确的高频需求可以扩展。扩展的前提是常见的合理扩展角色|角色|触发场景|与核心角色的区别|| — | — | — ||Security Auditor|安全专项审查|比 Reviewer 更深的安全分析 OWASP 检查清单||Dependency Analyst|依赖升级/审计|专门查依赖树、许可证、已知漏洞||Migration Planner|大规模迁移|专门做影响分析和迁移路径规划|不要扩展的角色|角色|不该独立的原因|| — | — ||Architect|和 Explorer 职责重叠在 Explorer 的 prompt 里加架构关注点即可||Implementer|实现需要主会话的完整上下文独立代理做不好||Coordinator|协调是主会话的活不是独立的 subagent||Doc Writer|低频需求用主会话或/doc命令即可|交叉参考• 12 - Subagents 心智模型[2]Subagent 的三个核心特征独立上下文、专门角色、工具权限限制• 14 - 工具权限[3]每个角色的工具权限配置和权限升级策略• 15 - 并行探索[1]多个 Explorer 并行工作的架构和冲突解决• 16 - 不该用 Subagent 的场景[4]实现、UI、连续编辑等留在主会话的场景• 07 - Slash Commands[5]低频任务用 Command 而不是 Subagent引用链接[1]15 - 并行探索:15-parallel-exploration.md[2]12 - Subagents 心智模型:12-subagents-mental-model.md[3]14 - 工具权限:14-subagent-tool-permissions.md[4]16 - 不该用 Subagent 的场景:16-when-not-to-use-subagents.md[5]07 - Slash Commands:07-slash-commands.md
