高级 约 35 分钟 2026-10-12 02:30:02 · 56 阅读

subagent-driven-development Agent Skill 实战教程:安装配置与 9 个核心用法

subagent-driven-development Agent Skill 实战教程:安装配置与 9 个核心用法

把一份十几页的实施计划交给编码代理,最常见的结局是它一头扎进第一个任务,上下文越滚越长,到第五个任务时已经把前面的决定忘了一半。obra/superpowers 仓库(GitHub 29.8 万 star,MIT 协议)的 subagent-driven-development 技能给了一个反直觉的解法:每个任务派一个全新的实现者子代理,干完就换人,协调者只管派活、收报告、跑评审。这篇教程把这个 568 行 SKILL.md 拆开讲透——从台账防失忆到修复循环熔断,配三个官方脚本在干净仓库里的完整实测。

相关背景可参考 AI 编程总纲,工具档案见 Superpowers 产品页。同仓库的 brainstorming、diagnosing-superpowers、finishing-a-development-branch、receiving-code-review 实战均已上线;本篇是这条线的重头戏,官方自己的定位是「高质量、快迭代」的执行引擎。

为什么每个任务要换一个新子代理

SKILL.md 的论证原文值得整段看:

You delegate tasks to specialized agents with isolated context. By precisely crafting their instructions and context, you ensure they stay focused and succeed at their task. They should never inherit your session's context or history — you construct exactly what they need.(你把任务委托给带隔离上下文的专门代理。通过精确构造它们的指令和上下文,你保证它们聚焦并完成自己的任务。它们永远不该继承你的会话上下文或历史——你构造它们需要的,仅此而已。)

公式就一句:每个任务一个新子代理 + 任务评审(规格 + 质量)+ 末尾全分支终审 = 高质量、快迭代。隔离是双向的:子代理不被你的历史污染,你的上下文也不被实现细节塞满——协调者的上下文要留着干协调的活。

还有一条贯穿全文的行为约束,官方写得很硬:不要在任务之间停下来问人类「要继续吗」。执行就是执行,只有四类事情必须停:不可逆或破坏性操作、安全敏感动作、工作区之外的副作用(合并、推共享分支、发布)、以及烂到每条路都是猜的计划缺陷。其余一切冲突自己裁决,裁决记进台账继续走。

什么时候用它,什么时候别用

SKILL.md 用一个决策图回答适配问题,三个判断就够了:有实施计划吗?任务之间大体独立吗?人类选择 inline 执行或者没有子代理工具吗?有计划、任务独立、有子代理工具——用它;三个条件缺任何一个,走隔壁的 executing-plans 技能 inline 执行,或者先回去做头脑风暴把计划做出来。

和 inline 执行的取舍,官方列了笔账:子代理模式每个任务一个新上下文外加一次评审上下文,成本高但每步都有独立质检;inline 一个上下文从头干到尾加末尾一次评审,便宜但中间无人把关。「任务高度耦合」是子代理模式的明确反指标——任务间要来回传大量上下文时,换人成本会吃掉隔离收益。

安装挂载与三个配套脚本

技能随 superpowers 仓库分发,克隆仓库、把 skills/ 目录挂进代理的技能搜索路径即可。它比别的技能多一样东西:scripts/ 目录下三个 bash 脚本,管的是「任务书怎么给、评审包怎么打包、工作区在哪」三件杂事:

bash scripts/sdd-workspace PLAN_FILE      # 解析(必要时创建)本计划专属工作区
bash scripts/task-brief PLAN_FILE N       # 把第 N 个任务的全文抽成独立文件
bash scripts/review-package PLAN_FILE BASE HEAD   # 生成评审包:commits+stat+diff 一个文件

三个脚本在本文的演示仓库里全部真实跑过,输出长这样:

SDD 三脚本实测输出

干净 git 仓库 + 双任务计划:工作区解析、任务书抽取、评审包生成的真实终端记录

注意 git status --short 那段空输出——工作区藏在 .superpowers/sdd/ 下,目录里自建了一个只写一行 * 的 .gitignore,整个杂项从版本控制里隐身,不污染你的提交。

用法一:台账(progress.md)防失忆

SKILL.md 里最重的一句话,来自真实事故:

Conversation memory does not survive compaction. In real sessions, controllers that lost their place have re-dispatched entire completed task sequences — the single most expensive failure observed.(会话记忆熬不过上下文压缩。真实会话里,迷路的协调者把整段已完成的任务序列重新派了一遍——这是观察到过的最贵失败。)

对策是台账文件。工作区里建 progress.md,首行写计划路径表明身份,之后每完成一个任务补一行,格式官方也定死了:`Task <N>: complete (commits <base7>..<head7>, review clean)`。断点续跑的规则跟着台账走:有 complete 行的任务绝不重派,从第一个没有该行的任务继续;某任务最后一行是修复轮次,说明它卡在循环里,从下一轮接着来。压缩过后,信台账和 git log,别信自己的记忆——这是原文原话。

用法二:一计划一工作区

sdd-workspace 脚本管隔离。每个计划按文件名 slug 在 .superpowers/sdd/ 下开一个专属目录,台账、任务书、报告、评审包全住里面。同名计划也不串门:目录里的 plan-path 标记记着主人的仓库相对路径,撞名时自动用父目录名消歧。实测里另一个目录 docs/other/feature-plan.md 的同名计划被解析到 feature-plan-other/,两个工作区互不可见。防的是 SKILL.md 里点名的故障:一个计划的协调者读到另一个计划的陈旧台账,误以为任务全完成,整段跳过。

SDD 工作区目录结构

一个计划的工作区全家福:归属标记、台账、任务书、评审包各有其位(实测产物)

有个坑脚本注释里直说了:git clean -fdx 会把这个目录连同台账一起清掉,因为它是 git 忽略的临时物。真被清了,恢复只能靠 git log 里的提交。

用法三:任务书只给该给的

派实现者之前先跑 task-brief,把第 N 个任务的全文从计划里抽成独立文件,派发时只给文件路径。官方对派发提示词的内容有明确配方:一句任务在项目里的位置、任务书路径(并声明「先读它,它是你的需求,数值照抄」)、前面任务定下的接口和决定、你注意到的歧义的处理、报告文件路径和报告契约。精确数值——数字、魔法字符串、签名、测试用例——只出现在任务书里,协调者不复述。

反面教材也有数据:一次真实会话的派发提示词堆到 42k 字符,99% 是粘贴的历史摘要。新子代理需要的是任务、接口、全局约束,就这三样。报告反过来也走文件:实现者把完整报告写进 task-N-report.md,会话里只回五行以内——状态、提交号、一行测试结论、疑虑、报告路径。

用法四:实现者报告的四种状态

实现者回来只有四种状态,每种有固定处置:DONE 就打包评审;DONE_WITH_CONCERNS 先读疑虑,正确性或范围问题要在评审前处理,纯观察记下照常评审;NEEDS_CONTEXT 补上下文重派;BLOCKED 按堵点分流——上下文不足补上下文重来,推理能力不够换更强模型,任务太大拆小,计划本身错了就先裁决修正记台账再带着裁决重派。官方跟了一句狠话:绝不无视升级,也绝不逼同一个模型什么都不改地重试——实现者说卡住了,那就是有东西得变。

用法五:任务评审的双重裁决

每个任务完成都要过一道评审,而且规格合规和代码质量两个裁决缺一不可,实现者自查永远不能替代这道评审。评审者拿到三样东西:任务书、实现者报告、评审包文件——diff 永远以文件形式交付,不进协调者上下文。

评审者模板里有两条很硬的规矩。其一,实现者的报告只是未经验证的说法:「left it per YAGNI」「kept it simple deliberately」这类自我辩护不算数,代码按本身的品质打分。其二,评审者遇到 diff 里断在函数中间看不全的情况可以单独读那个文件,但禁止爬整个代码库——每次越界检查必须先说出具体风险的名字。

SDD 任务循环流程图

从派发到终审的完整链路,依据 SKILL.md「The Process」结构绘制

用法六:修复循环与五轮熔断

评审报了规格不合规、Critical 或 Important 发现,进入修复循环。规则细但不乱:Minor 发现不进循环,记台账留给终审分诊;与计划文本冲突的发现归协调者裁决,裁决落台账后才动手;其余进循环。循环一轮 = 一次修复派发 + 一次范围受限的重评。前 1–3 轮唤醒原实现者——它的上下文还在,知道自己干过什么;4–5 轮换一个更强模型的新实现者,配的话术官方都写好了:「前一位实现者试了 N 次没过,现在归你,读报告文件看试过什么」。

每任务最多五轮,第五轮评审仍有未决发现就熔断。熔断后协调者逐条裁决:评审错了或有争议,挂起并写裁决理由;真实但下游没人依赖,同样挂起;真实且承载性——后面的任务建在它上面——只做最小改动解锁下游并记台账。全部路径都是猜的极端情况才停下来问人。裁决只许在熔断点做,提前裁决换汤不换药,还是预判。

用法七:模型选档,明写再派

派子代理必须显式指定模型,这条官方写成了加粗警告:漏写就继承会话模型——往往是最贵的那档,整节的省钱设计静默作废。选档逻辑按任务形态走:机械实现(规格完整、动一两个文件)用快而便宜的模型,计划写得好的话大多数实现任务都是机械的;多文件协调用标准模型;架构设计用最强模型,终审永远用最强档。修复循环第 4–5 轮至少比卡住的实现者高一档。

还有一条反直觉的账:轮次数比 token 单价更贵。最便宜的模型干多步任务经常多花两三倍的轮次,总成本反而更高——评审者和按散文描述干活的实现者,地板应该是中档模型。计划文本里已经带完整代码的任务是例外,那是照抄加测试,用最便宜的。

用法八:终审与收尾

全部任务完成后,用 requesting-code-review 技能的 code-reviewer 模板派终审——注意这是跨技能调用,模板文件在隔壁技能目录下。终审范围是整个分支,MERGE_BASE 用 git merge-base main HEAD 取分叉点,评审包照旧走文件。终审有发现的话只派一次修复(一个修复者拿全部发现清单,不按发现逐个派人——官方见过按发现派人的一场修复潮,成本超过全部任务之和),加一次范围重评,残余发现按熔断规则裁决。终审没有第二波修复,载重发现浮给人看,在收尾技能的选项菜单里由人类定夺。收尾交接给 superpowers:finishing-a-development-branch 技能,站内有专门一篇讲它。

删工作区之前还有最后一件事:把台账里所有含 Ruling 的行收集进最终消息,按裁决顺序列出,每条带上「错了的代价」。官方的措辞很重——这份清单是你替人类搭档做的决定到达他们眼前的唯一通道,随工作区消失的裁决等于秘密做的决定。

用法九:官方点名的九类自我合理化

SKILL.md 末尾的 Common Rationalizations 表有九行,每行一句借口配一句现实。挑四条最常踩的:

「规格差一点点,差不多得了」——评审发现规格缺口就是没完成,修或者撞到五轮上限后裁决,没有第三条路。「我自己修更快,派活太费事」——协调者亲自修污染上下文而且跳过评审,回到循环唤醒实现者。「再审一轮总会收敛的」——过了上限还不收敛说明失败是结构性的,裁决然后改道。「修复很小,重评就免了」——没人看的修复就是回归的入口,每轮都要过范围重评。

九条合起来其实就是一句话:流程里的每一步都有人想省,而每一步被省掉的方式都已经被试过、出过事故、写进了这张表。

写在最后

subagent-driven-development 的 568 行 SKILL.md 里没有一句空话:台账对应最贵的真实事故,五轮熔断对应无限循环的修复潮,模型选档对应静默烧钱的默认继承,九行对照表对应九种已经被证明会翻车的省事方案。把这套流程跑顺的标志不是快,而是每个任务留下四样东西:任务书、报告、评审包、一行台账——断点能续、裁决有据、终审有物可查。

本文步骤与配图依据 obra/superpowers 仓库 skills/subagent-driven-development 目录的 SKILL.md 及其三个配套脚本(main 分支,2026 年 10 月)整理,实测部分来自作者本地环境,版权归原作者所有。

评论 (0)