writing-plans

编写计划

概述

编写全面的实施计划，假设工程师对我们的代码库毫无了解，而且判断力可能不佳。记录他们需要了解的一切：每项任务要修改哪些文件、代码、需要查看的测试和文档，以及如何测试。将完整计划拆分成易于执行的小任务。遵循 DRY 和 YAGNI 原则。测试规模要适度。频繁提交。

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

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

**上下文：**应在专用工作树中执行（通过 superjawn:using-git-worktrees 设置）。

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

• （用户对计划保存位置的偏好优先于此默认设置）

范围检查

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

文件结构

定义任务前，先梳理将要创建或修改的文件，以及每个文件的职责。这一步将确定任务分解方案。

• 设计边界清晰、接口明确的单元。每个文件只承担一项明确职责。
• 对于能一次放在上下文中理解的代码，你的推理效果最好，修改也更可靠。优先选择小而专注的文件，避免文件职责过多。
• 一起变更的文件应放在一起。按职责拆分，而不是按技术层拆分。
• 在现有代码库中，应遵循既有模式。如果代码库使用大文件，不要擅自重构；但如果要修改的文件已经变得难以维护，在计划中提出拆分方案是合理的。

此结构将指导任务分解。每项任务都应产出独立完整、单独来看也合理的变更。

易于执行的小任务粒度

每个步骤只做一项操作（2–5 分钟）：

• “运行检查，查看当前行为”——一个步骤
• “实施最小改动”——一个步骤
• “运行相同的检查并确认结果符合预期”——一个步骤
• “提交”——一个步骤

仅当测试能防止可能反复出现的问题、保护稳定契约、覆盖不明显的逻辑或高影响行为时，才添加新测试。预期值应取自规范或真实数据，而不是新代码的输出。

计划文档头部

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

# [Feature Name] Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superjawn:subagent-driven-development (recommended) or superjawn: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]

---

任务结构

### Task N: [Component Name]

**Files:**
- Create: `exact/path/to/file.py`
- Modify: `exact/path/to/existing.py:123-145`
- Test (only when the task keeps a new test): `tests/exact/path/to/test.py`

**Check:** [The command that proves this task, and why it is the cheapest faithful evidence]

- [ ] **Step 1: Run the check that shows current behavior**

Use an existing test or a focused command when it proves the behavior:

Run: `python -m mypkg.cli convert sample.csv`
Expected: exit 1 with "unsupported column type: date"

When the task keeps a new test, write it first and take the expected value
from the spec or real data:

```python
def test_specific_behavior():
    result = function(input)
    assert result == expected  # expected value from the spec or real data
```

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

- [ ] **Step 2: Write minimal implementation**

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

- [ ] **Step 3: Run the same check to verify the result**

Run: the same command as Step 1
Expected: the behavior the spec requires (for example, exit 0, or PASS)

- [ ] **Step 4: Commit**

```bash
git add src/path/file.py  # add tests/path/test.py only if the task kept a test
git commit -m "feat: add specific feature"
```

禁止占位内容

每个步骤都必须包含工程师实际需要的信息。以下内容都表示计划不合格，绝不可写入：

• “待定”“TODO”“稍后实现”“补充细节”
• “添加适当的错误处理”／“添加验证”／“处理边界情况”
• “为上述内容编写测试”（但没有给出实际测试代码）
• “与任务 N 类似”（应重复给出代码，因为工程师可能会跳着阅读任务）
• 只描述要做什么，却不说明怎么做的步骤（涉及代码的步骤必须包含代码块）
• 引用任何未在任务中定义的类型、函数或方法

请记住

• 始终写出精确的文件路径
• 每个步骤如有代码变更，都要给出完整代码
• 给出精确命令及预期输出
• 遵循 DRY 和 YAGNI 原则，测试规模要适度，并频繁提交

自我审查

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

1. 规范覆盖情况： 浏览规范中的每个章节／要求。你能否指出实现每项要求的任务？列出所有遗漏。

2. 占位符扫描： 搜索计划中的风险信号，即上文“无占位符”一节中的任何模式。修复它们。

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

如果发现问题，请直接在原处修复。无需重新审查，修复后继续。如果发现某项规范要求没有对应任务，就添加该任务。

执行交接

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

“计划已完成并保存至 docs/superpowers/plans/<filename>.md。有两种执行方式：

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

2. 行内执行——在本次会话中使用 superjawn:executing-plans 执行任务，并通过检查点分批执行

你选择哪种方式？”

如果选择子 Agent 驱动：

• 必需子技能： 使用 superjawn:subagent-driven-development
• 每项任务使用全新的子 Agent，并进行两阶段审查

如果选择行内执行：

• 必需子技能： 使用 superjawn:executing-plans
• 通过检查点分批执行，以便审查