Subagents

上下文膨胀

你让 Claude 先实现一个功能，再审查一遍。它既知道自己的实现意图，又要假装从外部视角审查。审查变成了走过场——它很难对自己的代码说"这里有问题"。

目标冲突

一个会话里既要"写新功能"又要"跑测试"又要"生成文档"。Claude 的注意力被分散，每个任务的输出质量都不如单独做。

安全风险

审查员不应该有写权限。但在同一个会话里，它既能读代码也能改代码——你没法约束它"只看不改"。

上下文隔离

主 Agent 上下文约 50K token，每个 Subagent 获得干净的独立上下文（约 20K token）。它看不到主会话的对话历史，只接收任务描述，完成后只返回结果——中间过程不污染主上下文。

单一职责

一个 agent 只做一件事。审查员不做实现，实现者不做审查。

最小权限

精确控制每个 agent 能用哪些工具。审查型 agent 只给 Read、Grep、Glob，不给 Edit 和 Write。

并行执行

多个 agent 可以同时处理不同任务。安全审查和质量审查可以并行跑，最后汇总。

1. 单一职责

每个 agent 只负责一个领域。不要让"审查员"同时负责测试。如果两个职责都需要，做两个 agent。

2. 可验证产物

每个 agent 的输出应该有明确的格式和验收标准。这样主 agent 才能汇总多个角色的结果。

3. 最小权限

审查型 agent 只需只读工具（Read、Grep、Glob），不要给写权限。实现型 agent 需要编辑权限，但要限制作用范围。

4. 清晰红线

明确列出"绝对不能做的事"。比如审查员不能改代码，实现者不能删测试。

Code Reviewer 只读

工具：Read, Grep, Glob

审查代码质量、命名规范、结构可读性、耦合度和可维护性。输出按严重程度分类（高/中/建议），每条包含文件路径、行号、问题描述和修复建议。

Secure Reviewer 只读

工具：Read, Grep（最小权限集）

专注安全漏洞：硬编码密钥、SQL 注入、命令注入、XSS、API key 泄露、PII 处理。按 OWASP 分类，每条包含 Severity、漏洞类型、影响和修复方案。

Debugger 读写

工具：Read, Edit, Bash, Grep, Glob

排错流程：分析错误 → 检查最近变更 → 提出假设 → 隔离故障 → 最小修复 → 验证。输出包含根因、证据、修复内容、回归检查。

Test Engineer 读写

工具：Read, Write, Bash, Grep

编写单元测试、集成测试、边界情况测试。遵循项目现有框架（Jest/pytest 等），目标 80%+ 覆盖率，关键路径 100%。

Documentation Writer 读写

工具：Read, Write, Grep

生成 API 文档、用户指南、架构文档和 Changelog。基于实际代码验证准确性，包含参数说明、返回值、错误码和可运行的示例。

Implementation Agent 全权限

工具：Read, Write, Edit, Bash, Grep, Glob

端到端功能实现：理解需求 → 分析代码库 → 制定方案 → 逐步实现 → 边做边测 → 清理重构。红线：不删测试、每次改动不超过 5 个文件、不改配置。

Data Scientist 读写

工具：Bash, Read, Write | 模型：sonnet

SQL 查询、BigQuery 操作、数据洞察。支持探索性分析、统计分析和报告生成。输出包含目标、查询、结果、洞察和建议。

Clean Code Reviewer 只读

工具：Read, Grep, Glob, Bash

按 Clean Code 原则（Robert C. Martin）审查：命名、函数长度、SOLID、DRY/KISS/YAGNI、坏味道。四级严重度：Critical（50 行+函数）→ Low（轻微可读性）。

验证安装

1. 运行 /agents，检查对应 agent 是否出现在列表中
2. 试着让 Claude 委派一个简单任务，观察是否自动分派
3. 直接说"用 code-reviewer 审查这段代码"来手动指定

文件结构 （点击文件名查看角色定义）

.claude/agents/
├── clean-code-reviewer.md
├── code-reviewer.md
├── data-scientist.md
├── debugger.md
├── documentation-writer.md
├── implementation-agent.md
├── secure-reviewer.md
└── test-engineer.md

自动委派

主 Agent 根据 description 字段自动判断。你只需正常描述任务，它会自己找到合适的 agent。

用户: "审查这段代码的安全性"
# 主 Agent 自动选择 secure-reviewer

显式指定

直接说出 agent 名称，跳过自动匹配。

用户: "用 code-reviewer 审查 src/auth.ts"
# 直接调用指定角色

@ 提及调用

在对话中通过 @agent-name 方式引用。

用户: "@debugger 这个空指针异常怎么修？"
# 直接唤起 debugger 角色

会话级固定

在整个会话中固定使用某个 agent。适合长时间专注某一领域。

$ claude --agent code-reviewer
# 整个会话都用 code-reviewer

设计要点

• 每个 agent 的输出格式要标准化，方便下一个 agent 解析
• 前一步发现问题可以中断链路，让主 Agent 决定是修还是继续
• 串联链路不宜超过 4-5 个环节，否则延迟和 token 消耗会失控

何时用串联 vs 并行

• 有依赖关系 → 串联（实现完了才能审查）
• 互相独立 → 并行（安全审查和质量审查同时跑）
• 混合场景 → 先并行收集，再串联处理（并行审查后，串联通往文档更新）

团队配置要点

• 角色定义要清楚——每个角色的职责边界和输出格式都要明确
• 任务边界要明确——不要让多个 agent 做重复工作
• 计划审批流程——如果是 plan 驱动，团队会先审计划再执行

交互能力

• 显示模式：终端或图形界面，选择适合你的显示方式
• 导航：可以在 team 中切换角色、查看状态和读取消息
• Hook 事件：一些 hook 可以在 team 生命周期中触发（启动/完成/失败）

Subagent 生命周期

从创建到结束，一个 subagent 经历五个阶段：

1. 创建  → 加载角色卡，初始化隔离上下文
2. 分配  → 主 Agent 传入任务描述和必要信息
3. 执行  → 在隔离上下文中独立运行，调用工具
4. 返回  → 输出结构化结果，汇总到主会话
5. 结束  → 上下文销毁，或挂起等待恢复

可恢复的 Agent

某些 subagent 可以先启动、之后再恢复——适合长任务接力。比如一个耗时的大规模重构，你可以今天做到一半，明天恢复继续。

结合后台执行，你可以：启动 agent → 去做别的事 → 回来检查进度 → 继续或结束。

保持子上下文精简

• 只传递任务所需的最少信息——不要把整个对话历史都丢进去
• 用 context 字段控制 agent 能看到多少信息
• 让每个 agent 只负责自己的事，不要"什么都想知道"

性能考虑

• 过多的上下文会拖慢推理速度并降低准确性
• 如果发现 agent 输出质量下降，先检查是不是塞了太多无关信息
• 子上下文尽量控制在 5K token 以内，把空间留给结果

限制可启动的 Agent

你可以限制 Claude 只能 spawn 某些 subagent，降低风险。

# settings.json 示例
{
  "agents": {
    "allowList": ["code-reviewer", "secure-reviewer"],
    "denyList": ["implementation-agent"]
  }
}

# 只允许审查类 agent，禁止高风险自动化

适用场景：CI/CD 管道中只允许只读审查，生产环境禁止自动修改代码。

插件分发安全

插件分发的 subagent 要特别注意：

• 权限范围：检查 tools 字段，确保没有超出预期的权限
• 边界条件：第三方 agent 的 prompt 可能包含你不知道的指令
• 最小信任：对插件提供的 agent 采用与自定义 agent 相同的审查标准

角色重叠

症状：两个 agent 做了同样的分析，结果冲突，token 白白浪费。

修复：检查每个 agent 的职责边界。code-reviewer 看代码质量，secure-reviewer 看安全漏洞——维度不重叠。

权限过大

症状：审查型 agent 拿到了 Edit 权限，审查过程中顺手"修"了代码。

修复：审查型角色的 tools 字段只保留 Read、Grep、Glob。需要修改时让主 agent 另派实现型 agent。

输出格式不统一

症状：不同 agent 的输出格式各异，主 agent 无法汇总。

修复：在 Skill 的模板中定义统一的输出格式，所有 agent 执行时都引用同一个模板。

重复劳动

症状：多个 agent 各自读同一份文件做类似分析。

修复：让主 agent 先做一次预分析（提取关键信息），再分派给不同角色，避免重复读取。

到这里，你已经能

• 说清 Subagent 解决什么问题（上下文隔离、角色专精）
• 设计角色边界和权限（单一职责 + 最小权限）
• 用串联或并行方式组织多角色协作
• 利用后台执行和 Worktree 隔离管理复杂任务
• 控制上下文大小、限制可启动的 agent 范围
• 理解内置角色、Agent Teams 与 Skill 的配合

它和前后章节的关系

• Skills — 为 Subagent 提供执行手册
• Subagents — 定义"谁来做"
• MCP — 让 agent 访问外部工具和数据
• Hooks — 自动化角色间的质量门禁

继续本课程

• 下一章：MCP — 让 agent 访问外部工具和数据
• Hooks — 自动化角色间的质量门禁

本章源文件

• 04-subagents/ 目录 — 所有角色定义文件
• 推荐先看 code-reviewer.md，再看 secure-reviewer.md