writing-plans

编写计划

概述

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

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

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

**上下文：**应在专用工作树中执行（由 brainstorming 技能创建）。

**计划保存位置：**对于新项目，保存到 docs/rubypowers/plans/YYYY-MM-DD-<feature-name>.md。如果已存在 docs/superpowers/plans/，则改用该旧目录，以便现有项目的文档集中存放。此工作流中的每次草稿保存、编辑、晋升、完成消息和审阅者指示，都使用选定的目录。如果项目已有旧目录，不要创建新目录。

• 用户对计划位置的偏好优先于此默认设置。

范围检查

如果规范涵盖多个相互独立的子系统，那么在 brainstorming 期间就应该将其拆分为多个子项目规范。如果没有拆分，请建议将其拆分为多个独立计划，每个子系统对应一个计划。每个计划都应独立产出可运行、可测试的软件。

文件结构

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

• 设计边界清晰、接口明确的单元。每个文件都应有一个明确的职责。
• 你最擅长在上下文中一次处理少量代码，文件越精简，修改越可靠。优先选择小型、职责明确的文件，而不是承担过多工作的庞大文件。
• 一起变更的文件应放在一起。按职责拆分，而不是按技术层拆分。
• 在现有代码库中，遵循已有模式。如果代码库使用大型文件，不要擅自重构；但如果要修改的文件已经过于庞大，在计划中安排拆分是合理的。

此结构将指导任务拆分。每项任务都应产出可以独立理解的、自包含的变更。

小任务粒度

每个步骤只做一件事（2–5 分钟）：

• “编写失败测试”——一个步骤
• “运行测试，确认其失败”——一个步骤
• “实现最精简的代码，使测试通过”——一个步骤
• “运行测试并确认通过”——一个步骤
• “提交”——一个步骤

计划文档头部

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

# [Feature Name] Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use rubypowers:subagent-driven-development (recommended) or rubypowers: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: `tests/exact/path/to/test.py`

- [ ] **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: Write minimal implementation**

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

- [ ] **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"
```

不要使用占位内容

每个步骤都必须包含工程师所需的实际内容。以下情况都属于计划失败，绝不能这样写：

• “TBD”“TODO”“稍后实现”“补充细节”
• “添加适当的错误处理”／“添加验证”／“处理边缘情况”
• “为上述内容编写测试”（但未提供实际测试代码）
• “类似任务 N”（重复提供代码——工程师可能不会按顺序阅读任务）
• 只描述要做什么，却不展示如何做的步骤（编写代码的步骤必须包含代码块）
• 引用了任何未在任务中定义的类型、函数或方法

牢记

• 始终写出确切的文件路径
• 每个步骤都要提供完整代码——如果步骤会修改代码，就展示代码
• 提供准确命令和预期输出
• 遵循 DRY、YAGNI、TDD，并频繁提交

自我审查

完成整个计划后，以全新的视角审视规范，并对照规范检查计划。这是你自行执行的检查清单，不是派发给子 Agent 的任务。

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

2. 占位符扫描： 搜索计划中的危险信号——即上方「无占位符」章节中的任何模式。修复它们。

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

如果发现问题，请直接修复。无需再次审查，修复后继续即可。如果发现规范要求没有对应任务，请添加该任务。

执行交接

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

「计划已完成并保存到 <selected plans folder>/<filename>.md。有两种执行方式：

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

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

你想采用哪种方式？」

如果选择子 Agent 驱动：

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

如果选择行内执行：

• 必需的子技能： 使用 rubypowers:executing-plans
• 分批执行，并设置检查点以便审查