write-plan

编写计划

概述

编写全面的实施计划，假设工程师对我们的代码库毫无了解，而且品味也不太可靠。记录他们需要知道的一切：每项任务要修改哪些文件、涉及哪些代码和测试、需要查阅哪些文档，以及如何进行测试。将完整计划拆分成小任务。遵循 DRY、SOLID、YAGNI 和 TDD。频繁提交。每份计划最后都必须包含 测试计划与验证 部分和覆盖率目标，然后在编写任何代码之前，自动进行第二轮工程评审（/plan-eng-review）。

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

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

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

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

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

范围检查

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

如果规范描述的是一项面向用户的功能，应将计划限定为一个垂直切片：一个分支涵盖该功能正常运行所需的所有层——UI、API、业务逻辑、数据和测试；每个切片都应可独立交付，并且可以安全回退（完整定义见 superskills 安装目录中的 DEVELOPER_WORKFLOW.md）。如果是缺陷修复、重构或单层变更，则只规划其实际涉及的层——不要为了让切片看起来完整而额外添加层；这违反了 YAGNI 原则。

文件结构

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

• 设计边界清晰、接口明确的单元。每个文件都应有明确的单一职责。
• 你对能一次放入上下文的代码推理效果最好；文件聚焦时，编辑也更可靠。优先使用更小、更聚焦的文件，避免一个文件承担过多职责。
• 一起变更的文件应放在一起。按职责拆分，而不是按技术层拆分。
• 在现有代码库中，应遵循已有模式。如果代码库使用大型文件，不要擅自重构；但如果要修改的文件已经过于庞大，在计划中提出拆分是合理的。

此结构将决定任务的拆分方式。每项任务都应产出自包含的变更，能够独立成立。

设计原则（在计划中明确指出）

此技能在计划阶段落实 superskills 质量标准（TDD、DRY、SOLID、YAGNI）；/qa-full 则在交付阶段确保符合标准。以下各节中均有这些原则的定义，请以此为准。权威书面版本位于 superskills 安装目录中的 ENGINEERING_STANDARDS.md（不在你要为其制定计划的项目中），因此无需获取该文件。

计划必须体现对这些原则的遵循——不能只打勾，而要指出每项原则在文件结构和任务中的适用位置：

• DRY — 添加代码前，指出要复用的现有辅助工具或模块（用 Grep 查找）。如果两个任务会引入类似逻辑，就将共用部分提取到更早的独立任务中。指出你明知会接受的重复，以及原因。
• SOLID — 每个单元都只有一个变更理由（SRP）；依赖接口或抽象，而非具体实现（DIP）；保持接口精简（ISP）；通过新增代码进行扩展，而非修改稳定的核心（OCP）。对于文件结构中的每个新单元，说明其单一职责及其暴露的接口（边界）。
• YAGNI — 只构建规范要求的内容。不要推测性地设计可扩展性，也不要添加“以后可能会需要”的钩子。

如果要遵循这些原则就必须重构现有代码，请将重构列为独立任务——不要把它夹带进功能任务中。

安全与威胁模型（功能跨越信任边界时）

威胁建模是设计阶段的工作——它必须影响计划，而不是等到交付关卡才发现问题。如果此功能涉及以下任何一项，请在编写任务前对设计运行 /cso（OWASP Top 10 + STRIDE），并将结果纳入计划：

• 处理身份验证、授权、会话或令牌
• 接受不可信输入（用户输入、上传内容、webhook、外部 API）
• 读写敏感或受监管的数据（个人身份信息、支付信息、凭据、健康信息）
• 新增公开端点、新的外部集成或反序列化
• 改变信任边界（新增服务间调用、新增跨租户路径）

计划需要纳入的内容：

• 设计任务：针对每项重大威胁安排任务——输入验证、边界处的授权检查、速率限制、输出编码、最小权限、密钥处理。将这些列为独立任务（不要把它们埋在功能任务中）。
• 测试计划条目：针对每项威胁列出滥用或负面测试用例（例如“拒绝伪造的 JWT”“阻止对 /orders/:id 的 IDOR”），以便 /qa-full 的 /defense 步骤有具体内容可验证。

如果功能不跨越任何信任边界，请用一行说明并跳过——不要凭空编造安全任务（此处同样适用 YAGNI）。

细粒度任务

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

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

计划文档标题

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

# [Feature Name] Implementation Plan

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

不要使用占位符

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

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

测试计划与验证（每个计划都必须包含）

任务完成后，每个计划都必须以 ## Test Plan & Verification 章节结尾。没有这一章节的计划是不完整的。/qa-full、/qa、/qa-only 和 /verify 都会使用这份汇总内容，而 /plan-eng-review 会对其进行复核。每项任务的 TDD 步骤仍保留在原处；本章节则将它们与覆盖率、关键路径和验收标准关联起来。

## Test Plan & Verification

**Coverage target:** [concrete, e.g. "≥90% lines on new modules; every new public function and error path has a test"]

**Critical paths (must pass before ship):**
- [end-to-end flow] → [how it's verified]

**Edge cases & error paths:**
- [input/state] → [expected handling] → [test that covers it]

**Regression guards:**
- [existing behavior that must not break] → [test protecting it]

**Verification commands:**
- Unit: `[exact command]` — expected: all pass
- Coverage: `[exact command]` — expected: ≥ target above
- E2E (if applicable): `[exact command]`

**Acceptance criteria (from spec):**
- [ ] [criterion] → covered by [task / test name]

覆盖率目标这一行正是 /qa-full 第 9 步检查、/verify 确认的内容——要写具体，不能只说“覆盖率良好”。

牢记

• 始终使用准确的文件路径
• 每个步骤都要包含完整代码——如果某个步骤会修改代码，就展示代码
• 使用准确命令并注明预期输出
• 遵循 DRY、SOLID、YAGNI、TDD，并频繁提交
• 每个计划都要以 ## Test Plan & Verification 章节结尾，并包含覆盖率目标

自我审查

完成计划后，以全新的视角重新审视规范，并核对计划是否符合规范。这是你要自行执行的检查清单——不是派发给子 Agent 的任务。

1. 规范覆盖： 浏览规范中的每个章节和要求。能否指出具体任务来实现它们？列出所有遗漏。

2. 占位符扫描： 搜索计划中的风险信号——查找上文“禁止使用占位符”一节中的所有模式。修正它们。

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

4. TDD 与测试计划完整性： 每个编写代码的任务是否都有先编写失败测试的步骤？是否包含 ## Test Plan & Verification 章节，并明确列出具体覆盖率目标、关键路径、边缘情况和准确的验证命令？如果有任何任务提交了代码却没有测试，就修正它。

5. 原则检查（DRY / SOLID / YAGNI）： 对于每个新增单元，能否说明其单一职责（SRP）以及复用的现有辅助工具（DRY）？是否存在任务间的重复逻辑、上帝对象或投机性的可扩展性设计（YAGNI）？请修正，或在文中说明理由。

6. 信任边界检查： 功能是否跨越任何信任边界（身份验证、不可信输入、敏感数据、新端点或集成、反序列化）？如果是，是否运行了 /cso，并将每项重大威胁转化为设计任务和负向测试？如果没有跨越信任边界，是否已明确说明？请补齐遗漏——未安排安全任务的信任边界功能，其计划是不完整的。

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

工程审查（自动进行的第二轮检查——不得跳过）

计划通过自我审查后，在编写任何代码之前，将计划交给 /plan-eng-review 进行独立的工程复核。这是自动步骤——不要征求许可，直接运行：

1. 对已保存的计划文件调用 /plan-eng-review。它会确定架构和数据流，严格检验边缘情况和测试覆盖率，并编写一份 Test Plan Artifact，供 /qa、/qa-only 和 /qa-full 作为主要测试输入使用。
2. 它会逐项提出问题，并给出明确的建议。逐一处理，并将解决方案写回计划文件——包括它在 ## Test Plan & Verification 章节或 DRY/SOLID 结构中发现的任何遗漏。
3. 只有在 /plan-eng-review 认可计划后，才能按下方所述移交执行。

完整流程：/write-plan（DRY · SOLID · YAGNI · TDD · 测试计划 · 覆盖率）→ 自我审查 → /plan-eng-review（复核 + Test Plan Artifact）→ 执行。

执行交接

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

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

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

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

你选择哪种方式？”

如果选择子 Agent 驱动：

• 必需的子技能： 使用 subagent-driven-development
• 每项任务都使用全新的子 Agent + 两阶段审查

如果选择行内执行：

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