功能说明: 本技能涵盖 结构化流程和配置指引、化工作流场景 等核心能力。
多代理开发
通过为每个任务派发新鲜子代理执行实现计划,并在每步后进行两阶段评审(先规格合规,后代码质量),实现高质量快速迭代. 核心原则: 每任务新鲜子代理 + 两阶段评审(规格→质量) = 高质量、快迭代
何时使用
输入定义
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| input | string | 是 | 多代理开发处理的输入数据或指令 |
| options | object | 否 | 附加配置选项,如模式选择、格式偏好等 |
| callback_url | string | 否 | 异步处理完成后的回调通知URL |
有实现计划? ──否──→ 手动执行或先头脑风暴
│是
任务相对独立? ──否(紧耦合)──→ 手动执行或先头脑风暴
│是
留在当前会话? ──否──→ 使用并行会话执行(execute-elsewhere)
│是
▼
使用多代理开发(本技能)
与并行会话执行的对比:
- 同一会话(无上下文切换)
- 每任务新鲜子代理(无上下文污染)
- 每任务后两阶段评审:先规格合规,后代码质量
- 更快迭代(任务间无需人工介入)
执行流程
读取计划,提取所有任务全文,记录上下文,创建TodoWrite
│
▼
┌─── 每个任务 ────────────────────────────────────┐
│ │
│ 派发实现子代理(提供完整任务文本+上下文) │
│ │ │
│ 子代理有疑问? ──是──→ 回答问题,提供上下文──→重新派发│
│ │否 │
│ 子代理实现、测试、提交、自评审 │
│ │ │
│ 派发规格评审子代理 │
│ │ │
│ 规格合规? ──否──→ 实现子代理修复规格差距──→重新评审│
│ │是 │
│ 派发代码质量评审子代理 │
│ │ │
│ 质量通过? ──否──→ 实现子代理修复质量问题──→重新评审│
│ │是 │
│ 在TodoWrite中标记任务完成 │
│ │
└─────────────────────────────────────────────────┘
│
▼
还有更多任务? ──是──→ 派发下一个任务实现子代理
│否
▼
派发最终全局代码评审子代理
│
▼
使用"完成开发分支"流程
提示模板
./implementer-prompt.md- 派发实现子代理./spec-reviewer-prompt.md- 派发规格合规评审子代理./code-quality-reviewer-prompt.md- 派发代码质量评审子代理
选择性并行执行策略(差异化)
并非所有任务都必须串行。根据任务依赖关系选择执行策略:
依赖详情
在提取任务后,构建依赖图:
任务A(独立) ──┐
任务B(独立) ──┼──→ 任务D(依赖A+B)
任务C(独立) ──┘ │
▼
任务E(依赖D)
执行策略选择
| 任务关系 | 策略 | 说明 |
|---|---|---|
| 完全独立(无共享文件) | 可并行派发实现子代理 | 加速开发,但评审仍串行 |
| 共享文件但无逻辑依赖 | 串行实现,可并行评审 | 避免文件冲突 |
| 有逻辑依赖 | 严格串行 | 等依赖任务完成后再开始 |
| 不确定 | 默认串行 | 安全优先 |
| 并行安全规则: |
- 永远不要并行派发操作同一文件的实现子代理(冲突)
- 并行实现完成后,评审必须串行进行
- 如并行任务出现冲突,回退到串行模式
分层评审机制(差异化)
评审层级
| 层级 | 触发条件 | 评审深度 | 成本 |
|---|---|---|---|
| L0 自评审 | 每次实现后 | 实现子代理自检 | 低 |
| L1 规格合规 | L0通过后 | 对照规格检查完整性 | 中 |
| L2 代码质量 | L1通过后 | 检查代码质量、优秀实践 | 中 |
| L3 全局评审 | 所有任务完成后 | 整体一致性、集成问题 | 高 |
评审顺序(严格遵守)
L0自评审 → L1规格合规 → L2代码质量 → (所有任务完成) → L3全局评审
绝不能在L1规格合规通过前开始L2代码质量评审(错误顺序).
用法示例
你: 我正在使用多代理开发来执行这个计划.
# ...
[读取计划文件一次: docs/plans/feature-plan.md]
[提取所有5个任务的完整文本和上下文]
[创建TodoWrite包含所有任务]
# ...
任务1: 钩子安装脚本
# ...
[获取任务1文本和上下文(已提取)]
[派发实现子代理,提供完整任务文本+上下文]
# ...
实现者: "开始前 - 钩子应安装在用户级还是系统级?"
# ...
你: "用户级($HOME/.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环境不可用
- 复杂业务场景建议结合人工经验判断
- 执行效率受模型能力与网络环境影响
结果格式
处理结果以结构化格式返回, 包含状态码、消息和数据字段.
安全规范
| 风险类型 | 防范措施 |
|---|---|
| API密钥泄露 | 使用环境变量注入,不得在源码中明文写入 |
| 命令执行风险 | 执行命令受限于安全白名单,不拼接用户输入 |
| 网络通信安全 | 通信使用HTTPS并校验证书有效性 |
| 敏感数据暴露 | 输出不含敏感凭据 |
| 使用前请确认已阅读依赖说明章节,确保运行环境满足安全要求。 |
性能数据
| 操作场景 | 手动耗时 | 自动化耗时 | 效率提升 |
|---|---|---|---|
| 文件解析与提取 | 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 |
初次使用指南
- 配置API密钥: 在环境变量中设置对应的API Key
- 初始化连接: 使用提供的凭证建立API连接
- 调用接口: 传入必要参数执行API调用
- 准备文件: 确认文件路径正确且格式受支持
- 执行处理: 调用对应的处理函数
- 查看结果: 检查输出文件或返回数据
- 检查环境: 确认运行时和依赖已安装
- 执行命令: 使用正确的参数格式执行
- 查看输出: 检查命令输出和退出码
前置条件
- 已安装所需运行环境(参考依赖说明)
- 已获取必要的API密钥或访问凭证(如适用)
- 输入数据已准备就绪
异常处置
针对"多代理开发"使用中可能遇到的常见问题,提供以下排查方案:
| 错误类型 | 原因分析 | 解决方案 |
|---|---|---|
| API认证失败(401) | API密钥错误或过期 | 检查密钥配置,重新生成token |
| 接口限流(429) | 请求频率超出限制 | 降低调用频率,启用重试退避策略 |
| 响应超时(504) | 网络延迟或服务端负载过高 | 增加超时阈值,检查网络连接 |
| 文件不存在 | 路径错误或文件未创建 | 检查路径拼写,确认文件已生成 |
| 文件格式不支持 | 扩展名不在支持列表中 | 转换为支持的格式后重试 |
| 权限不足 | 当前用户无读写权限 | 检查文件权限,以管理员身份运行 |
| 命令执行失败 | 参数错误或环境依赖缺失 | 检查命令语法,确认依赖已安装 |
| 进程超时 | 命令执行时间过长 | 增加超时设置,优化命令参数 |
| 网络连接失败 | DNS解析失败或防火墙拦截 | 检查网络配置,确认代理设置 |
"多代理开发"通用排查步骤
- 检查输入参数: 确认所有必填参数已提供且格式正确
- 查看日志输出: 定位具体错误行和异常类型
- 验证环境配置: 确认依赖库版本和运行环境满足要求
- 逐步调试: 缩小问题范围,隔离故障模块
帮助手册
Related skills
- Downloads
- 868All time
- Security audit
- Pass
- Last updated
- 2mo ago
- Current version
- v1.0.2
- License
- MIT-0
