SuperAPI AI 工具集

writing-plans

编程与开发

查看项目

更新于 10-15 10:24

技能介绍

该技能用于在动手写代码之前,为多步骤任务编写实施方案(implementation plan)。适用时机是:已经有一份规格或需求说明,任务是多步骤的,且尚未触碰代码。开始使用时应宣告:"I'm using the writing-plans skill to create the implementation plan."

用途与目标

为一位从未见过该代码库或该规格说明的工程师编写实施计划。假定他们了解项目所用语言,只要知道确切的接口和确切的测试,就能写出符合语言习惯的代码;当计划留有选择空间时,他们会做出合理选择。他们无法知道的是你所做的决定:涉及哪些文件、使用哪些名称与签名、需求中的取值、证明每项任务的测试。计划的作用就是把这些记录下来,并以小步任务的形式呈现。原则为 DRY、YAGNI、TDD、频繁提交。

保存位置

计划保存到 docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md。用户对计划位置的偏好优先于此默认值。若在隔离的 worktree 中工作,应符合执行时的 superpowers:using-git-worktrees 技能要求。

范围检查

如果规格覆盖多个相互独立的子系统,应在头脑风暴阶段拆分为子项目规格。如果未拆分,建议拆成多个计划,每个子系统一个。每份计划应能独立产出可运行、可测试的软件。

文件结构

在定义任务之前,先规划哪些文件将被创建或修改,以及各自负责什么,分解决策在此确定。设计边界清晰、接口明确的单元,每个文件只有一项明确职责。优先选择较小、聚焦的文件,而非承担过多职责的大文件。一起变更的文件应放在一起,按职责而非技术层次拆分。在既有代码库中遵循既有模式;若代码库使用大文件,不要单方面重构,但若正在修改的文件已过于臃肿,可在计划中纳入拆分。该结构决定任务分解,每项任务应产出可独立成立的、自包含的变更。

任务规模

任务是带有自身测试周期、值得由一名全新审查者把关的最小单元。划分任务边界时:把设置、配置、脚手架和文档步骤并入需要其交付物的任务;只在审查者可以有意义地拒绝一项任务却批准相邻任务时才拆分。每项任务以可独立测试的交付物结束。

步骤粒度

每一步是一个有可检查结果的动作,例如:"Write the failing test"、"Run it to make sure it fails"、"Implement the minimal code to make the test pass"、"Run the tests and make sure they pass"、"Commit"。

计划文档头部

每份计划必须以指定头部开始,包含:标题、面向代理执行的必需子技能提示(superpowers:subagent-driven-development 或 superpowers:executing-plans)、使用复选框语法跟踪步骤、Goal(一句话说明构建内容)、Architecture(2-3 句说明方法)、Tech Stack(关键技术/库)、Spec(本计划实现的规格/设计文档路径,计划从规格论证,故规格随行,执行者需同时阅读两者)。随后是 Global Constraints(规格中项目级要求,如版本下限、依赖限制、命名与文案规则、平台要求,每项一行,取值逐字复制自规格;每项任务的要求隐含包含本节)与 Review Focus(规格暗示但没有任何任务的测试覆盖的、最可能影响使用者的输入类别或失效模式,每项一行,命名输入或条件及合理预期行为,最可能的在前;写完清单后,为每一行在拥有该代码的任务中按其步骤风格补上对应测试)。

任务结构

每个任务包含:Task N: [Component Name];Files(Create、Modify、Test 的确切路径);Interfaces(Consumes:本任务使用此前任务的什么,给出确切签名;Produces:后续任务依赖什么,给出确切函数名、参数与返回类型;任务实现者只看到自己的任务,此块用于了解相邻任务使用的名称与类型);随后是带复选框的步骤。

每一步的内容

当实现者能从中写出唯一一件合理的事时,这一步就完成了。要求是无歧义,而非完整。测试步骤:以代码给出测试名称与断言,包含规格中的确切取值。代码步骤:给出确切签名(名称、参数、返回类型)、所在文件及规格固定的具体取值,函数体由实现者编写;仅当签名与测试未确定算法,或规格固定了确切文案时才给出函数体。验证步骤:给出要运行的命令及表示通过的结果。引用其他任务:由该任务的 Interfaces 块说明使用什么,计划不重复其代码。计划是实现者无法独自做出的决策集合;比所描述代码还长的计划等于把代码写了出来;不决定任何内容的行(如 "TBD"、"handle edge cases"、"add appropriate validation"、"write tests for the above"、未被任何任务定义的类型或函数)则是相反的失败,自审会同时捕捉两者。

自审

写完完整计划后,以新鲜视角对照规格检查,这是自查清单,不需要派发子代理:1. 规格覆盖:浏览规格各节/要求,能否指向实现它的任务,列出缺口。2. 步骤扫描:每一步都必须让实现者写出唯一一件合理的事,不得承载更多;不决定任何内容的行是缺口,签名与测试已确定的函数体是转录,两者都要修正。3. 类型一致性:后续任务使用的类型、方法签名与属性名是否与前面任务定义的一致(如 Task 3 叫 clearLayers() 而 Task 7 叫 clearFullLayers() 就是 bug)。4. Review Focus:规格暗示的每个输入类别或失效模式,是否有任务的测试覆盖它;最可能影响使用者的五个未覆盖项放入 Review Focus 一节,每行对应测试加到拥有该代码的任务;空节表示已检查且未发现,而非跳过检查。5. 比例:比较计划长度与规格长度,比规格长数倍的计划是程序转录而非计划;若代码块占文档大部分,把函数体替换为签名、测试名与断言,并检查每一步是否仍无歧义。发现问题就地修复,无需重新审查;若发现规格要求无对应任务,补上任务。

执行交接

保存并自审计划后,将计划链接给人类伙伴阅读。若对方已明确给出执行方式,请其审阅计划并确认是否表达了想要的内容,等待该审阅后再实施,然后使用已保留的方式。否则,请其审阅计划并在实施前选择执行方式。未提供执行方式时的提示语包含:计划已保存到 docs/superpowers/plans/<filename>.md,请审阅;两种方式——Subagent-driven(每个任务由全新子代理实现,下一任务开始前由全新审查者检查,最后做整分支审查,最彻底,但每任务与每次审查都消耗新上下文)与 Native(本人在本会话中实现每个任务,最后用最强模型上的全新审查者检查整个分支,最省最快,直到最后才独立审查;适合中档会话模型,因为计划承载了设计)。并给出推荐及理由(一句话:任务间接口依赖程度、任务数量、发布后错误的代价)。若已提供执行方式:计划完成后请对方审阅并确认是否表达了其想要的内容。若选择 Subagent-driven,必需子技能为 superpowers:subagent-driven-development;若选择 Native,必需子技能为 superpowers:executing-plans。

适用场景与限制

适用于已有规格或需求说明、任务为多步骤、尚未触碰代码时编写实施计划。限制与边界:具体收费、价格、平台支持与效果等事实资料暂未提供;计划位置默认值可被用户偏好覆盖;在既有代码库中不应单方面重构大文件;本技能不执行实现,仅产出计划并进行执行交接。