SuperAPI AI 工具集

writing-plans

编程与开发

查看项目

更新于 10-16 14:20

技能介绍

用途

writing-plans 用于在动手写代码之前,为多步骤任务编写完整的实施计划。适用于你已经有某个功能的规格或需求、需要把它转化为可执行步骤的场景。该技能假设执行计划的工程师对我们的代码库几乎没有上下文,因此要求把一切必要信息写清楚:每个任务要改动哪些文件、代码内容、测试、可能需要查阅的文档,以及如何测试。

开始时应声明:「I'm using the writing-plans skill to create the implementation plan.」该技能建议在由 brainstorming 技能创建的专用 worktree 中运行。

计划保存位置

计划默认保存到 docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md。用户对计划位置的偏好会覆盖此默认值。

范围检查

如果规格覆盖多个相互独立的子系统,本应在 brainstorming 阶段拆分为子项目规格。如果没有拆分,应建议拆成多个计划,每个子系统一个。每个计划都应能独立产出可工作、可测试的软件。

文件结构规划

在定义任务之前,先规划哪些文件将被创建或修改,以及每个文件的职责。这是锁定分解决策的环节。设计要求单元具有清晰边界和明确定义的接口,每个文件应有单一清晰职责。理由是:你能最好地思考能一次性放入上下文的代码,文件聚焦时编辑更可靠,因此倾向于更小、更聚焦的文件。一起变更的文件应放在一起,按职责而非技术层拆分。在既有代码库中应遵循既有模式;若代码库使用大文件,不要单方面重构,但若正在修改的文件已变得难以维护,在计划中包含拆分是合理的。该结构会影响任务分解,每个任务应产出可独立理解的、自包含的变更。

任务粒度

每个步骤是一个动作(2-5 分钟),例如:写失败的测试、运行并确认失败、实现最小代码让测试通过、运行测试确认通过、提交。

计划文档头部

每个计划必须以指定头部开头,包含:功能名称、面向 agentic workers 的说明(要求使用 superpowers:subagent-driven-development 或 superpowers:executing-plans,并按任务逐步执行,使用复选框 - [ ] 语法跟踪进度)、Goal(一句话说明构建什么)、Architecture(2-3 句说明方法)、Tech Stack(关键技术/库)。

任务结构

任务采用如下结构:

Task N: [Component Name]

Files:

  • Create: exact/path/to/file.py

  • Modify: exact/path/to/existing.py:123-145

  • Test: tests/exact/path/to/test.py

  • [ ] Step 1: Write the failing test(含具体测试代码)

  • [ ] Step 2: Run test to verify it fails(含运行命令与预期失败信息)

  • [ ] Step 3: Write minimal implementation(含具体实现代码)

  • [ ] Step 4: Run test to verify it passes(含运行命令与预期结果)

  • [ ] Step 5: Commit(含具体 git add 与 git commit 命令)

禁止占位符

每个步骤必须包含工程师所需的实际内容。以下属于计划失败,永远不要写:

  • 「TBD」「TODO」「implement later」「fill in details」
  • 「Add appropriate error handling」/「add validation」/「handle edge cases」
  • 「Write tests for the above」(没有实际测试代码)
  • 「Similar to Task N」(要重复写出代码,因为工程师可能不按顺序阅读任务)
  • 只描述做什么却不展示怎么做的步骤(涉及代码的步骤必须给出代码块)
  • 引用任何任务中都未定义的类型、函数或方法

要点提醒

始终使用精确的文件路径;每个步骤包含完整代码——若某步骤修改代码,就展示代码;给出精确命令与预期输出;遵循 DRY、YAGNI、TDD、频繁提交。

自审

写完完整计划后,用新鲜的视角对照规格检查计划。这是一份自己运行的清单,而不是派发子代理:

  1. 规格覆盖:浏览规格中每个章节/需求,能否指出实现它的任务?列出所有缺口。
  2. 占位符扫描:在计划中搜索上述「禁止占位符」中的模式,并修复。
  3. 类型一致性:后续任务中使用的类型、方法签名、属性名是否与前面任务中定义的一致?例如 Task 3 中叫 clearLayers() 而 Task 7 中叫 clearFullLayers() 就是 bug。

若发现问题,就地修复即可,无需重新审查。若发现某规格需求没有对应任务,就补上该任务。

执行交接

保存计划后,提供执行选择:

「Plan complete and saved to docs/superpowers/plans/<filename>.md. Two execution options:

  1. Subagent-Driven (recommended) - I dispatch a fresh subagent per task, review between tasks, fast iteration
  2. Inline Execution - Execute tasks in this session using executing-plans, batch execution with checkpoints

Which approach?」

若选择 Subagent-Driven:REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development(每个任务一个新子代理 + 两阶段审查)。

若选择 Inline Execution:REQUIRED SUB-SKILL: Use superpowers:executing-plans(批量执行,带检查点供审查)。

限制

资料未提供该技能的安装方式、平台要求、是否收费、具体版本信息或与其他技能的具体依赖关系细节;这些内容暂未提供。