编写计划

概述

编写全面的实施计划，假设工程师对我们的代码库零背景知识且品味存疑。记录他们需要知道的一切：每个任务需要触及哪些文件、代码、测试、他们可能需要检查的文档，以及如何测试。把整个计划分解成小块的任务。遵循 DRY 原则、YAGNI 原则、TDD 原则、频繁提交原则。

假设他们是一名熟练的开发者，但对我们的工具集或问题领域几乎一无所知。假设他们不太擅长设计好的测试。

开始时声明： “我正在使用编写计划技能来创建实施计划。”

上下文： 这应该在一个专用的工作树中运行（由构思技能创建）。

保存计划到： docs/superpowers/plans/YYYY-MM-DD-<功能名称>.md

• （用户对计划位置的偏好会覆盖此默认值）

范围检查

如果规格涵盖多个独立的子系统，那么在构思阶段就应该将其分解为子项目规格。如果尚未分解，建议将其拆分为单独的计划——每个子系统一个。每个计划本身应该能产生可工作、可测试的软件。

文件结构

在定义任务之前，规划出将要创建或修改的文件，以及每个文件的职责。这是分解决策被确定下来的地方。

• 设计边界清晰、接口定义明确的单元。每个文件应有一个清晰的职责。
• 您能最好地推理一次可以容纳在上下文中的代码，并且当文件专注时，您的编辑更可靠。优先选择较小、专注的文件，而不是做得太多的庞杂文件。
• 经常一起变动的文件应放在一起。按职责拆分，而不是按技术层。
• 在现有代码库中，遵循既定的模式。如果代码库使用大文件，不要单方面进行重构——但如果您正在修改的文件变得臃肿，在计划中包含拆分是合理的。

此结构将为任务分解提供依据。每个任务应产生可独立理解的自包含更改。

小块任务的粒度

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

• “编写失败的测试” – 步骤
• “运行它以确保它失败” – 步骤
• “编写最少的代码使测试通过” – 步骤
• “运行测试并确保它们通过” – 步骤
• “提交” – 步骤

计划文档头部

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

# [功能名称] 实施计划

> **给代理工作者的说明：** 必需：如果子代理可用，使用 superpowers:subagent-driven-development；否则，使用 superpowers:executing-plans 来实施此计划。步骤使用复选框 (`- [ ]`) 语法进行跟踪。

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

**架构：** [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 with "function not defined"

- [ ] **步骤 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: add specific feature"
```

记住

• 始终使用确切的文件路径
• 计划中包含完整代码（不仅仅是“添加验证”）
• 包含确切的命令和预期输出
• 使用 @ 语法引用相关技能
• DRY、YAGNI、TDD、频繁提交

计划审查循环

在完成计划的每个块后：

1. 为当前块分派计划文档审查子代理（参见 plan-document-reviewer-prompt.md）
   • 提供：块内容、规格文档的路径
2. 如果 ❌ 发现问题：
   • 修复块中的问题
   • 为该块重新分派审查者
   • 重复直到 ✅ 获得批准
3. 如果 ✅ 获得批准：继续下一个块（或者如果是最后一个块，则进行执行交接）

块边界： 使用 ## 块 N：<名称> 标题来分隔块。每个块应 ≤1000 行，并且在逻辑上自包含。

审查循环指南：

• 由编写计划的同一代理修复问题（以保留上下文）
• 如果循环超过 5 次迭代，提交给人工指导
• 审查者是提供建议的——如果您认为反馈不正确，可以解释分歧

执行交接

保存计划后：

“计划已完成并保存到 docs/superpowers/plans/<文件名>.md。准备执行了吗？”

执行路径取决于工具能力：

如果工具具有子代理功能（Claude Code 等）：

• 必需： 使用 superpowers:subagent-driven-development
• 不要提供选择——子代理驱动是标准方法
• 每个任务使用全新的子代理 + 两阶段审查

如果工具不具有子代理功能：

• 在当前会话中使用 superpowers:executing-plans 执行计划
• 批量执行并设置检查点以供审查