writing-plans

编写计划

概述

为没有见过本代码库或本规格的工程师编写实现计划。假设他们一旦知道确切的接口和确切的测试，就能用项目所用语言编写符合惯用写法的代码，并且在计划留白之处会做出合理的选择。他们无法知道的是你做过的决定：涉及哪些文件、哪些名称和签名、规格中的哪些值，以及哪些测试能证明每个任务。请把这些都写明。将整个计划拆分为便于执行的小任务。DRY。YAGNI。TDD。频繁提交。

开始时声明： "我正在使用 writing-plans skill 创建实现计划。"

上下文： 如果在隔离的 worktree 中工作，该 worktree 应在执行时通过 superpowers:using-git-worktrees skill 创建。

计划保存位置： docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md

• （用户的位置偏好优先于此默认值）

范围检查

如果规格涵盖多个相互独立的子系统，则在头脑风暴阶段就应将其拆分为子项目规格。如果没有拆分，请建议将其拆为多个计划，每个子系统一个。每个计划都应能独立产出可运行、可测试的软件。

文件结构

在定义任务之前，先梳理将要创建或修改哪些文件，以及每个文件负责什么。这一步决定了拆分方案，之后便不宜再随意更改。

• 设计边界清晰、接口明确的单元。每个文件只承担一项明确的职责。
• 你在能一次装入上下文的代码上推理效果最好，而且文件越聚焦，编辑越可靠。优先选择小而专注的文件，而不是什么都做的大文件。
• 一起变化的文件应放在一起。按职责拆分，而不是按技术层拆分。
• 在已有代码库中，应遵循既有模式。如果代码库使用大文件，不要擅自重构；但如果你要修改的文件已经变得难以维护，在计划中包含拆分方案是合理的。

此结构决定任务的拆分方式。每个任务都应产出可独立理解的自包含变更。

任务粒度控制

任务是最小的、拥有自身测试周期、并且值得让一位新的审查者把关的单元。划分任务边界时：将环境搭建、配置、脚手架和文档步骤并入需要它们的那个任务中；只有当审查者可以合理地驳回某一任务而同时批准相邻任务时，才进行拆分。每个任务都应以一个可独立测试的交付物结束。

步骤粒度

每个步骤是一个具有可检查结果的动作：

• "编写失败的测试"，为一个步骤
• "运行测试，确认其失败"，为一个步骤
• "实现使测试通过的最小代码"，为一个步骤
• "运行测试，确认全部通过"，为一个步骤
• "提交"，为一个步骤

计划文档头部

每份计划都必须以以下头部开始：

# [Feature Name] Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** [One sentence describing what this builds]

**Architecture:** [2-3 sentences about approach]

**Tech Stack:** [Key technologies/libraries]

**Spec:** [path to the spec/design doc this plan implements — the plan
argues from the spec, so the spec travels with it; executors read both]

## Global Constraints

[The spec's project-wide requirements — version floors, dependency limits,
naming and copy rules, platform requirements — one line each, with exact
values copied verbatim from the spec. Every task's requirements implicitly
include this section.]

## Review Focus

[The five input classes or failure modes the spec implies but no task's
tests exercise that are most likely to bite a person using this software
— one line each, naming the input or condition and the behavior a
reasonable person would expect, most likely first. The spec is a vision
document: it says what the software must do, not everything it will
meet, and its silence on an input is not permission for that input to
break the program. Write the list here, once, with the spec in front of
you. Then, for each line, add the test that pins it to the task that
owns the code, in that task's own step style.]

---

任务结构

### 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`

**Interfaces:**
- Consumes: [what this task uses from earlier tasks — exact signatures]
- Produces: [what later tasks rely on — exact function names, parameter
  and return types. A task's implementer sees only their own task; this
  block is how they learn the names and types neighboring tasks use.]

- [ ] **Step 1: Write the failing test**

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

- [ ] **Step 2: Run test to verify it fails**

Run: `pytest tests/path/test.py::test_name -v`
Expected: FAIL with "function not defined"

- [ ] **Step 3: Implement `function(input: InputType) -> ResultType` in `exact/path/to/file.py`**

One line on the approach when the signature and the test leave a choice
(which library call, which data structure); a code block only for an
algorithm they do not determine.

- [ ] **Step 4: Run test to verify it passes**

Run: `pytest tests/path/test.py::test_name -v`
Expected: PASS

- [ ] **Step 5: Commit**

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

步骤包含什么

当实现者能从某个步骤中写出且只写出一种合理的结果时，该步骤即算完成。这就是全部要求：无歧义，但不必完整。每类步骤只需包含使其无歧义的内容，不多不少：

• 测试步骤： 测试名称及其断言，以代码形式给出，并包含规格中的精确值。
• 代码步骤： 精确的签名（名称、参数、返回类型）、所在文件，以及规格固定的具体值。函数体由实现者编写。只有在签名和测试无法确定的算法，或规格固定的精确文案时，才给出函数体。
• 验证步骤： 要运行的命令，以及表示通过的输出。
• 对其他任务的引用： 该任务的 Interfaces 块说明应使用什么；计划不重复该任务的代码。

计划是实现者无法独自做出的一组决策。如果计划比它所描述的代码还长，说明它已经把代码写了一遍。无法作出任何决定的内容（如“待定”、“处理边界情况”、“添加适当的校验”、“为上述内容编写测试”，或引用了任何任务都未定义的类型或函数）则是相反的问题，自我审查会同时发现这两类错误。

自我审查

完成整份计划后，以全新的视角重新审视规格，并对照规格检查计划。这是你自己执行的检查清单，不是子 Agent 调度。

1. 规格覆盖： 浏览规格中的每个章节或需求。你能否指出哪个任务实现了它？列出所有遗漏。

2. 步骤扫描： 每个步骤都必须让实现者写出且只写出一种合理的结果，且步骤不得包含超出此范围的内容：一行不做任何决定的文字即是缺口，签名和测试已经确定的函数体则是誊抄。两者都需修正。

3. 类型一致性： 后面任务中使用的类型、方法签名和属性名，是否与前面任务中定义的一致？如果任务 3 中的函数叫 clearLayers()，而任务 7 中叫 clearFullLayers()，这就是一个 bug。

4. 审查重点： 对于规格所隐含的每一类输入或故障模式，是否有某个任务的测试覆盖了它？最可能给人带来麻烦的五个未覆盖项应列入“审查重点”一节，且该节中的每一行都要把对应测试添加到所属任务中。该节为空，意味着你已检查过且没有发现问题，而不是跳过了检查。

5. 篇幅比例： 比较计划与规格的长度。如果计划的篇幅是其所实现规格的数倍，那它就是程序的誊写稿，而不是计划。如果代码块占据了文档的大部分，请用签名、测试名称和断言替换函数体，并确认每个步骤仍然无歧义。

如果发现问题，直接在原处修正。无需重新审查，修正后继续即可。如果发现某条规格需求没有对应任务，就补充该任务。

执行交接

保存并自我审查计划后，将其链接提供给你的人类协作者阅读。如果对方已明确提供执行方式，请其审阅计划，确认计划涵盖了其所需内容；在其完成审阅前不要开始实现，然后使用已保留的执行方式。否则，请其审阅计划，并在实现前选择执行方式。

未提供执行方式时：

"计划已完成并保存至 docs/superpowers/plans/<filename>.md。请审阅该计划。你更倾向于哪种执行方式？

• 子 Agent 驱动：每个任务由一个全新的子 Agent 实现，之后在进入下一个任务前由一个全新的审查者检查，最后进行整个分支的审查。最为全面；每个任务和每次审查都需要一个全新的上下文，成本较高。
• 原生：由我在本会话中亲自实现每个任务，采用此运行环境的常规方式，然后由一个使用最强模型的全新审查者对整个分支进行检查。成本最低、速度最快；在最终审查前没有独立审查。配合中等水平的会话模型运行效果良好，因为计划已包含设计方案。

因为 ，我推荐 <一句话说明来自计划的理由：任务之间对彼此接口的依赖程度、任务数量、交付错误的代价>。计划是否符合你的预期？你希望采用哪种执行方式？"

已提供执行方式时：

"计划已完成并保存至 docs/superpowers/plans/<filename>.md。请审阅该计划。它是否符合你的预期？"

如果选择子 Agent 驱动：

• 必需子技能： 使用 superpowers:subagent-driven-development

如果选择原生：

• 必需子技能： 使用 superpowers:executing-plans