多 Agent 协作流水线——从单打独斗到团队作战

核心论点：单个 Agent 擅长写代码，但不会审查自己的代码、不会给自己写测试、不会从架构角度审视自己的设计。把编码任务拆成多个角色，让 Agent 各司其职，质量提升远超"多调几轮"。

单 Agent 的天花板

用 Craft 模式让 AI 写一个功能，它会很认真地写——但有些问题它绝对不会发现：

AI 写的代码： ✅ 功能正确——能跑 ❌ 把所有逻辑写在一个 200 行函数里——但你项目的规范是 service 层拆分 ❌ 没写测试——因为它以为"写完代码"就是完成任务 ❌ 数据库查询 N+1——功能正确但性能有问题 ❌ 异常处理不一致——有的吞异常，有的裸抛

这些问题不是 AI"不会"，而是单 Agent 模式下，没有角色负责检查这些问题。就像一个人写代码——他自己不会发现自己拼错变量名，需要 Code Review。

为什么不直接让一个 Agent 做完所有事？

看完上面的天花板，自然会问：把 5 个角色的职责全写到一个 Agent 的 prompt 里，不就解决了吗？

答案：不行。三个根本原因。

原因一：视角盲区无法消除

让一个 Agent 同时扮演架构师、coder、测试、审查员——等于让一个人同时当运动员和裁判。心理上不可能，AI 也一样。

实际表现：

• 写了 N+1 查询 → 同一个 Agent 扮演的"reviewer"视角大概率也发现不了，因为它刚从"coder"视角看过同一段代码
• 没写测试 → “test-generator"视角不会主动跳出来补，因为任务的主要目标是"实现功能”
• 把所有逻辑写进一个 500 行函数 → "architect"视角被"coder"视角压制——代码已经写出来了，它倾向于合理化现有实现

原因二：Prompt 冲突导致行为不可预测

5 个角色的约束是互相矛盾的：

塞在一起的结果是平庸——每个角色维度都做 60 分，没有一个是 90 分。就像一个五项全能运动员，每项都还行，但没一项能进决赛。

原因三：上下文污染

流水线每个阶段有独立上下文：

architecture-designer：需求文档 + 架构规范 ↓ （只传设计文档，不传需求） python-coder：设计文档 + 依赖文件 ↓ （只传代码，不传设计意图） code-reviewer：实现代码 + 规范

独立上下文的巧妙之处：reviewer 看不到设计意图，只能按客观标准审查。如果 reviewer 看到了"为什么这么设计"，就容易原谅实现偏差。

合并成一个 Agent 后，所有上下文混在一起——reviewer 看到了设计意图就开了"后门"，coder 看到了审查标准反而束手束脚写出过度防御的代码。

什么时候"单 Agent 全能"是合理的？

两种场景：

1. 原型验证 / PoC——速度优先，质量其次。一个 Agent 快速出结果比走完整流水线更快
2. 极小改动——改一行配置、加一个字段，不需要分工

这两种正好对应下文"用法 2：精简流水线"——不是所有情况都需要完整流水线，但所有情况也不需要一个 Agent 扮演所有角色。

多 Agent 流水线的设计思路

把编码过程拆成独立角色，每个角色只做自己擅长的事。关键不是"多调几次 AI"，而是上下文隔离——每个阶段只看到上一个阶段的输出，不携带上游信息：

这不是"多调几次 AI"的简单叠加，而是分工 + 上下文隔离带来的质量跃迁。

五个核心 Agent 的职责边界

你们项目已配置的 Agent（.codebuddy/agents/）：

除了这五个核心 Agent，还有api-designer（API 接口设计）和database-designer（数据库表结构设计）两个可选 Agent。它们通常插入在 architecture-designer 和 python-coder 之间，用于新模块的 API 契约和数据模型设计。详见 API 与数据库设计篇。

architecture-designer：出设计，不出代码

输入：功能需求 输出：模块划分、接口定义、数据流、调用关系 不做：写具体实现代码

什么时候调用：

• 新模块/新功能（不知道文件怎么拆）
• 涉及两个以上模块的改造（需要明确模块间契约）
• 技术选型（向量库选 Milvus 还是 Chroma？）

真实案例：退款确认功能——输入一句需求，architecture-designer 拆出 4 个模块（退款申请/订单验证/付款回调/状态同步），定义退款状态机（申请→审批→退款中→已完成/已拒绝）和各模块间异步消息契约。如果不先出设计，coder 大概率用一个 500 行的 refund_service.py 处理所有事——发邮件、调支付接口、更新订单状态全塞进去，后面加一个退款原因字段就崩。

python-coder：实现，不做决策

输入：设计文档 + 相关依赖文件（@ 引用） 输出：按设计实现的可运行代码 不做：自行决定模块拆分、技术选型、接口定义

关键约束：coder 必须拿到 design 之后再动手。如果直接丢需求给 coder——“写个 A/B 实验系统”——它会同时做设计和实现，质量不可控。

调用方式：关键是带上设计文档作为上下文——没有设计文档，coder 会同时做设计和实现，质量不可控。将 architecture-designer 输出的设计文档通过 @ 引用喂给 coder，让它只做填空。

test-generator：补测试，不改功能代码

输入：已实现的代码文件 输出：单元测试 + 集成测试（pytest 格式） 不做：修改功能代码（除非发现明显的边界 bug）

什么时候调用：

• 每个新模块写完时
• 每次重构后（确保行为不变）
• CI 覆盖率低于目标值时

真实案例：

@ …/experiment_service.py 给 assign() 和 record() 写单元测试，覆盖： - 正常分流（A/B 概率均等） - 边界：同一 user 多次 assign 返回相同 variant - 异常：指标记录时实验已关闭 - 并发：两个请求同时 assign

test-generator 经常能发现 coder 没处理的边界情况——比如 user_id 为 None、实验状态异常等。

code-reviewer：审查，不改代码。

输入：已实现的代码文件 输出：审查报告（问题分级 + 修改建议） 不做：自动修改代码

审查维度：

为什么必须独立审查：coder 自己审查自己的代码，和你不找别人 Code Review 自己合并 PR 一样——心理盲区。同样的代码，换个 Agent 身份再看，能发现完全不同的问题。

performance-optimizer（可选）：专项优化

输入：代码+性能数据（慢查询日志、profile 结果、压测报告） 输出：优化方案 + 改动

只有性能出现问题时才调用。日常开发不需要走这个 Agent。

流水线的三种用法

用法 1：标准新功能（完整流水线）

1. architecture-designer → 出设计 2. 你审核设计 3. python-coder → 按设计实现 4. test-generator → 补测试 5. code-reviewer → 审查 6. 你修复审查发现的问题（或让 coder 修）

耗时：5-8 轮对话，适合中等以上功能。

用法 2：小改动（精简流水线）

1. python-coder → 修改 1-2 个文件 2. code-reviewer → 审查

耗时：2-3 轮对话，适合修 bug、加字段、小重构。

用法 3：问题驱动（反向流水线）

1. code-reviewer → 审查现有代码，给问题清单 2. 你选要修哪些 3. python-coder → 逐一修复 4. test-generator → 补回归测试

适合接手别人的代码或技术债清理。

Team 模式：并行协作

Team 模式是 CodeBuddy 的一种特殊运行模式，不同于 Ask/Craft/Plan 的对话模式。它适用于上面"三种用法"都搞不定的场景——当任务可以并行分解时，用 Team 模式让多个 Agent 实例同时工作，而不是串行跑完整流水线。

如果任务可以并行分解，用 CodeBuddy 的 Team 模式让多个 Agent 同时工作：

任务：同时改造 MCP Server 和 A2A 层的错误处理 Team 创建 → 分配： ├── python-coder-1：改造 mcp_server.py 的错误处理 ├── python-coder-2：改造 a2a_routers.py 的错误处理 └── code-reviewer：审查两者的改动（等 coder 完成后）

Team 模式的优点在于并行——两个 coder 同时改互不影响的文件，总耗时是单 Agent 串行的一半。

踩坑与解法：如果两个并行任务确实都碰了同一个文件（比如一个改order_service.create()的校验逻辑，另一个改它的支付流程），用git worktree给每个 Agent 一个独立的工作目录：

gitworktreeadd../agent-a main# Agent A 的工作区gitworktreeadd../agent-b main# Agent B 的工作区

两个 Agent 各自在自己的 worktree 里改，互不干扰。改完后git merge回主分支——即使有冲突，也是在合并阶段统一处理，而不是两个 Agent 在同一个文件上互相覆盖。

worktree 是 Team 模式的安全垫，不是替代品。Team 模式负责「同时跑多个 Agent」，worktree 负责「让它们不互相踩脚」。

如何选择：Team 模式 vs 编排 Agent

判断标准很简单——看任务之间有没有共享的输出目标：

一个判断捷径：如果两个任务可以给两个不同的人同时做且不互相等——用 Team。如果必须第一个人做完第二个人才能开始——用编排。

编排 Agent：让流水线自己跑

前面三种用法都是你手动调用每个 Agent——先调 architecture-designer，审核设计，再调 coder，再调 test-generator……每步都要你切换。

当你走熟了"用法 1"的标准流水线后，可以创建一个编排 Agent（orchestrator），它的唯一职责是按顺序调度子 Agent：

你：实现退款确认功能 编排 Agent： 1. 调用 architecture-designer → 输出设计文档 2. 展示设计文档，等你确认 3. 调用 python-coder（带设计文档 + 依赖文件） 4. 调用 test-generator（带实现代码） 5. 调用 code-reviewer（带实现代码） 6. 汇总审查报告，指出需要你修复的问题

编排 Agent 的价值不是省掉那几次手动调用，而是：

• 你不会漏步骤——比如写完代码忘了调 test-generator
• 上下文传递不出错——不用每次手动 @ 引用上一个 Agent 的输出
• 审核点自动插入——设计和最终审查这两个关键点，编排 Agent 会停下来等你确认

流水线的维护

Agent 定义文件本身也是一种 Rule——它告诉 AI 在以某个角色身份工作时应该遵守什么约束。所以它的维护和 03 篇讲的 Rules 维护是同一件事。

Agent 定义是.codebuddy/agents/下的 markdown 文件，和 Rules 一样需要维护：

• 每个 Agent 定义里引用相关的 Rules（自动继承规范）
• coder 型 Agent 必须声明"基于现有组件扩展"
• reviewer 型 Agent 必须声明审查维度

什么时候需要更新 Agent 定义：

• 发现某类问题反复出现（比如 coder 又写了 N+1）→ 在 coder Agent 定义里加一条约束
• 项目规范更新（比如换了日志框架）→ 更新对应 Agent 引用的 Rules
• 某个 Agent 的输出质量下降 → 检查它的输入是否受控，必要时加「不做」声明

核心要点

1. 单个 Agent 的能力有天花板——它不会审查自己、不会给自己写测试。多 Agent 流水线用角色分工解决了这个问题。
2. 不要把多个角色合并到一个 Agent 的 prompt 里。视角盲区、Prompt 冲突、上下文污染会让每个角色都做不好，“全能"变"全不能”。
3. 每个 Agent 的输入必须受控。architecture-designer 只拿需求，coder 只拿设计文档，reviewer 只拿代码和规范。输入不受控，上下文隔离就失效了。
4. design → code → test → review 是标准流水线，但不是每次都全跑。小改动用精简版，技术债用反向流水线。
5. Agent 定义需要持续维护——发现反复出现的问题，及时加到对应 Agent 的约束里。
6. Team 模式适用于并行任务——两个无依赖的改动可以同时跑 coder，省一半时间。