返回
Everything Claude Code 系列 开发工具

Everything Claude Code 教程 5：Subagents - 子代理架构与任务委托

本文详解 Everything Claude Code 的 Subagents 系统，包含子代理创建、工具权限控制和多代理协作模式。

教程概述

Subagents（子代理）是 Everything Claude Code 的核心架构特性，允许主代理将任务委托给专门的子代理，实现并行执行和专业分工。

你将学到

  • ✅ Subagent 工作原理
  • ✅ 创建自定义 Subagent
  • ✅ 工具权限控制
  • ✅ 多代理协作模式
  • ✅ 迭代检索模式

什么是 Subagents？

Subagents 是独立运行的代理进程，主代理可以将特定任务委托给它们：

flowchart TD
    subgraph 主代理
        A[Orchestrator] --> B[任务分析]
        B --> C[任务分发]
    end

    subgraph 子代理
        D[Planner] --> E[规划]
        F[Architect] --> G[架构审查]
        H[Code Reviewer] --> I[代码审查]
        J[Tester] --> K[测试]
    end

    C --> D
    C --> F
    C --> H
    C --> J

    E --> A
    G --> A
    I --> A
    K --> A

    style A fill:#e3f2fd
    style D fill:#e8f5e9
    style F fill:#fff3e0
    style H fill:#fce4ec

为什么需要 Subagents？

场景 无 Subagents 有 Subagents
上下文管理 主代理上下文爆炸 子代理独立上下文
并行执行 顺序执行 真正并行
专业分工 一个代理做所有事 专家代理各司其职
权限控制 完全权限 可限制子代理权限
成本优化 全部用高级模型 简单任务用便宜模型

Subagent 架构图

flowchart LR
    subgraph 用户
        U[用户请求]
    end

    subgraph 主代理
        O[Orchestrator<br/>Opus/Sonnet]
    end

    subgraph 子代理池
        S1[Explorer<br/>Haiku]
        S2[Planner<br/>Sonnet]
        S3[Architect<br/>Opus]
        S4[Reviewer<br/>Sonnet]
        S5[Tester<br/>Haiku]
    end

    U --> O
    O --> S1
    O --> S2
    O --> S3
    O --> S4
    O --> S5

    S1 --> O
    S2 --> O
    S3 --> O
    S4 --> O
    S5 --> O

目录结构

~/.claude/agents/
├── planner.md           # 功能实现规划
├── architect.md         # 系统架构设计
├── tdd-guide.md         # 测试驱动开发
├── code-reviewer.md     # 代码质量审查
├── security-reviewer.md # 安全漏洞分析
├── build-error-resolver.md  # 构建错误解决
├── e2e-runner.md        # 端到端测试
├── refactor-cleaner.md  # 代码清理
└── doc-updater.md       # 文档同步

创建自定义 Subagent

Subagent 文件格式

创建 ~/.claude/agents/my-agent.md：

---
name: my-agent
description: "代理描述"
model: sonnet  # haiku/sonnet/opus
tools:
  allowed:
    - Read
    - Grep
    - Glob
  denied:
    - Bash
    - Write
timeout: 300  # 秒
---

# Agent 角色定义

你是一个专门的 [角色]，负责 [职责]。

## 工作流程

1. 接收任务
2. 分析需求
3. 执行操作
4. 返回结果

## 输出格式

[定义期望的输出格式]

示例 1：代码审查 Agent

创建 ~/.claude/agents/code-reviewer.md：

---
name: code-reviewer
description: "代码质量和安全审查专家"
model: sonnet
tools:
  allowed:
    - Read
    - Grep
    - Glob
    - Bash
  denied:
    - Write
    - Edit
timeout: 300
---

# 代码审查专家

你是一个专业的代码审查专家，负责审查代码质量和安全性。

## 审查范围

### 1. 代码质量
- 命名规范
- 代码重复
- 复杂度
- 可读性

### 2. 安全检查
- 输入验证
- SQL 注入
- XSS 漏洞
- 敏感数据暴露

### 3. 性能
- 算法复杂度
- 资源泄漏
- 不必要的计算

### 4. 最佳实践
- 设计模式
- SOLID 原则
- 错误处理

## 输出格式

```markdown
## 审查报告

### 严重问题 (Critical)
- [文件:行号] 问题描述

### 重要问题 (Major)
- [文件:行号] 问题描述

### 建议改进 (Minor)
- [文件:行号] 建议内容

### 整体评分
X/10

### 改进建议
[具体改进步骤]


### 示例 2：测试运行 Agent

创建 `~/.claude/agents/test-runner.md`：

```markdown
---
name: test-runner
description: "执行测试并分析结果"
model: haiku
tools:
  allowed:
    - Bash
    - Read
    - Grep
  denied:
    - Write
    - Edit
timeout: 600
---

# 测试运行器

你负责运行测试套件并分析结果。

## 工作流程

1. 检测项目类型和测试框架
2. 运行适当的测试命令
3. 分析测试结果
4. 报告失败原因

## 测试命令映射

| 项目类型 | 命令 |
|---------|------|
| Node.js | `npm test` 或 `pnpm test` |
| Python | `pytest` |
| Go | `go test ./...` |
| Rust | `cargo test` |

## 输出格式

```markdown
## 测试结果

### 摘要
- 总测试数: X
- 通过: X
- 失败: X
- 跳过: X

### 失败详情
[失败的测试及原因]

### 建议修复
[如何修复失败的测试]


### 示例 3：文档更新 Agent

创建 `~/.claude/agents/doc-updater.md`：

```markdown
---
name: doc-updater
description: "保持文档与代码同步"
model: haiku
tools:
  allowed:
    - Read
    - Write
    - Edit
    - Glob
    - Grep
timeout: 300
---

# 文档更新器

你负责确保文档与代码实现保持同步。

## 检查项

1. API 文档与实际接口一致
2. README 中的示例可运行
3. CHANGELOG 更新
4. 注释与代码逻辑匹配

## 输出格式

```markdown
## 文档更新报告

### 需要更新的文档
- [文件] 更新原因

### 已更新的内容
- [文件] 具体更改

### 建议
[文档改进建议]


## 工具权限控制

### 权限级别

```mermaid
flowchart TD
    A[完全权限] --> B[读写执行]
    A --> C[只读]
    A --> D[无权限]

    B --> E["Read, Write, Edit, Bash"]
    C --> F["Read, Grep, Glob"]
    D --> G["无工具"]

配置方式

# 在 agent 文件中
tools:
  allowed:
    - Read
    - Grep
    - Glob
    - Bash  # 允许的命令可能有限制
  denied:
    - Write  # 禁止写入
    - Edit   # 禁止编辑

安全最佳实践

  1. 最小权限原则 - 只授予必要的工具
  2. 沙箱执行 - 敏感操作在沙箱中运行
  3. 审查日志 - 记录所有子代理操作
  4. 超时限制 - 防止无限执行

多代理协作模式

模式 1：流水线模式

sequenceDiagram
    participant O as Orchestrator
    participant P as Planner
    participant A as Architect
    participant I as Implementer
    participant R as Reviewer

    O->>P: 需求分析
    P->>A: 设计方案
    A->>I: 实现计划
    I->>R: 代码审查
    R->>O: 最终结果

适用场景：大型功能开发

模式 2：并行审查模式

sequenceDiagram
    participant O as Orchestrator
    participant R1 as Code Reviewer
    participant R2 as Security Reviewer
    participant R3 as Performance Reviewer

    O->>R1: 代码审查
    O->>R2: 安全审查
    O->>R3: 性能审查

    par 并行执行
        R1-->>O: 质量报告
        R2-->>O: 安全报告
        R3-->>O: 性能报告
    end

    O->>O: 汇总结果

适用场景：代码审查、发布前检查

模式 3：迭代检索模式

当子代理缺少主代理的语义上下文时，使用迭代检索：

sequenceDiagram
    participant O as Orchestrator
    participant S as Subagent

    O->>S: 任务请求
    S->>O: 初步结果

    Note over O: 评估结果是否充分

    alt 需要更多信息
        O->>S: 追问 + 上下文
        S->>O: 补充结果
    else 结果充分
        O->>O: 接受结果
    end

关键规则：

  • 传递目标上下文，不只是查询
  • 最多 3 轮迭代
  • 每轮返回明确结论

模式 4：探索 vs 执行

flowchart LR
    subgraph 探索型
        A[Explorer] --> B[收集信息]
        B --> C[返回摘要]
    end

    subgraph 执行型
        D[Executor] --> E[修改代码]
        E --> F[返回结果]
    end

    G[Orchestrator] --> A
    G --> D

选择依据：

  • 探索型：只读操作、信息收集
  • 执行型：写操作、代码修改

协作模式时序图

以下是一个完整的多代理协作流程：

sequenceDiagram
    participant U as 用户
    participant O as Orchestrator
    participant E as Explorer
    participant P as Planner
    participant I as Implementer
    participant R as Reviewer

    U->>O: 实现用户认证功能

    Note over O: Phase 1: RESEARCH
    O->>E: 探索现有代码结构
    E->>O: research-summary.md

    Note over O: Phase 2: PLAN
    O->>P: 创建实现计划
    P->>O: plan.md

    Note over O: Phase 3: IMPLEMENT
    O->>I: 执行计划
    I->>O: 代码更改

    Note over O: Phase 4: REVIEW
    O->>R: 代码审查
    R->>O: review-comments.md

    Note over O: Phase 5: VERIFY
    O->>I: 修复审查问题
    I->>O: 最终代码

    O->>U: 完成

使用 Subagents

在对话中调用

# 显式委托
使用 code-reviewer 审查 src/auth.ts

# 并行委托
同时运行 code-reviewer 和 security-reviewer 审查这个 PR

# 流水线模式
按顺序运行: planner -> architect -> implementer

通过 Skill 触发

在 Skill 中定义自动委托：

# 复杂开发流程

## 触发条件
- 用户要求实现新功能
- 预计涉及 >5 个文件

## 工作流程
1. 委托 planner 创建计划
2. 委托 architect 审查设计
3. 委托 executor 实现代码
4. 委托 reviewer 审查质量

最佳实践

1. 选择正确的模型

任务类型 推荐模型 原因
文件搜索 Haiku 快速、便宜
简单编辑 Haiku 单文件操作
多文件实现 Sonnet 平衡性能与成本
架构决策 Opus 需要深层推理
安全审查 Opus 不能遗漏漏洞

2. 限制并发数

建议同时运行 ≤4 个子代理
原因：
- 避免资源竞争
- 保持主代理上下文清晰
- 降低 API 调用成本

3. 明确输出格式

✅ 好的输出定义
输出格式：
- 文件列表
- 具体更改
- 验证步骤

❌ 模糊的输出定义
输出：审查结果

小结

关键要点

  • ✅ Subagents 实现并行执行和专业分工
  • ✅ 通过工具权限控制限制子代理能力
  • ✅ 选择合适的模型优化成本
  • ✅ 使用迭代检索处理上下文缺失
  • ✅ 定义清晰的输出格式

系列导航：