核心论点单个 Agent 擅长写代码但不会审查自己的代码、不会给自己写测试、不会从架构角度审视自己的设计。把编码任务拆成多个角色让 Agent 各司其职质量提升远超多调几轮。单 Agent 的天花板用 Craft 模式让 AI 写一个功能它会很认真地写——但有些问题它绝对不会发现AI 写的代码 ✅ 功能正确——能跑 ❌ 把所有逻辑写在一个 200 行函数里——但你项目的规范是 service 层拆分 ❌ 没写测试——因为它以为写完代码就是完成任务 ❌ 数据库查询 N1——功能正确但性能有问题 ❌ 异常处理不一致——有的吞异常有的裸抛这些问题不是 AI不会而是单 Agent 模式下没有角色负责检查这些问题。就像一个人写代码——他自己不会发现自己拼错变量名需要 Code Review。为什么不直接让一个 Agent 做完所有事看完上面的天花板自然会问把 5 个角色的职责全写到一个 Agent 的 prompt 里不就解决了吗答案不行。三个根本原因。原因一视角盲区无法消除让一个 Agent 同时扮演架构师、coder、测试、审查员——等于让一个人同时当运动员和裁判。心理上不可能AI 也一样。实际表现写了 N1 查询 → 同一个 Agent 扮演的reviewer视角大概率也发现不了因为它刚从coder视角看过同一段代码没写测试 → “test-generator视角不会主动跳出来补因为任务的主要目标是实现功能”把所有逻辑写进一个 500 行函数 → architect视角被coder视角压制——代码已经写出来了它倾向于合理化现有实现原因二Prompt 冲突导致行为不可预测5 个角色的约束是互相矛盾的角色核心行为冲突点architecture-designer不出代码只出设计和 coder写代码矛盾python-coder快速实现基于现有组件扩展和 reviewer严格挑刺矛盾test-generator专注边界和异常和 coder专注正常路径矛盾code-reviewer挑刺拒绝妥协和所有角色都矛盾塞在一起的结果是平庸——每个角色维度都做 60 分没有一个是 90 分。就像一个五项全能运动员每项都还行但没一项能进决赛。原因三上下文污染流水线每个阶段有独立上下文architecture-designer需求文档 架构规范 ↓ 只传设计文档不传需求 python-coder设计文档 依赖文件 ↓ 只传代码不传设计意图 code-reviewer实现代码 规范独立上下文的巧妙之处reviewer 看不到设计意图只能按客观标准审查。如果 reviewer 看到了为什么这么设计就容易原谅实现偏差。合并成一个 Agent 后所有上下文混在一起——reviewer 看到了设计意图就开了后门coder 看到了审查标准反而束手束脚写出过度防御的代码。什么时候单 Agent 全能是合理的两种场景原型验证 / PoC——速度优先质量其次。一个 Agent 快速出结果比走完整流水线更快极小改动——改一行配置、加一个字段不需要分工这两种正好对应下文用法 2精简流水线——不是所有情况都需要完整流水线但所有情况也不需要一个 Agent 扮演所有角色。多 Agent 流水线的设计思路把编码过程拆成独立角色每个角色只做自己擅长的事。关键不是多调几次 AI而是上下文隔离——每个阶段只看到上一个阶段的输出不携带上游信息阶段输入输出上下文隔离的价值architecture-designer需求文档 架构规范设计文档不携带实现细节python-coder设计文档 依赖文件实现代码不携带设计争议和备选方案test-generator实现代码 验收标准测试代码不携带实现过程中的妥协code-reviewer实现代码 规范审查报告不携带为什么这么设计的解释performance-optimizer代码 性能数据优化方案不携带功能需求只看性能这不是多调几次 AI的简单叠加而是分工 上下文隔离带来的质量跃迁。五个核心 Agent 的职责边界你们项目已配置的 Agent.codebuddy/agents/除了这五个核心 Agent还有api-designerAPI 接口设计和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 - 异常指标记录时实验已关闭 - 并发两个请求同时 assigntest-generator 经常能发现 coder 没处理的边界情况——比如 user_id 为 None、实验状态异常等。code-reviewer审查不改代码。输入已实现的代码文件 输出审查报告问题分级 修改建议 不做自动修改代码审查维度维度检查什么严重程度代码规范命名、类型注解、日志方式低设计模式是否违反已有架构约定中安全漏洞SQL 注入、未校验输入高性能问题N1 查询、无索引、大循环中复用问题是否有重复实现已有组件中异常处理吞异常、裸抛、不一致高为什么必须独立审查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判断标准很简单——看任务之间有没有共享的输出目标场景用哪个原因同时改mcp_server.py和a2a_routers.py的错误处理Team两个文件互不依赖改完各交各的同时加「退款」和「优惠券叠加」两个功能Team功能独立不碰同一段逻辑实现「退款」功能设计→编码→测试→审查编排后一步依赖前一步的输出改了order_service.py后要更新test_order.py编排test 必须等 code 完才能写一个判断捷径如果两个任务可以给两个不同的人同时做且不互相等——用 Team。如果必须第一个人做完第二个人才能开始——用编排。编排 Agent让流水线自己跑前面三种用法都是你手动调用每个 Agent——先调 architecture-designer审核设计再调 coder再调 test-generator……每步都要你切换。当你走熟了用法 1的标准流水线后可以创建一个编排 Agentorchestrator它的唯一职责是按顺序调度子 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 又写了 N1→ 在 coder Agent 定义里加一条约束项目规范更新比如换了日志框架→ 更新对应 Agent 引用的 Rules某个 Agent 的输出质量下降 → 检查它的输入是否受控必要时加「不做」声明核心要点单个 Agent 的能力有天花板——它不会审查自己、不会给自己写测试。多 Agent 流水线用角色分工解决了这个问题。不要把多个角色合并到一个 Agent 的 prompt 里。视角盲区、Prompt 冲突、上下文污染会让每个角色都做不好“全能变全不能”。每个 Agent 的输入必须受控。architecture-designer 只拿需求coder 只拿设计文档reviewer 只拿代码和规范。输入不受控上下文隔离就失效了。design → code → test → review 是标准流水线但不是每次都全跑。小改动用精简版技术债用反向流水线。Agent 定义需要持续维护——发现反复出现的问题及时加到对应 Agent 的约束里。Team 模式适用于并行任务——两个无依赖的改动可以同时跑 coder省一半时间。