本文为「AI 辅助编程实战指南」第9篇，完整系列持续更新中。

前言

到 2026 年，AI 编程工具已经从”代码补全”进化到了”自主开发”。Claude Code 的 Agent 模式、Cursor 的 Background Agent、GitHub Copilot 的 Agent Mode——这些工具不再只是被动回答问题，而是能主动读取代码库、分析问题、编写代码、运行测试、修复错误。

但一个 Agent 再强，也有瓶颈：上下文窗口有限、单线程工作、容易被锚定效应带偏。真正的高效开发方式，是让多个 Agent 各司其职、协同工作——就像你管理一个开发团队一样。

本篇学完你将掌握：

  • 单智能体专精和多智能体协同的区别与适用场景
  • Claude Code Subagent 的完整配置和使用方法
  • Agent Team（智能体团队）的编排架构和最佳实践
  • Cursor 多智能体工作流的实操方法
  • Harness 工程：如何系统性地驯服和管控智能体
  • 从单 Agent 到多 Agent 的渐进式升级路径

一、为什么单智能体不够用

在前8篇中，我们讨论的所有技巧——Prompt 工程、任务拆解、上下文管理、记忆系统——本质上都是在优化单个 Agent 的工作效率。但当项目复杂度上升到一定程度，单 Agent 模式会遇到三个结构性瓶颈。

1.1 三个瓶颈

瓶颈 表现 根本原因
上下文天花板 一个 Agent 只能看到一个上下文窗口，大型项目的代码库远超窗口容量 物理限制，无法突破
单线程工作 前端改完改后端，后端改完改测试——所有任务串行执行 架构限制
锚定效应 Agent 找到一个”可行方案”后倾向于深挖，忽略其他可能更好的路径 推理机制限制

1.2 一个典型场景

假设你在开发一个全栈功能：前端新增一个商品批量导入页面，后端实现导入 API 和校验逻辑，数据库需要新增导入记录表，还要补充测试。

用单 Agent 模式：

1
2
3
# 串行执行，每步等前一步完成
Agent：设计数据模型 → 实现后端 API → 实现前端页面 → 写测试
耗时：4 个阶段串行 × 每阶段 30 分钟 = 2 小时

用多 Agent 协同：

1
2
3
4
5
6
# 并行执行，各 Agent 独立工作
Agent-架构师：设计数据模型和 API 接口规范
Agent-后端：实现导入 API（等架构师完成后开始）
Agent-前端：实现导入页面（等架构师完成后开始，与后端并行）
Agent-测试：编写测试用例（等后端和前端完成后开始）
耗时：架构 30 分钟 + max(后端, 前端) 30 分钟 + 测试 30 分钟 = 1.5 小时

更重要的是，多 Agent 模式不仅更快，还更容易产出高质量结果——每个 Agent 专注于自己擅长的领域，而不是一个”全栈打杂”。

二、两种协同模式：Subagent vs Agent Team

2026 年的 AI 编程工具提供了两种截然不同的多智能体协同方式。选择哪种，取决于你的任务是否需要 Agent 之间互相沟通。

2.1 模式对比

维度 Subagent（子智能体） Agent Team（智能体团队）
通信方式 只向主 Agent 汇报结果，互相之间不通信 队友之间可以直接发消息、互相挑战观点
协调方式 主 Agent 统一管理所有工作 共享任务列表，队友自行认领
上下文 独立上下文窗口，结果汇总回主 Agent 独立上下文窗口，完全独立运行
适合场景 专注的执行任务——只需要结果 需要讨论、挑战和协作的复杂任务
Token 消耗 较低——结果被摘要返回主上下文 较高——每个队友都是独立的 Claude 实例
工具支持 Claude Code（原生）、Qoder Claude Code（实验性功能）

2.2 选择决策树

1
2
3
4
5
6
7
8
9
你的任务需要多个 AI 互相讨论、挑战对方的结论吗？
├─ 是 → Agent Team
│       例：安全审查（需要互相验证发现）
│       例：架构设计（需要多角度讨论权衡）
│       例：Bug 调查（需要竞争假说互相反驳）
└─ 否 → Subagent
        例：代码审查（只需要审查结果）
        例：文件搜索（只需要搜索结果）
        例：并行实现（只需要各模块的实现代码）

💡 建议：80% 的多智能体场景用 Subagent 就够了。Agent Team 适合真正需要”讨论”的场景——安全审查、架构设计、Bug 调查。对于常规的功能开发，Subagent 的性价比更高。

三、Subagent：专注的”外包专家”

Subagent 是 Claude Code 中最成熟的多智能体机制。你可以把它理解为”外包专家”——主 Agent 遇到特定类型的任务时，委托给专门的 Subagent 处理，Subagent 在自己的上下文窗口中完成工作，只返回结果摘要。

3.1 内置 Subagent

Claude Code 自带几个内置 Subagent，在适当时自动使用：

Subagent 模型 工具权限 用途
Explore Haiku（快速低成本） 只读 搜索和分析代码库
Plan 继承主对话 只读 Plan Mode 下的代码库研究
General-purpose 继承主对话 所有工具 复杂的多步骤任务

当你让 Claude Code “查找所有用了 useState 的组件”时，它可能自动委托给 Explore Subagent——用快速低成本模型完成搜索，把搜索结果摘要返回主对话，不会用搜索过程的大量中间输出来污染你的主上下文。

3.2 创建自定义 Subagent

真正的威力在于创建自己的 Subagent。以下是完整流程：

方式一：通过 /agents 命令（推荐）

在 Claude Code 中运行 /agents，选择 Library → Create new agent，然后选择范围（项目级或用户级）。你可以手动填写配置，也可以让 Claude 帮你生成。

方式二：手动创建文件

在项目目录 .claude/agents/ 或用户目录 ~/.claude/agents/ 中创建 Markdown 文件：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
# .claude/agents/security-reviewer.md
---
name: security-reviewer
description: 安全审查专家。当需要审查代码安全性时使用。
tools: Read, Grep, Glob
model: sonnet
---

你是一名资深安全工程师。审查代码时重点关注：
1. 认证和授权漏洞（越权访问、Token 泄露）
2. 注入攻击（SQL 注入、XSS、命令注入）
3. 敏感数据处理（日志中的密码、硬编码密钥）
4. 依赖安全（已知漏洞版本）

输出格式：
- 严重程度：🔴 高危 / 🟡 中危 / 🟢 低危
- 问题描述
- 受影响文件和行号
- 修复建议

使用方式：

1
2
3
4
5
6
# 方式1：让 Claude 自动判断何时使用
请审查 src/auth/ 目录的安全性。
→ Claude 识别到安全审查任务，自动委托给 security-reviewer

# 方式2：显式指定
使用 security-reviewer 审查 src/auth/ 目录。

3.3 Subagent 的关键配置

配置项 说明 示例值
name 唯一标识符 security-reviewer
description Claude 何时应该委托给它 越具体越好，见下文
tools 允许使用的工具 Read, Grep, Glob（只读）
model 使用的模型 sonnet、haiku、opus
permissionMode 权限模式 plan（只读）、auto（自动）
maxTurns 最大执行轮数 10（防止失控）
memory 持久记忆范围 user、project、local
isolation 隔离模式 worktree（独立 Git 工作树）

description 的写法至关重要——它决定了 Claude 何时自动委托任务给这个 Subagent：

1
2
3
4
5
6
7
# 好的 description：具体、有触发关键词
description: >
  安全审查专家。在代码变更涉及认证、授权、加密、
  用户输入处理时主动使用。也适用于第三方依赖的安全评估。

# 不好的 description：模糊、无触发条件
description: 审查代码

3.4 工具权限控制

Subagent 默认继承主对话的所有工具，但你可以精细控制：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# 只读审查者——不能修改任何文件
---
name: code-reviewer
tools: Read, Grep, Glob
---

# 测试专家——可以执行测试但不能编辑代码
---
name: test-runner
tools: Read, Grep, Glob, Bash
---

# 全能力实现者——继承所有工具
---
name: implementer
# 不指定 tools，默认继承全部
---

⚠️ 注意：isolation: worktree 是一个强大但容易被忽视的配置。设置后，Subagent 会在独立的 Git 工作树中工作——它有自己的代码副本，不会直接影响你的主分支。适合需要大范围代码修改的探索性任务。

3.5 Subagent 的持久记忆

Subagent 也可以有自己的持久记忆，跨会话积累领域经验：

1
2
3
4
5
6
---
name: security-reviewer
description: 安全审查专家
memory: project  # 项目级持久记忆
tools: Read, Grep, Glob
---

启用后，这个 Subagent 会在 ~/.claude/agent-memory/ 中维护自己的笔记——比如”这个项目之前出现过 XX 类型的安全问题””这个团队的代码经常在 YY 地方犯错”。每次调用时，它会带着这些积累的经验来审查代码。

3.6 实战：一个完整的多 Subagent 工作流

以下是一个实际项目中配置的多 Subagent 体系：

1
2
3
4
5
6
.claude/agents/
├── security-reviewer.md   # 安全审查（只读，Sonnet）
├── test-writer.md         # 测试编写（读写，Sonnet）
├── doc-writer.md          # 文档编写（读写，Haiku）
├── db-migrator.md         # 数据库迁移（读写+Worktree隔离，Sonnet）
└── perf-analyzer.md       # 性能分析（只读，Opus）

在一次完整的功能开发中，各 Subagent 按需调用：

1
2
3
4
5
6
1. 主 Agent：设计 API 接口和数据模型
2. 主 Agent：实现业务逻辑
3. test-writer：自动被调用编写测试
4. security-reviewer：自动被调用审查安全性
5. doc-writer：自动被调用更新文档
6. perf-analyzer：按需被调用分析性能

💡 提示：不需要在一次开发中调用所有 Subagent。根据任务类型，只调用需要的——这才是”按需外包”的精髓。日常小修改可能只需要 test-writer，涉及安全的改动才加上 security-reviewer。

四、Agent Team：平行协作的”项目组”

Agent Team 是 Claude Code 的实验性功能，让多个 Claude Code 实例组成团队——一个担任”组长”（Team Lead），其他担任”队友”（Teammates）。与 Subagent 最大的区别是：队友之间可以直接沟通。

4.1 架构总览

1
2
3
4
5
6
7
8
9
10
11
┌──────────────────────────────────────────┐
│            Team Lead（组长）               │
│  接收你的指令 → 拆解任务 → 分配给队友       │
│  ← 汇总队友的发现 → 综合输出               │
└───────┬──────────────┬───────────────┬────┘
        │              │               │
   ┌────▼────┐    ┌────▼────┐    ┌────▼────┐
   │ 队友 A  │    │ 队友 B  │    │ 队友 C  │
   │ 安全审查 │    │ 性能分析 │    │ 测试覆盖 │
   └─────────┘    └─────────┘    └─────────┘
   ←→ 队友之间可以直接发消息、互相挑战观点

4.2 启用和启动

Agent Team 默认关闭，需要手动启用：

1
2
3
4
5
6
// .claude/settings.json
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

启用后，用自然语言描述任务和团队结构即可：

1
2
3
4
5
我在设计一个 CLI 工具，用于追踪代码库中的 TODO 注释。
创建一个 Agent Team，从不同角度探索：
- 一个队友负责 UX 设计
- 一个队友负责技术架构
- 一个队友扮演"魔鬼代言人"，挑战所有假设

4.3 显示模式

Agent Team 支持两种显示模式：

模式 说明 适合场景
In-process 所有队友在主终端内运行，Shift+Down 切换队友 任何终端，无需额外配置
Split panes 每个队友一个独立窗格，可同时看到所有人的输出 使用 tmux 或 iTerm2 
1
2
3
4
5
// 强制使用 in-process 模式
// ~/.claude/settings.json
{
  "teammateMode": "in-process"
}

4.4 任务协调机制

Agent Team 通过共享任务列表协调工作：

1
2
3
4
5
6
任务列表状态：
├── ✅ [完成] 分析现有 TODO 解析库的优劣（队友A）
├── 🔄 [进行中] 设计 AST 遍历算法（队友B）
├── ⏳ [待认领] 编写 CLI 参数解析模块
├── ⏳ [待认领] 设计输出格式（依赖：AST 遍历算法完成）
└── ⏳ [待认领] 性能基准测试（依赖：所有模块完成）

任务有三种状态：pending（待认领）→ in progress（进行中）→ completed（已完成）。任务还支持依赖关系——有前置任务未完成的任务不能被认领。

队友完成一个任务后，会自动认领下一个未被分配、未被阻塞的任务。你也可以让组长显式分配：

1
把"编写 CLI 参数解析模块"任务分配给队友 B。

4.5 最佳使用场景

场景一：竞争假说的 Bug 调查

这是 Agent Team 最有价值的场景——多个队友各提出一个假设，然后互相辩论反驳：

1
2
3
4
用户报告应用在发送一条消息后就断开了，而不是保持连接。
创建 5 个队友调查不同假设。让他们互相交流，
尝试反驳对方的理论，像科学辩论一样。
最终把达成的共识更新到 findings.md。

为什么这比单 Agent 好？单 Agent 调查 Bug 时容易”锚定”在第一个看似合理的理论上，停止深入调查。多个独立调查者互相反驳，存活下来的理论才更可能是真正的根因。

场景二：多维度并行代码审查

1
2
3
4
5
创建 Agent Team 审查 PR #142。生成三个审查者：
- 一个聚焦安全影响
- 一个检查性能影响
- 一个验证测试覆盖率
各自审查后汇总发现。

每个审查者从同一个 PR 出发，但用不同的”滤镜”分析。组长最后综合三方发现。

场景三：跨层协调的功能开发

1
2
3
4
5
创建 Agent Team 开发商品批量导入功能：
- 前端队友：实现导入页面和进度条组件
- 后端队友：实现导入 API 和校验逻辑
- 测试队友：等前后端完成后编写集成测试
每个队友用 Sonnet 模型。要求所有队友在实现前先提交方案让你审核。

4.6 关键注意事项

注意事项 说明
Token 消耗 每个队友都是独立实例，Token 消耗线性增长。3 个队友 ≈ 4 倍单会话消耗（含组长）
团队规模 建议 3-5 个队友。超过 5 个协调成本显著增加，收益递减
任务粒度 每个队友 5-6 个任务最理想。太小的任务协调开销大于收益
实验性功能 会话恢复、任务协调、关闭行为都有已知限制，生产环境慎用
组长也会动手 有时组长会自己动手而不是等队友完成，需要明确指示”等队友完成后再汇总”

⚠️ 注意：Agent Team 目前是实验性功能。会话中断后无法恢复，关闭行为也不够优雅。对于生产环境的日常开发，优先使用 Subagent 模式——更成熟、更可控。

五、Cursor 的多智能体工作流

Cursor 2.0 引入了自己的多智能体体系，思路与 Claude Code 有所不同——更强调并行执行和结果择优。

5.1 Background Agent（后台智能体）

Cursor 的 Background Agent 可以在后台独立完成任务，不阻塞你的当前工作：

1
2
# 在 Cursor 中
Agent Mode → 右键 → Run in Background

适用场景：

  • 让 Agent 在后台跑一整套测试修复流程，你继续写其他功能
  • 同时启动多个 Background Agent 处理不同模块
  • Agent 完成后通知你审查结果

5.2 多 Agent 并行 + 结果择优

Cursor 2.0 最有特色的功能：让多个模型同时解决同一个问题，你选择最好的结果。

1
2
3
4
# 在 Cursor 中
选中一段代码 → 右键 → Generate with multiple models
→ 选择 2-3 个模型并行生成
→ 对比结果，选择最优方案

这种方式特别适合：

  • 复杂算法实现：不同模型可能给出不同的算法思路
  • 重构方案：多个方案对比，选出最优雅的重构路径
  • 边界情况处理：不同模型可能关注不同的边界 case

5.3 Cursor 与 Claude Code 的协同策略

需求 推荐工具 原因
日常编码 Cursor Agent Mode 集成 IDE 体验好，实时反馈
安全审查 Claude Code Subagent 专业化 Subagent，持久记忆
并行探索方案 Cursor 多模型生成 快速对比，直观选择
长时间后台任务 Cursor Background Agent 不阻塞主工作流
跨模块协作 Claude Code Agent Team 队友间可通信，适合复杂协调
自动化流水线 Claude Code CLI --agent 适合 CI/CD 集成

六、Harness 工程：驯服你的智能体

多智能体协同的效率高，但风险也大——Agent 可能擅自修改关键代码、引入安全漏洞、或者做出你意想不到的”优化”。Harness（驾驭）工程就是系统性地管控 Agent 行为的方法论。

6.1 四层管控体系

1
2
3
4
5
6
7
8
9
10
11
12
13
┌───────────────────────────────────────────┐
│ 第1层：规则文件（CLAUDE.md / .cursorrules）   │ ← 行为边界
│ 定义编码规范、安全红线、不可修改的模块         │
├───────────────────────────────────────────┤
│ 第2层：工具权限（Subagent tools 配置）         │ ← 能力边界
│ 控制 Agent 能读什么、写什么、执行什么          │
├───────────────────────────────────────────┤
│ 第3层：审批机制（Plan Mode + 方案审核）        │ ← 决策边界
│ 先出方案后执行，人工确认后才动手              │
├───────────────────────────────────────────┤
│ 第4层：隔离机制（Worktree + 沙箱）            │ ← 影响边界
│ 在隔离环境中操作，不影响主代码库              │
└───────────────────────────────────────────┘

6.2 各层实操配置

第1层：规则文件

在 CLAUDE.md 中定义不可逾越的红线（详见第5篇和第8篇）：

1
2
3
4
5
6
7
8
9
## 不可修改的模块
- src/auth/ — 认证模块（历史安全漏洞多）
- src/middleware/security.py — 安全中间件
- .github/ — CI/CD 配置

## 安全红线
- 禁止硬编码任何密钥、Token 或凭证
- 所有用户输入必须经过校验和清洗
- 数据库操作禁止字符串拼接

第2层：工具权限

为不同 Subagent 配置最小权限：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
# 只读审查者——绝对不能修改代码
---
name: reviewer
tools: Read, Grep, Glob
permissionMode: plan
---

# 测试编写者——可以创建测试文件，但不能修改业务代码
---
name: test-writer
tools: Read, Grep, Glob, Write, Edit
disallowedTools: Bash  # 禁止执行命令
---

# 实现者——完整的读写权限，但禁止危险命令
---
name: implementer
permissionMode: auto  # 自动模式，但受保护目录限制
---

第3层：审批机制

对高风险操作要求先出方案：

1
2
3
# 对 Agent Team 中的队友启用审批
Spawn a teammate to refactor the authentication module.
Require plan approval before they make any changes.

队友会在 Plan Mode 中完成方案设计，提交给组长审核。如果方案被拒绝，队友会根据反馈修改方案后重新提交。

你还可以在 Prompt 中设定审批标准：

1
只批准包含测试覆盖率的方案。拒绝任何修改数据库 Schema 的方案。

第4层：隔离机制

对探索性任务使用 Git 工作树隔离：

1
2
3
4
5
6
---
name: explorer
description: 探索性重构代理
isolation: worktree  # 在独立 Git 工作树中工作
tools: Read, Write, Edit, Bash
---

设置 isolation: worktree 后，Subagent 会在临时的 Git 工作树中操作——它有自己的代码副本，修改不会影响主分支。如果结果满意，你手动合并；不满意，直接丢弃工作树。

6.3 质量门控：Hooks

Claude Code 的 Hooks 机制可以在 Agent 生命周期的关键节点插入检查：

Hook 触发时机 用途
TeammateIdle 队友即将空闲时 检查队友是否真正完成了工作
TaskCompleted 任务即将标记完成时 验证测试是否通过
TaskCreated 任务即将创建时 防止创建不合理的任务 
1
2
3
4
5
6
7
8
9
10
11
// .claude/hooks.json — 任务完成时自动运行测试
{
  "hooks": {
    "TaskCompleted": [
      {
        "command": "npm test",
        "description": "验证测试通过后才能标记任务完成"
      }
    ]
  }
}

6.4 从单 Agent 到多 Agent 的渐进升级

不需要一步到位。按以下路径逐步升级：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
阶段1：单 Agent + 规则文件
  → 掌握 Prompt 工程 + 上下文管理（第3-7篇）
  → 适合：小型项目、日常维护

阶段2：单 Agent + Subagent 自动委托
  → 配置 2-3 个常用 Subagent（审查、测试、文档）
  → 适合：中型项目、需要代码审查的场景

阶段3：多 Subagent 协同 + 工作树隔离
  → 完整配置 5+ Subagent，使用 worktree 隔离
  → 适合：大型项目、团队协作

阶段4：Agent Team + Hooks 质量门控
  → 启用 Agent Team，配合 Hooks 自动验证
  → 适合：复杂架构决策、安全审查、Bug 调查

💡 建议：大多数团队停留在阶段 2 就能获得很好的投入产出比。阶段 3-4 需要更多的配置维护成本和 Token 预算，只建议在项目复杂度和团队规模确实需要时再升级。

七、踩坑记录：Agent Team 中三个队友同时修改了同一个文件

现象：
启用 Agent Team 开发一个全栈功能。创建了三个队友：前端、后端和数据库。三个队友并行工作，各自实现自己负责的部分。结果三人都需要修改 src/types/index.ts（类型定义文件）——前端添加了前端组件的类型，后端添加了 API 响应的类型，数据库添加了 ORM 模型的类型。三人的修改互不兼容，合并时冲突了一地。

原因：

  1. Agent Team 的队友之间默认不共享文件变更——每个队友看到的是 spawn 时的代码快照
  2. 类型定义文件是”跨层共享”的资源，三个队友都有修改需求
  3. 任务分配时没有考虑到文件冲突风险

解决方案：

  1. 先手动合并三方的类型定义（解决了冲突）
  2. 将 src/types/ 提取为独立的 Phase 0 任务，由组长先完成
  3. 后续队友基于已确定的类型定义工作，不再修改类型文件

改进后的任务分配：

1
2
3
4
5
6
7
8
# 改进后的 Agent Team Prompt
创建 Agent Team 开发商品管理模块。注意：
1. 所有类型定义由你（组长）先完成并提交
2. 前端队友只修改 src/components/ 目录
3. 后端队友只修改 src/api/ 和 src/services/ 目录
4. 数据库队友只修改 src/db/ 目录
5. 禁止任何队友修改 src/types/ 目录
各队友完成后，由你汇总并检查接口兼容性。

避坑建议：

  • 多 Agent 并行时，任务分配必须考虑文件边界——确保不同队友不会修改同一个文件
  • 共享资源（类型定义、配置文件、公共工具函数）应该由组长或一个专门的队友预先完成
  • 如果任务天然涉及同文件修改（如重构），不要用 Agent Team，改用 Subagent 串行处理
  • Agent Team 的价值在于独立任务的并行化，不在于让多个人”抢着写同一段代码”
  • 在使用 Agent Team 前，先花 5 分钟想一下”哪些文件可能被多人修改”，在 Prompt 中显式划清边界

总结与回顾

核心要点 关键结论
协同的必要性 单 Agent 有上下文天花板、单线程和锚定效应三大瓶颈
两种模式 Subagent（只汇报结果）vs Agent Team（互相沟通），80% 场景用 Subagent
Subagent 核心 description 写清楚触发条件，tools 配最小权限，高风险用 plan mode
Agent Team 核心 适合需要讨论/辩论的场景，注意文件边界划分，Token 消耗线性增长
Cursor 多智能体 Background Agent 后台执行，多模型生成择优选择
Harness 四层管控 规则文件 → 工具权限 → 审批机制 → 隔离机制，逐层收紧
渐进升级 单 Agent → Subagent 委托 → 多 Subagent → Agent Team，按需升级
核心原则 多 Agent 的价值在于”专精+并行”，不在于”人多力量大”

延伸阅读

本文为「AI 辅助编程实战指南」第9篇，完整系列持续更新中。