当AI编程工具进化到Claude Code、Codex这类Coding Agent阶段，单智能体的局限在复杂任务中暴露无遗。本文深度拆解多智能体协作的工程化解决方案，从动态子智能体生成规范到受控流水线设计，揭示如何通过角色分工、边界控制与验证机制，让AI真正胜任从功能开发到故障排查的完整工程任务。

过去我们使用 AI 编程工具时，更多是在问：“它会不会写代码？”但到了 Claude Code、Codex 这类 Coding Agent 阶段，问题已经变了。

（md的排版有点问题，如果你不想看又想用，直接把这篇蚊帐交给codex去帮你生成，总结就可以）

它们不只是能生成代码，而是可以读仓库、改文件、跑命令、调试、测试、总结，甚至可以结合 Skills、Subagents、MCP、Hooks、Worktrees 等机制，把一个复杂任务拆成多个连续步骤来完成。

真正的问题不再是：Agent 能不能干活。而是：如何让 Agent 在复杂任务里不迷路、不污染上下文、不反复犯错，并且最终能交付一份可验证的结果。

这就是多智能体协作真正有价值的地方。

一、为什么单一 Agent 做复杂任务容易失控？

在小任务里，一个 Coding Agent 已经足够好用。

比如改一个函数、补一个接口、修一个小 bug、解释一段代码，单 Agent 的效率很高。但一旦任务变复杂，例如做一个完整功能、重构多个模块、排查隐藏 bug、补测试、做性能优化、改前端页面，单 Agent 就会暴露几个问题。

第一，上下文越来越脏。它会不断读取文件、复制日志、分析报错、总结方案。随着信息越来越多，主会话里的有效上下文会被大量中间过程污染。

第二，角色混在一起。同一个 Agent 既负责写代码，又负责测试，又负责审查自己写的东西。这很容易出现“自己证明自己正确”的问题。

第三，长任务后期质量下降。任务一长，Agent 容易忘记最初的约束，也容易把临时尝试当成最终方案。

第四，失败后缺少责任边界。测试失败了，到底是需求理解错了、实现错了、测试环境错了，还是验证方式错了？如果没有角色分工，就很难定位。

第五，最终结果缺少证据。很多 Agent 会说“已经完成”，但没有构建日志、测试结果、截图、运行输出、变更摘要，用户很难判断到底能不能用。

所以，多智能体协作的目标不是制造复杂感，而是把复杂编程任务改造成一个更接近真实工程团队的流程：

有人规划，有人实现，有人测试，有人审查，有人汇总证据。

二、多智能体协作的核心思想

这套方案的核心不是提前写死几个角色，比如 planner、developer、tester、reviewer。

更好的方式是建立一套“动态子智能体生成规范”。

主会话天然就是主智能体，也就是 coordinator。它不应该陷入所有代码细节，而应该负责：

• 判断当前任务是否需要多智能体；
• 拆解任务边界；
• 生成子智能体 brief；
• 分发任务；
• 收集结果文件；
• 判断任务是通过、失败、重试还是阻塞；
• 最后汇总证据和交付报告。

子智能体则只负责边界清晰的小任务。

例如：

• 调查型 Agent：只读代码，输出调查报告；
• 实现型 Agent：只修改指定文件，输出变更记录；
• 测试型 Agent：只运行测试和复现流程，输出测试报告；
• 审查型 Agent：只做代码审查，不改代码；
• UI 验证 Agent：只启动页面、检查交互、输出截图或观察结果；
• 文档 Agent：只更新 README、使用说明、变更记录。

主智能体像项目负责人，子智能体像临时创建的工程成员。每个成员都必须有明确任务、明确权限、明确输出位置。

三、什么时候应该启用多智能体？

多智能体不是默认越多越好。

它适合这些场景：

1. 多文件功能开发例如新增一个完整功能，涉及后端接口、前端页面、配置文件、测试文件。
2. 复杂 bug 调查例如报错来源不清楚，需要先搜索代码、看日志、复现问题，再决定修复方案。
3. 重构任务例如拆分模块、迁移目录、统一接口、替换旧实现。
4. 前端页面实现和验证前端任务经常需要“实现 + 运行 + 截图/交互验证”，适合拆给不同 Agent。
5. 测试补齐实现和测试分开，让一个 Agent 写功能，另一个 Agent 写测试或验证测试是否真的覆盖问题。
6. 性能、安全、架构审查这类任务需要独立视角，不适合让实现者自己审自己。

它不适合这些场景：

1. 简单问答；
2. 单文件小改动；
3. 查一个命令；
4. 格式调整；
5. 不需要验证的小任务；
6. 用户只是想快速得到一个片段代码。

判断标准可以很简单：

如果任务可以在一个上下文里清楚完成，就不要启用多智能体。如果任务需要独立调查、独立实现、独立验证，就启用多智能体。

四、整体工作流设计

推荐把多智能体协作设计成一个受控流水线：

用户需求-> 主智能体判断是否启用多智能体-> 主智能体读取 multi-agent skill 规范-> 主智能体制定执行策略-> 必要时召唤调查/规划类子智能体-> 子智能体输出计划或调查报告文件-> 主智能体选择一个可验证任务-> 召唤实现类子智能体-> 实现类子智能体完成修改并输出变更报告-> 主智能体召唤测试/审查类子智能体-> 测试通过：进入下一个任务-> 测试失败：交回原实现 Agent 修复-> 原测试 Agent 复验-> 超过重试次数：标记 blocked-> 全部完成：主智能体汇总最终报告

这个流程里最重要的一点是：

子智能体不要直接决定下一步要召唤谁。

子智能体完成任务后，只返回状态和结果地址。下一步由主智能体判断。

否则多智能体容易失控，变成“Agent 继续召唤 Agent”，最后上下文、成本、任务边界都会失控。

五、子智能体 brief 应该怎么写？

每次创建或调用子智能体，都应该给它一个标准 brief。

可以使用下面这个模板：

role_name:本次子智能体的角色名，必须贴合当前任务。

mission:本次唯一任务目标。只能有一个主要目标。

when_to_use:为什么当前任务需要这个角色。

input_files:开始前必须读取哪些文件。

allowed_edit_scope:允许修改哪些文件或目录。

forbidden_actions:禁止做什么。例如不能删除文件、不能改配置、不能提交代码、不能改测试。

tools_policy:允许使用哪些工具。例如只读、可编辑、可运行测试、可启动服务。

output_path:结果必须写到哪里。

success_criteria:什么叫完成。必须可验证。

stop_condition:什么时候必须停止。例如发现需求不清、测试失败、权限不足、超过修改范围。

handoff_format:如何把结果交还给主智能体。

一个实现型子智能体的 brief 可以这样写：

role_name:auth-api-implementermission:实现用户登录接口的参数校验和错误返回逻辑。

input_files:

– src/routes/auth.ts

– src/services/auth-service.ts

– tests/auth.test.ts

allowed_edit_scope:

– src/routes/auth.ts

– src/services/auth-service.ts

forbidden_actions:

– 不允许修改测试文件

– 不允许改数据库 schema

– 不允许删除现有接口

– 不允许提交

git committools_policy:

– 可以读取文件

– 可以编辑 allowed_edit_scope 内的文件

– 可以运行相关测试output_path:

.agent-runs/2026-07-01/task-003/implementation-report.md

success_criteria:

– 登录接口能正确处理缺失参数- 错误返回格式与现有接口一致

– 相关测试可以通过

stop_condition:

– 如果发现现有测试与需求冲突，立即停止并报告

– 如果需要修改 allowed_edit_scope 之外的文件，立即停止并请求主智能体判断

handoff_format:STATUS:REPORT:CHANGED_FILES:TEST_COMMAND:NOTES:

这个 brief 的价值在于，它不会让子智能体自由发挥，而是把任务边界、权限、停止条件都提前写清楚。

六、输出协议：不要把所有内容塞回主上下文

多智能体协作里，最容易犯的错误是让子智能体把所有调查过程、代码片段、测试日志都直接返回给主会话。

这样做会迅速污染主上下文。

更好的方式是：完整结果写文件，主会话只接收简短状态和文件地址。

例如子智能体返回：

STATUS: PASSREPORT:

.agent-runs/2026-07-01/task-003/test-report.md

ARTIFACTS: .agent-runs/2026-07-01/task-003/screenshots/

SUMMARY: Auth API validation tests passed.

No regression found.

如果失败，则返回：

STATUS: FAILREPORT:

.agent-runs/2026-07-01/task-003/test-report.md

FAILED_CASES:

– tests/auth.test.ts::should_return_400_when_password_missing

REASON:Password missing case returns 500 instead of 400.SUGGESTED_NEXT_STEP:Send back to auth-api-implementer for repair.

这样有两个好处：

第一，主智能体上下文保持干净。

第二，整个过程可以追踪、复盘、验收。

以后用户想知道“到底改了什么”“测试有没有跑”“为什么失败”，都可以直接看.agent-runs目录里的报告。

七、失败修复机制：谁实现，谁优先修；谁发现，谁复验

多智能体协作必须设计失败处理规则。

推荐规则是：

谁实现的，优先谁修。谁发现的问题，优先谁复验。

原因很简单：

实现 Agent 拥有开发过程上下文，知道自己为什么这么改，修复效率更高。测试 Agent 知道自己发现的问题是什么，复验更准确。

流程可以这样设计：

实现 Agent 完成-> 测试 Agent 验证-> 如果通过，进入下一任务-> 如果失败，测试 Agent 输出失败报告-> 主智能体把失败报告交回原实现 Agent-> 原实现 Agent 根据失败报告修复-> 原测试 Agent 再次复验-> 最多重试 2 到 3 次-> 仍失败则生成 blocked 报告

重试一定要有限制。

建议最多 2 到 3 轮。超过上限后，不要继续消耗 token，而是生成 blocked 报告：

STATUS: BLOCKEDREASON:

Login validation behavior conflicts with existing middleware behavior.

ATTEMPTS:

– Attempt 1: Added route-level validation, but middleware still throws 500.

– Attempt 2: Adjusted service error mapping, but test still fails.

NEED_HUMAN_DECISION:

Should validation be handled in route layer or global middleware?

RELATED_FILES:

– src/routes/auth.ts

– src/middleware/error

-handler.ts

– tests/auth.test.ts

这比无限循环修 bug 更有价值，因为它把失败原因、尝试路径、人工决策点都暴露出来了。

八、Skill 目录应该怎么设计？

这套方案适合做成一个multi-agent-programmingskill。

它不需要把所有内容都塞进一个巨大的SKILL.md，而应该采用“薄入口、厚规范”的结构。

推荐目录如下：

• multi-agent-programming/SKILL.md
• agent-factory/when-to-use.md
• role-generation-rules.md
• role-attribute-schema.md
• role-naming-rules.mdworkflow/orchestration-flow.md
• develop-test-repair-loop.mdretry-and-block-policy.md
• contracts/file-handoff-contract.mdreport-format.md
• task-result-format.mdquality/verification-policy.md
• acceptance-checklist.mddone-definition.md
• examples/feature-development.md
• bug-fix.mdfrontend-ui.mdrefactor.md

其中SKILL.md只做入口，不写太长。

它主要告诉 Claude Code / Codex：

当用户任务满足复杂度条件时，启用 multi-agent-programming 工作流。

你是 coordinator，不要直接沉入所有实现细节。

你需要：

1. 判断是否真的需要多智能体；

2. 读取 agent-factory 中的角色生成规则；

3. 为每个子任务生成最小必要子智能体 brief；

4. 要求子智能体按照 contracts 中的文件交接协议输出；

5. 每个实现任务必须经过验证；

6. 测试失败时进入 develop-test-repair-loop；

7. 超过重试上限时生成 blocked 报告；

8. 最终输出 summary、changed files、verification evidence、known issues。

SKILL.md不应该写成一本大书，而应该像一个调度入口。

真正的细则放在子文件里，让 Agent 需要时再读取。

九、具体落地步骤

可以按下面步骤做。

第一步：建立 skill 目录

在项目或用户级 skill 目录中创建：

multi-agent-programming/SKILL.md

agent-factory/workflow/contracts/quality/examples/

第二步：写when-to-use.md

这个文件只回答一个问题：什么时候启用多智能体。

示例：

Use multi-agent workflow when:

– The task affects more than 3 files.

– The task requires investigation before implementation.

– The task requires independent testing or review.

– The task includes frontend behavior that needs runtime verification.

– The task has high regression risk.

– The task is a refactor, migration, or architecture change.

Do not use multi-agent workflow when:

– The task is a simple explanation.

– The change is limited to one small file.

– The user asks for a quick command or small snippet.

– No verification is needed.

第三步：写role-attribute-schema.md

这个文件定义每个子智能体必须包含哪些字段。

不要让主智能体随便写一句“你去测试一下”，而是强制生成完整 brief。

第四步：写file-handoff-contract.md

这是整套系统的关键。

要求所有子智能体必须把详细结果写入文件，只返回状态和路径。

推荐统一目录：

• .agent-runs/2026-07-01/task-001/plan.md
• implementation-report.md
• test-report.mdreview-report.md
• final-summary.md

第五步：写verification-policy.md

规定什么叫完成。

例如：

A task is not done until at least one verification artifact exists:

– test command and result

– build command and result

– runtime output- screenshot

– log excerpt- manual inspection checklist

– explanation why verification cannot be run

这一步非常重要。

因为 Agent 最大的问题之一是“说完成”，但没有证据。验证策略就是防止它只靠语言交付。

第六步：写retry-and-block-policy.md

规定失败后怎么处理。

Default retry limit:

2.If verification fails:

1. Send the failure report to the original implementation agent.

2. Ask it to repair only the failing issue.

3. Send the repaired result back to the original verification agent.

4. If still failing after 2 retries, stop and create a blocked report.Blocked report must include:

– failure reason- attempts made

– files involved

– suspected root cause

– human decision needed

第七步：准备几个 examples

examples 不需要很多，但要覆盖常见任务：

• feature-development.md
• bug-fix.md
• frontend-ui.mdrefactor.md

示例的作用不是让 Agent 照抄，而是让它学习“什么样的任务应该怎么拆”。

十、一个真实使用方式示例

用户输入：

帮我给这个项目增加登录接口，包括参数校验、错误返回、测试，并确认不会影响现有注册接口。

主智能体应该先判断：

这是一个多文件功能开发任务，涉及接口实现、参数校验、测试和回归验证，适合启用多智能体。

然后它可以拆成：

Agent 1: auth-codebase-investigator任务：调查现有 auth 结构、注册接口、错误处理方式，只读，不修改。

Agent 2: auth-api-implementer任务：根据调查报告实现登录接口，只允许修改 routes 和 service。

Agent 3: auth-api-test-writer任务：补充登录接口测试，只允许修改 tests/auth.test.ts。

Agent 4: auth-regression-verifier任务：运行 auth 相关测试，确认注册接口没有被破坏。

Agent 5: code-reviewer任务：审查实现是否符合项目风格和错误处理规范，不修改代码。

每个 Agent 都输出报告文件。

最后主智能体汇总：

FINAL STATUS: PASSCHANGED_FILES:

– src/routes/auth.ts

– src/services/auth-service.ts

– tests/auth.test.ts

VERIFICATION:

– npm test — auth.test.ts: PASS

– npm run typecheck:

PASSREPORTS:

– .agent-runs/2026-07-01/task-001/investigation-report.md

– .agent-runs/2026-07-01/task-001/implementation-report.md

– .agent-runs/2026-07-01/task-001/test-report.md

– .agent-runs/2026-07-01/task-001/review-report.md

KNOWN_ISSUES:

– No rate limit added. Recommend separate security task.

这就比普通 Agent 回复“我已经完成登录接口”可靠得多。

十一、这套方案真正提升的是什么？

它提升的不是单次代码生成能力，而是复杂任务的工程可控性。

具体来说，它解决了五个问题：

第一，降低上下文污染。调查、日志、测试输出都留在子智能体和本地报告里，主会话只保留决策信息。

第二，提高验证可信度。实现和测试分离，避免 Agent 自己写完自己宣布成功。

第三，让失败可追踪。每次失败都有报告、原因、尝试路径和下一步建议。

第四，让经验可沉淀。.agent-runs目录里的报告可以反过来优化 skill、补充常见错误、形成项目知识库。

第五，让 Coding Agent 更像工程团队。主智能体负责调度，子智能体负责执行，验证智能体负责把关，最终交付证据链。

十二、需要注意的边界

多智能体不是银弹。

它会带来额外 token 成本，也会增加流程复杂度。对于简单任务，单 Agent 反而更快。

另外，不同工具对 subagents 和 skills 的支持方式不同。Codex 更适合在明确要求时使用 subagent workflows，把任务拆给多个专门 Agent 并汇总结果。Claude Code 则可以通过自定义 subagents、skills、权限限制、hooks 等方式，构建更细的任务型工作流。

所以这套方案的最佳定位不是“重新发明 Agent 平台”，而是：

给现有顶尖 Coding Agent 加上一套可复用的工程协作规范。

它的本质是一个“多智能体编排 Skill”。

主智能体仍然是 Claude Code 或 Codex，子智能体仍然由这些工具调用。我们做的事情，是给它们一套更清晰的组织方式：

• 什么时候拆任务；
• 拆给谁；
• 允许改哪里；
• 禁止做什么；
• 如何交接；
• 怎么验证；
• 失败怎么修；
• 最后怎么交付证据。

当这些规范稳定下来之后，Coding Agent 就不再只是一个“会写代码的助手”，而更像一个有流程、有边界、有验收标准的小型工程团队。