SuperAPI AI 工具集

subagent-driven-development

编程与开发

查看项目

更新于 11-05 17:17

技能介绍

Subagent-Driven Development(子智能体驱动开发)是一种用于在当前会话中执行实施方案的技能,适用于实施方案中的任务大多相互独立的情况。它的核心做法是:为每个任务派发一个全新的实现者子智能体,每个任务完成后进行一次任务审查(检查规格符合性与代码质量),所有任务完成后做一次整分支的最终广域审查。

核心原则

每任务使用全新子智能体 + 任务审查(规格与质量)+ 最终广域审查 = 高质量、快速迭代。之所以使用子智能体,是为了把任务交给具有隔离上下文的专门智能体;通过精确构造指令与上下文,确保其专注并完成任务,而不是继承当前会话的上下文或历史。这样也能为主会话保留协调工作所需的上下文。

使用时机

技能中的决策流程为:若没有实施方案,先手动执行或先做头脑风暴;若有方案但任务紧耦合,同样先手动执行或先做头脑风暴;若任务大多独立但需要换到并行会话执行,则使用 executing-plans;若任务大多独立且留在当前会话中执行,则使用本技能。与在并行会话中执行方案相比,本技能的优势是:同一会话(无上下文切换)、每任务全新子智能体(无上下文污染)、每任务后审查并在最后做广域审查、迭代更快(任务之间无需人工介入)。

执行流程

先阅读方案,记录上下文与全局约束,创建待办事项列表;然后为任务派发实现者子智能体。若实现者子智能体提出问题,则回答问题并提供上下文后重新派发;否则由实现者实现、测试、提交并自审。随后生成 diff 文件,派发任务审查者子智能体;若审查者未同时报告规格通过且质量批准,则为 Critical/Important 问题派发修复子智能体,修复后重新审查;若通过,则在待办列表和进度记录中标记任务完成。判断是否还有任务:有则继续派发实现者;无则派发最终代码审查者子智能体,最后使用 superpowers:finishing-a-development-branch 收尾。

执行前的方案预检

在派发任务 1 之前,先扫描一遍方案以发现冲突:任务之间或任务与方案全局约束之间的矛盾;方案明确要求、但审查标准会视为缺陷的内容(例如断言为空的测试、逻辑块的逐字重复)。把发现的问题连同要求它的方案原文一起,作为一次批量提问呈现给人类伙伴,询问以哪一方为准,并在执行开始前完成,而不是执行中途每发现一个就打断一次。若扫描没有发现问题,则直接继续。审查循环仍是兜底机制,用于发现只有实现过程中才会浮现的冲突。

模型选择

使用能胜任各角色的最弱模型,以节省成本并提升速度。机械性实现任务(孤立函数、规格清晰、1-2 个文件)使用快速便宜的模型;集成与判断类任务(多文件协调、模式匹配、调试)使用标准模型;架构与设计任务使用能力最强的可用模型,最终整分支审查也属于此类。审查任务按 diff 的规模、复杂度和风险,选择具有同等判断力的模型。派发子智能体时始终显式指定模型;省略模型会继承会话模型,往往是最强也最贵的,会悄悄破坏这一策略。工具调用轮次数比 token 价格更重要:多步工作中最便宜的模型经常需要 2-3 倍轮次,总体反而更贵;审查者和依据文字描述工作的实现者应以中档模型为下限;当任务方案文本包含要写的完整代码时,实现即转录加测试,可使用最便宜档;单文件机械修复也用最便宜档。实现任务的复杂度信号:涉及 1-2 个文件且有完整规格则用便宜模型;涉及多文件并有集成问题则用标准模型;需要设计判断或广泛理解代码库则用最强模型。

处理实现者状态

实现者报告四种状态之一:DONE 表示生成审查包(scripts/review-package BASE HEAD,BASE 是派发实现者前记录的提交,绝不能用 HEAD~1,否则会悄悄丢弃多提交任务中除最后一次之外的所有提交),然后用打印出的路径派发任务审查者;DONE_WITH_CONCERNS 表示工作完成但有疑虑,先阅读疑虑,涉及正确性或范围的先处理再审查,若是观察性内容则记录后继续审查;NEEDS_CONTEXT 表示缺少信息,补充缺失上下文后重新派发;BLOCKED 表示无法完成任务,需评估阻塞原因——上下文问题则补充上下文并用同一模型重派,需要更强推理则换更强模型重派,任务过大则拆小,方案本身错误则上报人类。绝不能忽视升级请求,也不能不做改变就强迫同一模型重试。

处理审查者的 ⚠️ 项

任务审查者可能报告“⚠️ 无法从 diff 验证”的项目,即位于未改动代码或跨任务的需求。它们不阻塞其余审查,但必须在标记任务完成前由控制器自行解决,因为控制器掌握审查者所缺的方案与跨任务上下文。若确认是真实缺口,按规格审查失败处理,退回实现者并重新审查。

构造审查者提示

每任务审查是任务范围的关卡;广域审查只在最终整分支审查时做一次。填写审查者模板时:不要在没有具体任务相关理由的情况下添加“检查所有用法”“如有用则运行竞态测试”等开放式指令;不要要求审查者重新运行实现者已在同一代码上运行过的测试;不要预先判断发现——绝不指示审查者忽略或不标记某个问题。若提示中出现“不要标记”“不要把 X 当作缺陷”“至多算 Minor”“方案已选择”等字样,说明你在预判,通常是为了省掉一轮审查。交给审查者的全局约束块是它的注意力透镜:从方案全局约束或规格中逐字复制绑定要求,包括精确值、精确格式以及组件之间陈述的关系。审查者模板本身已带过程规则,约束块只放本项目规格的具体要求。把 diff 以文件交给审查者:运行 scripts/review-package BASE HEAD 并把打印的文件路径传给它(无 bash 时可用 git log --oneline、git diff --stat 和 git diff -U10 重定向到唯一命名文件)。派发提示只描述一个任务,不粘贴会话历史;新子智能体只需要其任务、涉及的接口和全局约束。Critical 与 Important 发现派发修复子智能体;Minor 发现记录到进度记录,并在最终整分支审查时指向该列表以便分诊。标记为 plan-mandated 或与方案要求冲突的发现属于人类决策:呈现发现与方案原文,询问以哪一方为准,不要因方案要求就驳回发现,也不要在未询问的情况下派发与方案矛盾的修复。最终整分支审查也使用审查包:运行 scripts/review-package MERGE_BASE HEAD(MERGE_BASE 用 git merge-base main HEAD 取得),并在最终审查派发中包含打印路径。每次修复派发都携带实现者契约:修复子智能体重新运行覆盖其改动的测试并报告结果;派发时点名覆盖测试文件,一行修复不需要整套测试;重新派发审查者前,确认修复报告包含覆盖测试、运行命令和输出。若最终整分支审查返回发现,派发一个修复子智能体处理完整发现列表,而不是每个发现一个修复者。

文件交接

粘贴进派发提示的内容和子智能体打印回来的内容都会在整个会话中常驻上下文,并在之后每轮被重读。因此以文件交接:任务简报——派发实现者前运行 scripts/task-brief PLAN_FILE N,它把任务全文提取到唯一命名文件并打印路径;派发提示应包含(1)一行说明该任务在项目中的位置;(2)简报路径,说明“先读它——这是你的需求,含要逐字使用的精确值”;(3)简报无法知道的来自前序任务的接口与决策;(4)你对简报中歧义的解决;(5)报告文件路径与报告契约。精确值只出现在简报中。报告文件——按简报命名(brief …/task-N-brief.md → report …/task-N-report.md),实现者把完整报告写入该文件,只返回状态、提交、一行测试摘要和疑虑。审查者输入——任务审查者获得三个路径:同一简报文件、报告文件和审查包,外加约束该任务的全局约束。修复派发把修复报告(含测试结果)追加到同一报告文件并返回简短摘要。

持久化进度

会话记忆无法在压缩后存活;真实会话中丢失位置的控制器曾重新派发整个已完成任务序列,这是观察到的最昂贵失败。因此用进度记录文件跟踪,而不仅是待办事项。技能开始时检查记录:cat "$(git rev-parse --show-toplevel)/.superpowers/sdd/progress.md";其中标记为完成的任务即为 DONE,不要重新派发,从第一个未标记完成的任务继续。任务审查干净返回时,与其他记录动作一起向记录追加一行:Task N: complete (commits <base7>..<head7>, review clean)。记录是恢复地图:它列出的提交即使在上下文不再记得创建时也存在于 git 中;压缩后应信任记录和 git log 而非自己的回忆。注意 git clean -fdx 会销毁记录(它是被 git 忽略的临时文件),若发生可从 git log 恢复。

提示模板

implementer-prompt.md 用于派发实现者子智能体;task-reviewer-prompt.md 用于派发任务审查者子智能体(规格符合性 + 代码质量);最终整分支审查使用 superpowers:requesting-code-review 的 code-reviewer.md。

限制与注意事项

本技能假设已有实施方案且任务大多相互独立;任务紧耦合时不适合。它依赖 git 提交、脚本(review-package、task-brief)和进度记录文件,并依赖特定提示模板路径。资料未提供安装命令、收费与价格、平台限制等额外信息。