Writing Plans

---

name: superpowers-writing-plans description: Use when you have a spec or requirements for a multi-step task, before touching code - guides writing comprehensive implementation plans with bite-sized tasks, TDD, and DRY/YAGNI principles

---

Superpowers Writing Plans - 写实现计划

概述

写全面的实现计划，假设执行者对代码库零上下文、品味可疑。记录他们需要知道的一切：每个任务要修改的文件、代码、可能需要检查的测试和文档、如何测试。给出完整计划为小粒度任务。DRY。YAGNI。TDD。频繁 commit。

假设执行者是个有技能的开发者，但几乎不了解我们的工具集或问题领域。假设他们不太懂好的测试设计。

开始时宣布： "我正在用 writing-plans 技能创建实现计划。"

上下文： 这应该在专门的工作目录中运行（由 brainstorming 技能创建）。

保存计划到： docs/superpowers/plans/YYYY-MM-DD-.md

范围检查

如果规格涵盖多个独立子系统，应该在 brainstorming 阶段已分解为子项目规格。如果没有，建议分解为独立计划——每个子系统一个。每个计划应产生可工作、可测试的软件。

文件结构

在定义任务之前，映射哪些文件将被创建或修改，每个文件负责什么。这是分解决策被锁定的地方。

用清晰边界和定义好接口的设计单元。每个文件应该有一个明确职责。

你能放进脑子里的代码你推理得最好，编辑也更可靠。偏好更小、专注的文件，不要大的什么都做的文件。

一起变更的文件应该放一起。按职责拆分，不是按技术层。

现有代码库中，遵循已有模式。如果代码库用大文件，不要单方面重构——但如果修改的文件已经长得太大，在计划中包含拆分是合理的。

这个结构指导任务分解。每个任务应该产生能独立理解的有意义的变更。

小粒度任务

每步是一个动作（2-5 分钟）：

"写失败的测试" — 一步

"运行确保它失败" — 一步

"写最少代码让测试通过" — 一步

"运行确保测试通过" — 一步

"Commit" — 一步

计划文档头部

每个计划必须以此头部开始：

# [功能名] 实现计划
目标： [一句话描述构建内容]
架构： [2-3 句话描述方法]
技术栈： [关键技术和库]

任务结构

### 任务 N：[组件名]
文件：
创建：exact/path/to/file.py
修改：exact/path/to/existing.py:123-145
测试：tests/exact/path/to/test.py
[ ] 步骤 1：写失败的测试

python def test_specific_behavior(): result = function(input) assert result == expected

[ ] 步骤 2：运行测试验证它失败
运行：pytest tests/path/test.py::test_name -v
预期：FAIL，错误信息 "function not defined"
[ ] 步骤 3：写最少的实现代码

python def function(input): return expected

[ ] 步骤 4：运行测试验证它通过
运行：pytest tests/path/test.py::test_name -v
预期：PASS
[ ] 步骤 5：Commit

bash git add tests/path/test.py src/path/file.py git commit -m "feat: add specific feature"

无占位符

每步必须包含执行者需要的实际内容。以下是计划失败——永远不要写：

"TBD"、"TODO"、"稍后实现"、"填细节"

"添加适当的错误处理"/"添加验证"/"处理边界情况"

"为上述写测试"（没有实际测试代码）

"类似于任务 N"（重复代码——执行者可能按顺序读任务）

描述做什么而不展示怎么做的步骤（代码步骤必须有代码块）

引用任何任务中未定义的类型、函数或方法

自审

写完完整计划后，用新眼光看规格并检查计划：

1. 规格覆盖： 浏览规格每个部分/需求。能指向实现它的任务吗？列出任何缺口。

2. 占位符扫描： 在计划中搜索红旗——上述"无占位符"部分的任何模式。修复它们。

3. 类型一致性： 在后续任务中使用的类型、方法签名和属性名与前面定义的一致吗？任务 3 中的 clearLayers() 和任务 7 中的 clearFullLayers() 是 bug。

发现问题，内联修复。不需要重新审查——修复并继续。如果发现规格需求没有任务，加任务。

工作目录说明（OpenClaw 适配）

Superpowers 原版使用 git worktree 做隔离工作区。在 OpenClaw 环境中：

使用 git branch 创建特性分支

在分支上工作，完成后 merge 或 PR

保持工作目录整洁，与主分支隔离

工作流程：

# 从当前分支创建特性分支
git checkout -b feature/
实现（按计划任务）
...
完成时
git checkout main && git merge feature/

执行移交

保存计划后，提供执行选择：

"计划写完保存到 docs/superpowers/plans/.md。两种执行选项：

1. 子 Agent 驱动（推荐） — 我为每个任务 dispatch 新的 subagent，任务间审查，快速迭代

2. 顺序执行 — 在本 session 按批次执行任务，有审查检查点

选择哪种？"

如果选择子 Agent 驱动：

需要 superpowers-subagent-dev 技能

每个任务新鲜 subagent + 两阶段审查

如果选择顺序执行：

在本 session 按计划任务顺序执行

每个任务后运行验证

完成后调用 superpowers-finishing-branch 清理