多 Agent 角色协同

单 Agent 模式（一个 AI 写代码 + 测试 + 文档 + Review）很快会遇到两个瓶颈：

• 上下文污染：PRD、架构、测试用例都塞进同一上下文，AI 抓不住重点
• 角色越界：让同一个 AI 既当产品又当架构师又当 QA，结果哪边都不专业

多 Agent 协同是上下文工程在团队维度的延伸——把"一个 AI 干所有事"升级为"专业分工"。

单 Agent vs 多 Agent

单 Agent 模式：       1 人 ──▶ 1 个 AI ──▶ 1 个结果
                          │
                  上下文污染 / 角色越界
                          │
                          ▼
多 Agent 模式：       1 个团队 ──▶ N 个专业 AI ──▶ N 个交付物
                          │
                  上下文分桶 / 契约交接

三大核心价值

价值	说明
专注度提升	每个 Agent 只关心自己领域的上下文
交付物可控	每个 Agent 产出明确的契约文档（PRD、API 契约、设计 Token）
流程可追溯	上下游通过契约交接，类似代码评审的标准流水线

单角色 vs 多角色的 Prompt 配置详见 Prompt 工程。

常见角色拆分

角色	职责	主要消费的上下文	主要产出
产品 Agent	需求分析、PRD、用户故事	业务背景、用户调研、竞品	prd.md、用户故事
架构 Agent	技术选型、模块划分、接口设计	系统上下文、约束、非功能需求	architecture.md、API 契约
设计 Agent	交互稿、设计 Token、组件规格	PRD、设计系统、品牌规范	设计稿、组件 spec
开发 Agent	编码实现、自测	agents.md、API 契约、组件库	业务代码 + 单元测试
测试 Agent	测试设计、覆盖率分析	PRD、代码、风险点	测试用例、缺陷报告
Review Agent	代码评审、规范、安全审计	agents.md、架构文档、安全规范	Review 评论、修复建议
运维 Agent	部署脚本、监控、故障排查	架构文档、SLA、运维手册	IaC、Runbook

团队规模小（≤5 人）时，可以一人扮演多个 Agent 角色；规模大（10+ 人）时，每个 Agent 角色通常对应一个专业子团队或专项 Agent 流水线。

协同工作流示例

       产品 Agent              架构 Agent              设计 Agent
         │                       │                       │
  业务诉求 ──▶ PRD/User Story ──▶ 技术方案 ──▶ 交互/视觉规格
                                         │
                                         ▼
       开发 Agent ◀── API契约/组件规格 ── 测试 Agent
         │                                 │
     业务代码 + 单测                    测试用例 + 缺陷
         │                                 │
         └───────────▶ Review Agent ◀──────┘
                              │
                         合并 / 修改
                              │
                              ▼
                       运维 Agent（部署 / 监控）

关键点：每个角色只加载自己需要的上下文，通过契约文档交接，而不是把全部上下文传给所有人。

上下文"分桶"策略

每个 Agent 角色维护自己的上下文桶：

.context/
  product/
    prd.md            # 产品 Agent 写
    glossary.md       # 业务术语
  architecture/
    arch.md           # 架构 Agent 写
    api-contract.md   # API 契约
  design/
    tokens.md         # 设计 Token
    components.md     # 组件规格
  coding/
    agents.md         # 开发 Agent 主要读
  testing/
    test-plan.md      # 测试 Agent 写
  review/
    checklist.md      # Review Agent 主要读

• 开发 Agent 只读 coding/ + 必要的 architecture/
• Review Agent 只读 review/ + coding/agents.md
• 测试 Agent 只读 testing/ + architecture/
• 禁止把所有上下文塞进任何单一 Agent

主 Agent vs 子 Agent：调度原则

多 Agent 协作是一个主 Agent 编排多个子 Agent的主从模式。理解什么时候主 Agent 自己干、什么时候派生子 Agent，是高效协同的关键。

三条决策原则

原则	主 Agent 处理	派生子 Agent 处理
复杂度	简单、一步到位的任务	复杂、需要拆分的任务
专业性	通用编码、对话	高度专业化的工作（测试、安全审计、性能分析）
上下文隔离	不消耗大量上下文	会大量消耗上下文（避免主 Agent 记忆被撑爆）

角色定位

┌─────────────────────────────────────────────┐
│               主 Agent（编排者）              │
│  - 理解全局目标，拆解任务                     │
│  - 决定"自己干"还是"派生子 Agent"            │
│  - 汇总子 Agent 结果，做最终决策              │
│  - 与用户保持对话，确认方向                   │
└──────┬──────────────┬──────────────┬────────┘
       │              │              │
       ▼              ▼              ▼
   ┌────────┐    ┌────────┐    ┌────────┐
   │子 Agent│    │子 Agent│    │子 Agent│
   │(产品)   │    │(开发)   │    │(测试)   │
   │独立上下文│    │独立上下文│    │独立上下文│
   │单一职责  │    │单一职责  │    │单一职责  │
   │返回结果  │    │返回结果  │    │返回结果  │
   └────────┘    └────────┘    └────────┘

维度	主 Agent	子 Agent
职责	编排、决策、汇总	执行专项任务
上下文	全局视角	领域上下文（分桶后的）
与用户交互	是	否（只返回结果给主 Agent）
生命周期	贯穿整个任务	任务完成即销毁
典型场景	拆任务、定方案、做取舍	写 PRD、写代码、写测试、做审查

子 Agent 效率最高的 3 类场景

1. 并行处理复杂任务

示例：开发一个电商 demo
       │
       ├─▶ 前端子 Agent（商品列表、购物车 UI）
       └─▶ 后端子 Agent（订单 API、支付回调）
       │
       并行启动，各自完成后再汇总

2. 长周期、多阶段项目（事件驱动）

示例：产品上线流水线
       │
   产品 Agent 完成 PRD
       │ (事件: prd_done)
       ▼
   架构 Agent 开始技术设计
       │ (事件: arch_done)
       ▼
   开发 Agent 开始实现
       │ (事件: code_done)
       ▼
   Review Agent 开始审查

3. 需要"专家"深度介入

示例：安全审计
       │
   开发 Agent 写出代码
       │
       ▼
   安全子 Agent（security-auditor）
       - 扫描 OWASP Top 10 风险
       - 检查依赖漏洞
       - 评估权限与认证
       │
       ▼
   输出深度审计报告

调度要点

串行 vs 并行：看依赖关系

子任务 B 依赖子任务 A 的输出 → 串行
子任务 B 和 C 互不依赖       → 并行

子 Agent 的边界契约：

子 Agent 只做、只返回，不与用户直接对话：

• 输入：明确的任务描述 + 必要的上下文
• 输出：结构化的结果（代码、文档、报告）
• 不做：不做跨角色的决策、不与用户交互

主 Agent 始终为结果负责：

子 Agent 的输出不是最终产物，主 Agent 必须汇总、验证、决策：

子 Agent 返回代码
       │
       ▼
主 Agent 检查：
├── 是否符合 agents.md 规范？
├── 是否满足任务要求？
├── 是否需要与其他子 Agent 的输出整合？
└── 是否需要让另一个子 Agent 验证（如 Review Agent）？
       │
       ▼
汇总后交给用户 / 进入下一步

记住：多 Agent 的瓶颈不在"Agent 不够多"，而在"调度不合理"。能并行就不串行，能独立上下文就不共享，主 Agent 始终为最终结果负责。

工具落地的选择

场景	推荐做法
小改动（< 1 天）	单一 Agent 单轮搞定
中等特性（1-5 天）	产品 Agent 出 PRD → 开发 Agent 实现 → Review Agent 审核
大型项目（> 1 周）	完整流水线，产品/架构/设计/开发/测试/Review/运维 全角色参与
跨团队协作	用"交付物清单"代替"上下文传递"，每个角色只看自己桶里的内容

核心原则：上下文按角色分桶，交付物按契约交接。多 Agent 不是让 AI 更忙，而是让每个 AI 更专注、更专业。

实战建议

DO

• 每个 Agent 角色维护独立的 .context/<role>/ 目录
• 通过契约文档交接，不用"全量上下文"
• 大项目强制拆分角色，小改动可以合并
• 定期回顾：哪些 Agent 重复犯同样的错？是否需要调整上下文桶
• 把多 Agent 流水线写入团队 onboarding 文档

DON'T

• 让所有 Agent 共享同一份"巨型 agents.md"
• 跨角色直接传递"对话历史"（容易污染）
• 让一个 Agent 兼任过多角色（容易越界）
• 跳过架构/设计环节直接让开发 Agent 实现复杂功能
• Review Agent 没有 checklist，输出过于主观

总结

多 Agent 协同不是"分而治之"的炫技，而是上下文工程的必然结果：

• 单 Agent 上下文超过临界点 → 必须分桶
• 交付物复杂度上升 → 必须拆角色
• 团队规模扩大 → 必须用契约代替对话

一个团队用好多 Agent 的标志：每个 Agent 产出的文档，人不看也能独立决策。