superpowers-writing-plans

by axelhu

Install this Skill

curl -fsSL -o superpowers-writing-plans.zip https://skill.seembox.com/api/v1/skills/superpowers-writing-plans/download && unzip superpowers-writing-plans.zip

Download superpowers-writing-plans.zip

SKILL.md About

---
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-<feature-name>.md`

## 范围检查

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

## 文件结构

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

- 用清晰边界和定义好接口的设计单元。每个文件应该有一个明确职责。
- 你能放进脑子里的代码你推理得最好，编辑也更可靠。偏好更小、专注的文件，不要大的什么都做的文件。
- 一起变更的文件应该放一起。按职责拆分，不是按技术层。
- 现有代码库中，遵循已有模式。如果代码库用大文件，不要单方面重构——但如果修改的文件已经长得太大，在计划中包含拆分是合理的。

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

## 小粒度任务

**每步是一个动作（2-5 分钟）：**
- "写失败的测试" — 一步
- "运行确保它失败" — 一步
- "写最少代码让测试通过" — 一步
- "运行确保测试通过" — 一步
- "Commit" — 一步

## 计划文档头部

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

```markdown
# [功能名] 实现计划

**目标：** [一句话描述构建内容]

**架构：** [2-3 句话描述方法]

**技术栈：** [关键技术和库]

---
```

## 任务结构

```markdown
### 任务 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
- 保持工作目录整洁，与主分支隔离

**工作流程：**
```bash
# 从当前分支创建特性分支
git checkout -b feature/<feature-name>

# 实现（按计划任务）
# ...

# 完成时
git checkout main && git merge feature/<feature-name>
```

## 执行移交

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

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

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

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

**选择哪种？"**

**如果选择子 Agent 驱动：**
- 需要 `superpowers-subagent-dev` 技能
- 每个任务新鲜 subagent + 两阶段审查

**如果选择顺序执行：**
- 在本 session 按计划任务顺序执行
- 每个任务后运行验证
- 完成后调用 `superpowers-finishing-branch` 清理

_meta.json Metadata

{
  "ownerId": "kn7bcaearb90wwcjbr9gpv32s5831k39",
  "publishedAt": 1774515926564,
  "slug": "superpowers-writing-plans",
  "version": "1.0.1"
}