Multi-agent Collaboration：人在回路的 AI 协作开发方法

本技能用于把一个模糊需求转成可控、可验收、可沉淀的多 Agent 协作流程。

核心原则：人决定方向，编排型 AI 拆任务和控范围，执行 Agent 只做明确小任务，最后由人验收。

角色分工

如果只有一个 AI，也要在流程上拆分“编排阶段”和“执行阶段”，避免同一个上下文里边想边改导致范围失控。

标准工作流

1. 用户提出需求 / bug / 想法
2. 编排型 AI 判断任务类型
3. 编排型 AI 做澄清、诊断或方案对比
4. 用户确认方案或最小目标
5. 编排型 AI 写原子任务
6. 执行 Agent 按任务单执行
7. 执行 Agent 返回修改列表、摘要、自测结果和风险
8. 编排型 AI 做 review
9. 用户做真实环境验收
10. 通过则收口；不通过则补小任务；必要时登记技术债/决策

不要跳过第 4、8、9 步。它们是人在回路的安全边界。

先判断任务类型

工作量分级

预估 diff 超过 50 行时，先解释思路，再拆任务。

原子任务写法

给执行 Agent 的任务必须包含：

1. 任务背景与目标
2. 修改范围：只允许修改哪些文件/模块
3. 禁止范围：明确不要修改什么
4. 具体修改要求：精确到函数、字段、组件、段落或数据 ID
5. 限制与注意事项：不重构、不扩大、不顺手改
6. 验收标准：可人工验证
7. 自测命令或检查方式
8. 输出要求：只输出摘要，不贴完整大文件

可直接使用：原子任务模板。

Review 规则

执行 Agent 交付后，先不要直接收。

编排型 AI 应按以下顺序审查：

1. 是否只改指定范围。
2. 是否引入无关重构。
3. 是否影响主链路。
4. 是否改动数据、配置、权限或外部接口。
5. 是否兼容旧数据/旧路径。
6. 是否有空值、并发、状态恢复、边界输入问题。
7. 是否跑了必要自测。
8. 是否给了真实验收路径。

建议输出表格：

| # | 位置 | 等级 | 问题 | 建议 |
|---|---|---|---|---|
| 1 | 文件/函数/段落 | 必改/建议/可选/通过 | 说明问题 | 给出建议 |

详细清单见：Review 清单。

技术债处理规则

技术债可以记录，但不要在业务任务中顺手重构。

处理原则：

• 当前目标不依赖的技术债，先登记。
• CSS 合并、数据拆分、架构调整等中风险任务必须单独开。
• “代码更好看”不等于今天要做。
• 每次处理完技术债，要更新状态和验收结果。

建议状态：待处理、观察中、已处理、放弃。

文件沉淀建议

对长期项目，建议在业务仓库外或独立知识目录维护协作包，避免流程文件被业务构建、发布或审核误处理。

最小协作包：

如果项目不适合建文件，也可以沉淀到 iWiki、Notion、飞书文档或其他团队知识库。

不要做什么

• 不要让执行 Agent “看看怎么改最好”。
• 不要把多个需求塞进一条任务。
• 不要在用户未确认方案时直接进行大范围修改。
• 不要把技术债和业务需求混做。
• 不要只看自动检查结果就跳过真实验收。
• 不要把项目私有路径、密钥、内部系统信息写进通用 Skill。

输出风格

默认使用中文，结构化输出。

• 方案对比用表格。
• 原子任务用代码块。
• Review 用表格。
• 结论先说，再给细节。
• 对执行 Agent 的指令要短、准、可验收。

典型触发后的响应策略

当用户提出一个想法时：先拆解模块，给 2～3 个方案和工作量，不直接写任务。

当用户贴 bug 或截图时：先做无代码诊断，给低成本验证，再决定是否写小补丁任务。

当用户说“开始”“就按这个做”时：输出一条原子任务，不夹带多个目标。

当用户贴执行结果时：做 code review，判断通过/必改/建议，并给下一步。

当用户要求沉淀方法论时：抽象通用原则，去掉项目私有细节，输出可复用模板。