多代理开发

多代理开发是一个通过子代理编排执行实现计划的开发框架。针对传统子代理开发"协调开销大、上下文污染、串行瓶颈、评审成本高"四大痛点,构建了智能任务分解图、选择性并行执行、分层评审机制和上下文隔离四大核心能力。 核心能力包括:每任务派发新鲜子代理避免上下文污染;两阶段评审(规格合规→代码质量);选择性并行执行独立任务...

核心功能: 本技能提供结构化流程和配置指引、化工作流场景等能力。

通过为每个任务派发新鲜子代理执行实现计划,并在每步后进行两阶段评审(先规格合规,后代码质量),实现高质量快速迭代. 核心原则: 每任务新鲜子代理 + 两阶段评审(规格→质量) = 高质量、快迭代

何时使用

输入定义

参数名	类型	必填	说明
input	string	是	多代理开发处理的输入数据或指令
options	object	否	附加配置选项,如模式选择、格式偏好等
callback_url	string	否	异步处理完成后的回调通知URL

text

有实现计划? ──否──→ 手动执行或先头脑风暴
     │是
任务相对独立? ──否(紧耦合)──→ 手动执行或先头脑风暴
     │是
留在当前会话? ──否──→ 使用并行会话执行(execute-elsewhere)
     │是
▼
使用多代理开发(本技能)

与并行会话执行的对比:

• 同一会话(无上下文切换)
• 每任务新鲜子代理(无上下文污染)
• 每任务后两阶段评审:先规格合规,后代码质量
• 更快迭代(任务间无需人工介入)

执行流程

text

读取计划,提取所有任务全文,记录上下文,创建TodoWrite
         │
         ▼
┌─── 每个任务 ────────────────────────────────────┐
│                                                 │
│  派发实现子代理(提供完整任务文本+上下文)          │
│         │                                       │
│  子代理有疑问? ──是──→ 回答问题,提供上下文──→重新派发│
│         │否                                     │
│  子代理实现、测试、提交、自评审                    │
│         │                                       │
│  派发规格评审子代理                               │
│         │                                       │
│  规格合规? ──否──→ 实现子代理修复规格差距──→重新评审│
│         │是                                     │
│  派发代码质量评审子代理                            │
│         │                                       │
│  质量通过? ──否──→ 实现子代理修复质量问题──→重新评审│
│         │是                                     │
│  在TodoWrite中标记任务完成                        │
│                                                 │
└─────────────────────────────────────────────────┘
         │
         ▼
   还有更多任务? ──是──→ 派发下一个任务实现子代理
         │否
         ▼
   派发最终全局代码评审子代理
         │
         ▼
   使用"完成开发分支"流程

提示模板

• ./implementer-prompt.md - 派发实现子代理
• ./spec-reviewer-prompt.md - 派发规格合规评审子代理
• ./code-quality-reviewer-prompt.md - 派发代码质量评审子代理

选择性并行执行策略(差异化)

并非所有任务都必须串行。根据任务依赖关系选择执行策略:

依赖详情

在提取任务后,构建依赖图:

text

任务A(独立) ──┐
任务B(独立) ──┼──→ 任务D(依赖A+B)
任务C(独立) ──┘         │
                        ▼
                    任务E(依赖D)

执行策略选择

任务关系	策略	说明
完全独立(无共享文件)	可并行派发实现子代理	加速开发,但评审仍串行
共享文件但无逻辑依赖	串行实现,可并行评审	避免文件冲突
有逻辑依赖	严格串行	等依赖任务完成后再开始
不确定	默认串行	安全优先
并行安全规则:

• 永远不要并行派发操作同一文件的实现子代理(冲突)
• 并行实现完成后,评审必须串行进行
• 如并行任务出现冲突,回退到串行模式

分层评审机制(差异化)

评审层级

层级	触发条件	评审深度	成本
L0 自评审	每次实现后	实现子代理自检	低
L1 规格合规	L0通过后	对照规格检查完整性	中
L2 代码质量	L1通过后	检查代码质量、优秀实践	中
L3 全局评审	所有任务完成后	整体一致性、集成问题	高

评审顺序(严格遵守)

text

L0自评审 → L1规格合规 → L2代码质量 → (所有任务完成) → L3全局评审

绝不能在L1规格合规通过前开始L2代码质量评审(错误顺序).

用法示例

text

你: 我正在使用多代理开发来执行这个计划.
# ...
[读取计划文件一次: docs/plans/feature-plan.md]
[提取所有5个任务的完整文本和上下文]
[创建TodoWrite包含所有任务]
# ...
任务1: 钩子安装脚本
# ...
[获取任务1文本和上下文(已提取)]
[派发实现子代理,提供完整任务文本+上下文]
# ...
实现者: "开始前 - 钩子应安装在用户级还是系统级?"
# ...
你: "用户级(~/.config/hooks/)"
# ...
实现者: "明白。开始实现..."
[稍后] 实现者:
  - 实现了install-hook命令
  - 添加了测试,5/5通过
  - 自评审:发现漏了--force标志,已添加
  - 已提交
# ...
[派发规格合规评审]
规格评审: ✅ 规格合规 - 所有要求满足,无多余内容
# ...
[获取git SHA,派发代码质量评审]
代码评审: 优点:测试覆盖好,代码整洁。问题:无。通过.
# ...
[标记任务1完成]
# ...
任务2: 恢复模式
# ...
[获取任务2文本和上下文(已提取)]
[派发实现子代理,提供完整任务文本+上下文]
# ...
实现者: [无问题,继续]
实现者:
  - 添加了verify/repair模式
  - 8/8测试通过
  - 自评审:一切正常
  - 已提交
# ...
[派发规格合规评审]
规格评审: ❌ 问题:
  - 缺失:进度报告(规格说"每100项报告")
  - 多余:添加了--json标志(未要求)
# ...
[实现者修复问题]
实现者: 移除--json标志,添加进度报告
# ...
[规格评审重新评审]
规格评审: ✅ 现在规格合规
# ...
[派发代码质量评审]
代码评审: 优点:扎实。问题(重要):魔术数字(100)
# ...
[实现者修复]
实现者: 提取PROGRESS_INTERVAL常量
# ...
[代码评审重新评审]
代码评审: ✅ 通过
# ...
[标记任务2完成]
# ...
...
# ...
[所有任务完成后]
[派发最终代码评审]
最终评审: 所有要求满足,可合并
# ...
完成!

优势对比

相比手动执行:

• 子代理自然遵循TDD
• 每任务新鲜上下文(无混淆)
• 并行安全(子代理不互相干扰)
• 子代理可提问(工作前和工作期间) 相比并行会话执行:
• 同一会话(无交接)
• 持续进展(无需等待)
• 评审检查点自动化 效率提升:
• 无文件读取开销(控制器提供完整文本)
• 控制器精确策展所需上下文
• 子代理预先获得完整信息
• 问题在工作开始前浮现(而非之后) 质量门禁:
• 自评审在交接前捕获问题
• 两阶段评审:规格合规,然后代码质量
• 评审循环确保修复实际有效
• 规格合规防止过度/不足构建
• 代码质量确保实现质量优良 成本:
• 更多子代理调用(每任务implementer + 2 reviewers)
• 控制器更多准备工作(预先提取所有任务)
• 评审循环增加迭代
• 但早期捕获问题(比后期调试更便宜)

红旗清单(绝不做)

永远不要:

• 未经用户明确同意在main/master分支开始实现
• 跳过评审(规格合规或代码质量)
• 带着未修复的问题继续
• 并行派发操作同一文件的实现子代理(冲突)
• 让子代理读取计划文件(提供完整文本)
• 跳过场景设定上下文(子代理需要理解任务位置)
• 忽略子代理问题(让其继续前回答)
• 接受规格合规"差不多"(评审发现问题=未完成)
• 跳过评审循环(评审发现问题=实现者修复=重新评审)
• 让实现者自评审替代实际评审(两者都需要)
• 在规格合规通过前开始代码质量评审(错误顺序)
• 在任一评审有未解决问题时进入下一任务

应急流程

子代理提问时

• 清晰完整地回答
• 必要时提供额外上下文
• 不要催促他们进入实现

评审发现问题

• 实现者(同一子代理)修复
• 评审者重新评审
• 重复直到通过
• 不要跳过重新评审

子代理任务失败

• 派发修复子代理并附带具体指令
• 不要手动修复(上下文污染)

子代理上下文不足

• 控制器补充缺失上下文
• 重新派发带完整上下文的子代理
• 记录为学习条目供未来参考

并行任务冲突

• 立即停止冲突任务
• 回退到串行执行
• 记录冲突文件以便未来避免

集成

必需的工作流技能:

• git-worktrees - 必需:开始前设置隔离工作空间
• writing-plans - 创建本技能执行的计划
• requesting-code-review - 评审子代理的代码评审模板
• finishing-a-development-branch - 所有任务完成后完成开发 子代理应使用:
• test-driven-development - 子代理每任务遵循TDD 替代工作流:
• executing-plans - 用于并行会话而非同会话执行

常见疑问

Q: 任务之间有依赖怎么办? A: 严格串行执行依赖任务。使用依赖图识别哪些任务可并行(完全独立)、哪些必须串行(有逻辑依赖)。不确定时默认串行. Q: 评审循环太多导致成本过高? A: 使用分层评审。L0自评审可过滤明显问题,减少L1/L2评审循环。确保实现子代理在提交前充分自检。规格清晰的计划能减少规格合规循环. Q: 子代理反复提问影响效率? A: 确保控制器在派发时提供完整上下文(任务全文+场景设定+相关文件内容)。如子代理仍反复提问,可能是计划不够详细,应先完善计划. Q: 如何判断任务是否"相对独立"? A: 检查任务是否操作相同文件、是否有数据依赖、是否需要前序任务的输出。如都不涉及,则独立。不确定时按串行处理. Q: 并行执行真的安全吗? A: 仅当任务操作完全不同的文件且无逻辑依赖时安全。并行实现完成后评审仍需串行。出现任何冲突立即回退串行.

故障处理

问题	原因	解决方案
子代理产出与规格不符	上下文不足或规格模糊	补充完整任务文本+场景设定,重新派发
评审循环超过3次	实现质量低或规格不清晰	检查规格明确性,考虑重新分解任务
子代理上下文污染	复用了非新鲜子代理	确保每任务派发全新子代理
并行任务文件冲突	操作了相同文件	立即停止,回退串行执行
TodoWrite状态不同步	未及时更新任务状态	每完成一个任务立即更新TodoWrite
最终评审发现集成问题	任务间接口未对齐	在计划阶段明确接口契约

环境要求

运行环境

• Agent平台: 支持子代理派发能力的AI Agent(Claude Code / Cursor / Codex等)
• 操作系统: Windows / macOS / Linux
• Git: 必需(分支管理、提交、worktree)

第三方依赖

依赖项	类型	是否必需	获取方式
LLM API	API	必需	由Agent内置LLM提供
Git	工具	必需	系统自带或从git-scm.com安装
子代理能力	平台功能	必需	Agent平台需支持子代理派发

API Key 配置

• 本技能基于Markdown指令,无需额外API Key

可用性分类

• 分类: MD+EXEC模式纯Markdown指令,需要子代理派发与命令行执行能力)
• 说明: 基于Markdown的AI Skill,通过自然语言指令驱动Agent编排子代理执行开发任务。需要Agent平台支持子代理派发功能.

能力一览

多代理开发是一个通过子代理编排

多代理开发是一个通过子代理编排执行实现计划的开发框架 处理: 解析多代理开发是一个通过子代理编排的输入参数,完成核心逻辑,生成结构化输出. 输出: 返回多代理开发是一个通过子代理编排的响应数据,含状态码、结果数据和运行日志.

• 通过input_params参数指定操作类型(创建/查询/导出)

针对传统子代理开发"协调开销大、上下文污

针对传统子代理开发"协调开销大、上下文污染、串行瓶颈、评审成本高"四大痛点,构建了智能任务分解图、选择性并行执行、分层评审机制和上下文隔离四大核心能力 处理: 解析针对传统子代理开发"协调开销大、上下文污的输入参数,完成核心逻辑,生成结构化输出. 输出: 返回针对传统子代理开发"协调开销大、上下文污的响应数据,含状态码、结果数据和运行日志.

• 通过input_params参数指定操作类型(创建/查询/导出)

核心能力包括

核心能力包括:每任务派发新鲜子代理避免上下文污染 处理: 解析核心能力包括的输入参数,完成核心逻辑,生成结构化输出. 输出: 返回核心能力包括的响应数据,含状态码、结果数据和运行日志.

• 通过input_params参数指定操作类型(创建/查询/导出)

两阶段评审(规格合规→代码质量

两阶段评审(规格合规→代码质量) 处理: 解析两阶段评审(规格合规→代码质量的输入参数,完成核心逻辑,生成结构化输出. 输出: 返回两阶段评审(规格合规→代码质量的响应数据,含状态码、结果数据和运行日志.

• 通过input_params参数指定操作类型(创建/查询/导出)

选择性并行执行独立任务

选择性并行执行独立任务 处理: 解析选择性并行执行独立任务的输入参数,完成核心逻辑,生成结构化输出. 输出: 返回选择性并行执行独立任务的响应数据,含状态码、结果数据和运行日志.

• 通过input_params参数指定操作类型(创建/查询/导出) 技术实现要点：核心能力基于input_params参数与output_format配置实现,支持创建/查询/修改/删除等操作模式,通过config_options进行运行时配置. 能力覆盖范围：核心能力涵盖以下关键词：上下文隔离防污染、Use、when、需要代码生成、编程辅助、调试测试、开发部署时使用、不适用于无明确技、术栈的模糊需求等。这些关键词对应description中声明的使用场景,均已在上述能力点中提供对应的操作支持.

能力边界

• 需LLM支持,无LLM环境不可用
• 复杂业务场景建议结合人工经验判断
• 执行效率受模型能力与网络环境影响

异常恢复指南

• 边界输入处理: 空输入返回提示信息, 超长输入自动截断
• 降级策略: 异常时返回默认值, 确保流程不中断 - 处理方式: 按上述步骤操作并确认结果
• 完成ping命令测试网络连通性,检查防火墙和代理设置连接后重新完成命令机制: 失败时自动完成ping命令测试网络连通性,检查防火墙和代理设置连接后重新完成命令, 最多3次 - 解析方式: 按上述步骤任务并确认响应

结果格式

处理结果以结构化格式返回, 包含状态码、消息和数据字段.

安全规范

风险类型	防范措施
API密钥泄露	使用环境变量注入,不得在源码中明文写入
命令执行风险	执行命令受限于安全白名单,不拼接用户输入
网络通信安全	通信使用HTTPS并校验证书有效性
敏感数据暴露	输出不含敏感凭据
使用前请确认已阅读依赖说明章节，确保运行环境满足安全要求。

主要特性

• 自动化执行: 智能任务分解,选择性并行执行,分层评审机制,上下文隔离防污染。。多代理开发是一个通过子代理编排执行实现计划的开发框架。针
• 文件处理: 支持多种文件格式的读取、解析和写入操作
• API集成: 通过标准化接口调用外部服务并处理响应
• 命令执行: 在安全沙箱中执行系统命令并收集结果
• 信息检索: 快速搜索和过滤目标数据

性能数据

操作场景	手动耗时	自动化耗时	效率提升
文件解析与提取	5-10分钟/个	<5秒/个	60-120x
批量文件处理(100个)	8-16小时	<5分钟	96-192x
API调用与响应解析	2-3分钟/次	<1秒/次	120-180x
多接口数据聚合	15-30分钟	<10秒	90-180x
命令执行与结果收集	3-5分钟/次	<2秒/次	90-150x
重复任务批量执行	因任务而异	线性缩减	5-50x
错误排查与修复	10-30分钟	<30秒	20-60x

初次使用指南

1. 配置API密钥: 在环境变量中设置对应的API Key
2. 初始化连接: 使用提供的凭证建立API连接
3. 调用接口: 传入必要参数执行API调用
4. 准备文件: 确认文件路径正确且格式受支持
5. 执行处理: 调用对应的处理函数
6. 查看结果: 检查输出文件或返回数据
7. 检查环境: 确认运行时和依赖已安装
8. 执行命令: 使用正确的参数格式执行
9. 查看输出: 检查命令输出和退出码

前置条件

• 已安装所需运行环境(参考依赖说明)
• 已获取必要的API密钥或访问凭证(如适用)
• 输入数据已准备就绪

问答合集

Q1: "多代理开发"支持哪些输入格式？

A1: "智能任务分解,选择性并行执行,分层评审机制,上下文隔离防污染。。针对传统子代理开发"协调开销大、上下文污。支持文本指令和结构化参数输入，具体格式参考使用流程章节。

Q2: 需要配置API Key吗？

A2: 是的，部分功能需要配置对应平台的API Key。请在依赖说明章节查看具体要求，并通过环境变量安全配置。

Q3: 命令行执行失败怎么办？

A3: 检查命令参数是否正确，确认运行环境支持exec能力。如遇权限问题，请参照错误处理章节排查。

异常处置

针对"多代理开发"使用中可能遇到的常见问题,提供以下排查方案:

错误类型	原因分析	解决方案
API认证失败(401)	API密钥错误或过期	检查密钥配置,重新生成token
接口限流(429)	请求频率超出限制	降低调用频率,启用重试退避策略
响应超时(504)	网络延迟或服务端负载过高	增加超时阈值,检查网络连接
文件不存在	路径错误或文件未创建	检查路径拼写,确认文件已生成
文件格式不支持	扩展名不在支持列表中	转换为支持的格式后重试
权限不足	当前用户无读写权限	检查文件权限,以管理员身份运行
命令执行失败	参数错误或环境依赖缺失	检查命令语法,确认依赖已安装
进程超时	命令执行时间过长	增加超时设置,优化命令参数
网络连接失败	DNS解析失败或防火墙拦截	检查网络配置,确认代理设置

"多代理开发"通用排查步骤

1. 检查输入参数: 确认所有必填参数已提供且格式正确
2. 查看日志输出: 定位具体错误行和异常类型
3. 验证环境配置: 确认依赖库版本和运行环境满足要求
4. 逐步调试: 缩小问题范围,隔离故障模块

帮助手册

异常管理

针对"多代理开发"使用中可能遇到的常见问题,提供以下排查方案:

错误类型	原因分析	解决方案
API认证失败(401)	API密钥错误或过期	检查密钥配置,重新生成token
接口限流(429)	请求频率超出限制	降低调用频率,启用重试退避策略
响应超时(504)	网络延迟或服务端负载过高	增加超时阈值,检查网络连接
文件不存在	路径错误或文件未创建	检查路径拼写,确认文件已生成
文件格式不支持	扩展名不在支持列表中	转换为支持的格式后重试
权限不足	当前用户无读写权限	检查文件权限,以管理员身份运行
命令执行失败	参数错误或环境依赖缺失	检查命令语法,确认依赖已安装
进程超时	命令执行时间过长	增加超时设置,优化命令参数
网络连接失败	DNS解析失败或防火墙拦截	检查网络配置,确认代理设置

主要功能

• 自动化执行: "智能任务分解,选择性并行执行,分层评审机制,上下文隔离防污染。。
• 文件处理: 支持多种文件格式的读取、解析和写入操作
• API集成: 通过标准化接口调用外部服务并处理响应
• 命令执行: 在安全沙箱中执行系统命令并收集结果
• 信息检索: 快速搜索和过滤目标数据

依赖说明

运行环境

• Agent 平台: 支持SKILL.md的任意AI Agent
• 操作系统: Windows / macOS / Linux

可用性分类

• 分类: MD（纯Markdown指令，通过自然语言驱动Agent完成操作）
• 说明: 基于Markdown的AI Skill，通过自然语言指令驱动Agent完成操作。