用途
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、频繁提交。
自审
写完完整计划后,用新鲜的视角对照规格检查计划。这是一份自己运行的清单,而不是派发子代理:
- 规格覆盖:浏览规格中每个章节/需求,能否指出实现它的任务?列出所有缺口。
- 占位符扫描:在计划中搜索上述「禁止占位符」中的模式,并修复。
- 类型一致性:后续任务中使用的类型、方法签名、属性名是否与前面任务中定义的一致?例如 Task 3 中叫 clearLayers() 而 Task 7 中叫 clearFullLayers() 就是 bug。
若发现问题,就地修复即可,无需重新审查。若发现某规格需求没有对应任务,就补上该任务。
执行交接
保存计划后,提供执行选择:
「Plan complete and saved to docs/superpowers/plans/<filename>.md. Two execution options:
- Subagent-Driven (recommended) - I dispatch a fresh subagent per task, review between tasks, fast iteration
- 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(批量执行,带检查点供审查)。
限制
资料未提供该技能的安装方式、平台要求、是否收费、具体版本信息或与其他技能的具体依赖关系细节;这些内容暂未提供。