SuperAPI AI 工具集

executing-plans

编程与开发

查看项目

更新于 10-14 14:35

技能介绍

用途

当你要在当前会话里亲自担任实现者执行一份实现计划时使用本技能——你的人类伙伴选择了内联执行,或者没有可用的子智能体工具。在本会话里亲自执行计划,一个任务接一个任务:不为每个任务派实现子智能体,也不为每个任务派审查者。只在最后对整个分支做一次全新上下文的审查。

为什么内联

子智能体驱动开发为每个任务付一个全新实现者和一个全新审查者的钱,每一个都要从零重读代码库。内联执行只付一个上下文(你自己的)外加最后一个审查者。它放弃的是每个任务一份全新上下文、每个任务第二双眼睛。本技能用别的办法保住那两样东西换来的好处:简报就是规格,账本就是你的记忆,TDD 是每个任务的关卡,最终审查者就是第二双眼睛。

核心原则

计划已经把该想的都想过了。严格照它执行,每一步都用一个你亲眼看着失败、又亲眼看着通过的测试来证明,并留下一份在你自己遗忘之后依然存在的记录。

工具调用之间最多说一句简短的旁白——账本和工具结果本身就是记录。

不要在任务之间停下来向你的人类伙伴确认。他们选内联执行是为了少花钱,不是为了每做完一个任务就回答一次“我该继续吗?”。不间断地执行计划里的所有任务。

做裁决,不要停摆。冲突、歧义、计划缺陷——你自己定。规格是有约束力的权威,计划是它的论证,两者都答不上来的部分由你的判断来定。每个决定都以 Ruling: <你决定了什么> — <为什么> — <如果错了代价是什么> 记进账本,然后继续。没有记进账本的裁决就偏离计划,等于一个暗中做出的决定。

只有四件事会让你停下,也只有这四件:不可逆或破坏性的操作;涉及安全的动作;这个工作树之外、按惯例应当先问一声的副作用(合并、推送到共享分支、发布);以及一个坏到每条前进路径都只能靠猜的计划。遇到这四类,停下来问。

何时使用

  • 你有一份来自 writing-plans 的计划,而你的人类伙伴在交接时选择了内联执行。
  • 你的运行环境没有子智能体工具。绝不编造一次分派;就在这里执行计划。
  • 任务基本相互独立——与 subagent-driven-development 的前提相同。

一份写得完整的计划,会让内联执行变成“照抄 + 测试”:它在中档的会话模型上就能跑得很好,而最强模型唯一值回票价的地方是最终审查——本技能会单独分派它。

当你的人类伙伴希望每个任务都有一道审查关卡,或者计划长到后面的任务会在压缩过的上下文上运行时,优先选 subagent-driven-development。在长计划上内联执行依然可行——账本让它可以恢复——但最后那几个任务分到的是最少的你。

流程

流程为一个 digraph(有向图),主要节点包括:准备(工作树、工作区 + 账本、读计划 + 规格、起飞前扫描);每个任务的循环(task-start:简报 + BASE、按顺序做各步 TDD 并对照 Expected、计划错则裁决记账、代码错则 systematic-debugging、按计划提交、完成契约检查、task-done 跑测试并记账);还有任务判断;最终整分支审查(有条件就用全新审查者);重新定级与修复;最终审查干净后删除本计划的工作区;最后使用 finishing-a-development-branch。

准备

确保工作发生在一个隔离的工作区里:用 using-git-worktrees 创建一个,或者核实已有的那个。未经你的人类伙伴明确同意,绝不在 main/master 分支上开始实现。

会话记忆无法在上下文压缩(compaction)中存活。把进度记在一个账本文件里,而不只是记在待办里。运行环境的待办只是实时视图;账本才是记录。

工作区和账本与 subagent-driven-development 共用——同一个目录、同一种格式——所以一个计划可以在执行中途换执行方式。

每个计划拥有自己的工作区:技能启动时,运行 ../subagent-driven-development/scripts/sdd-workspace PLAN_FILE——它会打印这个计划专属的、被 git 忽略的目录(<repo-root>/.superpowers/sdd/<计划文件名>/),本计划的一切产物都放在那里:账本、简报、审查包。

到 <工作区>/progress.md 查本计划的账本。如果它的第一行点名的是你的计划文件,那么带有 Task <N>: complete 行的任务就是已完成——不要重做;从第一个没有该行的任务处继续。

创建账本时,把它的身份写在第一行:# SDD ledger — plan: <计划文件路径>。

把计划读一遍,记下它的上下文和全局约束,并为每个任务建一条待办。如果计划点名了一份规格(Spec),把规格也读了。

必需子技能:现在、在任务 1 之前,加载 test-driven-development。

任务 1 之前,扫描计划中任务之间的冲突。计划的 Interfaces 块告诉你该看哪里。以规格为有约束力的权威,对每一行翻出的冲突作出裁决,把裁决记在那一行旁边,然后开始任务 1。

任务循环

运行本技能的 scripts/task-start PLAN_FILE N。它一次调用就打印出简报路径和 BASE。每个任务都要读简报。把该任务的待办标为 in_progress。记账顺着干活一起做。

计划的步骤已经是 RED-GREEN 的顺序;按这个顺序做。每个会运行命令的步骤都有一行 Expected:。运行命令,读它的输出,然后对照。三种结果:一致(下一步);代码错了(使用 systematic-debugging);计划错了(对能满足规格的最小改动作出裁决并记进账本)。

按计划的提交步骤提交。一个任务跨好几个提交没问题;审查范围从 BASE 切出,绝不用 HEAD~1。

完成契约:在一个任务写账本行之前,简报点名的每一个测试都存在、都在本任务中跑过并读输出;本任务最后一次测试运行通过;每一行 Expected: 都和真实输出对照过;每一处偏离都有 Ruling: 行。必需子技能:这个声明由 verification-before-completion 管辖。

完成任务:运行本技能的 scripts/task-done PLAN_FILE N BASE -- <测试命令>。只有在测试通过时,才往账本追加完成行。

最终审查

运行 ../subagent-driven-development/scripts/review-package PLAN_FILE MERGE_BASE HEAD(MERGE_BASE = 分支起点的那个提交,例如 git merge-base main HEAD),并基于它打印出的文件做审查。

有子智能体工具时:在可用的最强模型上分派审查者,使用 requesting-code-review 的 code-reviewer.md,附上审查包路径、计划和规格的路径、计划的「审查重点(Review Focus)」一节原文照录,以及一个指向账本中 Ruling: 行的指针。显式指定模型。

没有子智能体工具时:读 code-reviewer.md,并在最后一个任务的账本行之后,作为单独的一轮,自己对着审查包做那次审查。往账本写 Final review: self-review (no subagent tool),并说明作者自审比全新审查者弱,合并前是否足够由人类伙伴决定。

在对任何一条发现动手之前,先把它们分拣好。审查者的严重程度标签只是建议;关卡在你手里。先按影响重新定级。然后:Critical 和 Important 进入修复轮;Minor 以 Final: minor (deferred) 记进账本。

Critical 和 Important 发现由你自己修——一轮修完。每个修复由 TDD 验证:写出复现该发现的测试,看着它失败,让它通过,然后跑整个套件。不要分派复审。

一条你决定不修的发现,就是一个裁决——Final: Ruling: <发现> — <为什么代码可以维持原样> — <如果错了代价是什么>——它会通过裁决清单送到你的人类伙伴面前。没有第二轮修复。

收尾

在删除任何东西之前,把账本里所有含 Ruling: 的行按顺序收集到最终消息的“我作出的裁决”一节;把每一行 minor (deferred) 收集到“延后的 Minor”一节。两份清单都必须完整。

最终审查干净、它的修复都已提交后,删除本计划的工作区目录——现在 git 历史就是记录。同级目录属于其他计划;别碰它们。使用 finishing-a-development-branch。

常见的合理化借口

技能列出多条借口与现实对照,例如:“我记得任务 N 说了什么”——现实是你记得的是摘要,简报里有精确取值;“计划里的代码是对的,跳过看测试失败这一步”——一个你从没见它失败过的测试什么也证明不了;“我最后再跑全套件,不用每一步都跑”——每步都跑,你才知道是哪一步弄坏的;“这里计划错了,我直接做对的就行”——做对的,并且把裁决记进账本;“我做完几个任务再补账本行”——压缩不会挑一个方便的时机;“我已经仔细读过自己的 diff,最终审查者是多余的”——同一个作者,同样的盲区;“审查者说是 Minor,那就是 Minor”——评一评使用者会得到什么,先重新定级;“我顺手把 Minor 也修了吧”——记进账本,由你伙伴决定,等等。

适用场景与限制

适用于有完整计划、任务基本相互独立、在无子智能体工具或选择内联执行时。需要具备 Git 工作树、账本机制以及相关配套技能(test-driven-development、verification-before-completion、systematic-debugging、finishing-a-development-branch 等)。最终审查在无子智能体工具时只能作者自审,强度较弱,是否足以合并由人类伙伴决定。具体平台参考、脚本实现细节与目录结构依原始技能文档而定,本介绍未展开的部分暂未提供。