---
name: writing-plans
description: 当你已有多步骤任务的规格说明或需求时，在接触代码之前使用
---

# 编写计划

## 概述

编写全面的实施计划，并假设工程师对我们的代码库毫无了解且品味堪忧。记录他们需要知道的一切：每项任务要修改哪些文件、代码、测试、可能需要查阅的文档，以及如何进行测试。将完整计划拆成小块任务交给他们。DRY。YAGNI。TDD。频繁提交。

假设他们是技能娴熟的开发者，但对我们的工具集或问题领域几乎一无所知。假设他们不太懂良好的测试设计。

**开始时宣布：**“我正在使用 writing-plans 技能来创建实施计划。”

**上下文：**如果在隔离的工作树中工作，它应当已在执行时通过 `superpowers:using-git-worktrees` 技能创建。

**将计划保存至：**`docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md`
- （用户对计划位置的偏好会覆盖此默认值）

## 范围检查

如果规格说明涵盖多个相互独立的子系统，则在头脑风暴期间就应该已将其拆分为多个子项目规格说明。如果尚未拆分，建议将其拆成单独的计划——每个子系统一份。每份计划都应独立产出可运行、可测试的软件。

## 文件结构

在定义任务之前，梳理将创建或修改哪些文件，以及每个文件负责什么。分解决策将在这里确定下来。

- 设计边界清晰且接口定义明确的单元。每个文件都应只有一项明确的职责。
- 对于能够一次纳入上下文的代码，你的推理效果最佳；当文件职责聚焦时，你的编辑也更可靠。相比庞大且承担过多职责的文件，应优先选择更小、更聚焦的文件。
- 会一起变更的文件应该放在一起。按职责拆分，而不是按技术层拆分。
- 在现有代码库中，遵循既有模式。如果代码库使用大文件，不要单方面重构——但如果你正在修改的文件已经变得难以驾驭，那么在计划中加入拆分是合理的。

此结构会为任务分解提供依据。每项任务都应产出自包含的变更，且这些变更本身应独立合理。

## 任务大小适配

任务是具备自身完整测试周期、且值得由一位新的审查者设置一道关卡的最小单元。划分任务边界时：将设置、配置、脚手架和文档步骤并入其可交付成果需要这些步骤的任务中；仅当审查者能够有意义地拒绝一个任务、同时批准其相邻任务时才进行拆分。每项任务都以可独立测试的可交付成果结束。

## 小块任务粒度

**每个步骤都是一个操作（2-5 分钟）：**
- “编写失败的测试”——一个步骤
- “运行它以确保它失败”——一个步骤
- “实现让测试通过所需的最少代码”——一个步骤
- “运行测试并确保它们通过”——一个步骤
- “提交”——一个步骤

## 计划文档标题
**每个计划都必须以此标题开头：**

```markdown
# [功能名称] 实施计划

> **面向 Agent 型工作者：** 必需的子技能：使用 superpowers:subagent-driven-development（推荐）或 superpowers:executing-plans 来逐项任务实施此计划。步骤使用复选框（`- [ ]`）语法进行跟踪。

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

**架构：** [用 2-3 句话说明实现方法]

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

## 全局约束

[规范中的项目级要求——最低版本、依赖限制、
命名和文案规则、平台要求——每项一行，精确值逐字
从规范中复制。每项任务的要求均隐含包含本节。]

---
```

## 任务结构
````markdown
### 任务 N: [Component Name]

**文件：**
- 创建：`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，并显示“函数未定义”

- [ ] **步骤 3：编写最小实现**

```python
def function(input):
    return expected
```

- [ ] **步骤 4：运行测试以验证其通过**

运行：`pytest tests/path/test.py::test_name -v`
预期：PASS

- [ ] **步骤 5：提交**

```bash
git add tests/path/test.py src/path/file.py
git commit -m "feat: 添加特定功能"
```
````

## 不得使用占位符
每个步骤都必须包含工程师所需的实际内容。以下属于**计划失败项**——绝不要写：
- "TBD"、"TODO"、"稍后实现"、"补充细节"
- "添加适当的错误处理" / "添加验证" / "处理边界情况"
- "为上述内容编写测试"（却不提供实际测试代码）
- "类似于任务 N"（重复写出代码——工程师可能不会按顺序阅读任务）
- 只描述要做什么，却不展示如何做的步骤（代码步骤必须包含代码块）
- 引用任何任务中都未定义的类型、函数或方法

## 牢记
- 始终提供精确的文件路径
- 每个步骤都要提供完整代码——如果某个步骤修改代码，就展示该代码
- 提供精确的命令及预期输出
- DRY、YAGNI、TDD、频繁提交

## 自我审查

撰写完整计划后，以全新的视角审视规范，并对照规范检查计划。这是你自己执行的检查清单——不是派遣子 Agent。

**1. 规范覆盖：**快速浏览规范中的每个章节/要求。你能指出实现它的任务吗？列出所有缺漏。

**2. 占位符扫描：**在计划中搜索红旗项——即上方“禁止占位符”章节中的任何模式。修复它们。

**3. 类型一致性：**你在后续任务中使用的类型、方法签名和属性名称，是否与早期任务中的定义一致？任务 3 中名为 `clearLayers()` 的函数到了任务 7 却变成 `clearFullLayers()`，这就是一个错误。

如果发现问题，就地修复。无需重新审查——只需修复并继续。如果发现某项规范要求没有对应任务，就添加该任务。

## 执行交接

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

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

**1. 子 Agent 驱动（推荐）** - 每个任务派遣一个全新的子 Agent，在任务之间进行审查，快速迭代

**2. 内联执行** - 在本会话中使用 executing-plans 执行任务，分批执行并设置审查检查点

**选择哪种方式？"**

**如果选择子 Agent 驱动：**
- **必需的子技能：**使用 superpowers:subagent-driven-development
- 每个任务使用一个全新的子 Agent + 两阶段审查

**如果选择内联执行：**
- **必需的子技能：**使用 superpowers:executing-plans
- 分批执行，并设置检查点以供审查
