KeyInfo Bot
dc35e1cbf3
Constraint: Public skills are published only by explicit administrator action unless they are tracked third-party market sources. Confidence: high Scope-risk: narrow Directive: Keep private/internal skills out of the public marketplace and preserve normal incremental market Git history. Tested: Marketplace validation passed.
7.0 KiB
name, description
| name | description |
|---|---|
| writing-plans | 当你已有多步骤任务的规格说明或需求时，在接触代码之前使用 |
编写计划
概述
编写全面的实施计划，并假设工程师对我们的代码库毫无了解且品味堪忧。记录他们需要知道的一切：每项任务要修改哪些文件、代码、测试、可能需要查阅的文档，以及如何进行测试。将完整计划拆成小块任务交给他们。DRY。YAGNI。TDD。频繁提交。
假设他们是技能娴熟的开发者，但对我们的工具集或问题领域几乎一无所知。假设他们不太懂良好的测试设计。
开始时宣布：“我正在使用 writing-plans 技能来创建实施计划。”
**上下文：**如果在隔离的工作树中工作，它应当已在执行时通过 superpowers:using-git-worktrees 技能创建。
将计划保存至：docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md
- （用户对计划位置的偏好会覆盖此默认值）
范围检查
如果规格说明涵盖多个相互独立的子系统，则在头脑风暴期间就应该已将其拆分为多个子项目规格说明。如果尚未拆分，建议将其拆成单独的计划——每个子系统一份。每份计划都应独立产出可运行、可测试的软件。
文件结构
在定义任务之前，梳理将创建或修改哪些文件，以及每个文件负责什么。分解决策将在这里确定下来。
- 设计边界清晰且接口定义明确的单元。每个文件都应只有一项明确的职责。
- 对于能够一次纳入上下文的代码，你的推理效果最佳；当文件职责聚焦时，你的编辑也更可靠。相比庞大且承担过多职责的文件，应优先选择更小、更聚焦的文件。
- 会一起变更的文件应该放在一起。按职责拆分，而不是按技术层拆分。
- 在现有代码库中，遵循既有模式。如果代码库使用大文件，不要单方面重构——但如果你正在修改的文件已经变得难以驾驭，那么在计划中加入拆分是合理的。
此结构会为任务分解提供依据。每项任务都应产出自包含的变更，且这些变更本身应独立合理。
任务大小适配
任务是具备自身完整测试周期、且值得由一位新的审查者设置一道关卡的最小单元。划分任务边界时：将设置、配置、脚手架和文档步骤并入其可交付成果需要这些步骤的任务中；仅当审查者能够有意义地拒绝一个任务、同时批准其相邻任务时才进行拆分。每项任务都以可独立测试的可交付成果结束。
小块任务粒度
每个步骤都是一个操作（2-5 分钟）：
- “编写失败的测试”——一个步骤
- “运行它以确保它失败”——一个步骤
- “实现让测试通过所需的最少代码”——一个步骤
- “运行测试并确保它们通过”——一个步骤
- “提交”——一个步骤
计划文档标题
每个计划都必须以此标题开头：
# [功能名称] 实施计划
> **面向 Agent 型工作者：** 必需的子技能：使用 superpowers:subagent-driven-development（推荐）或 superpowers:executing-plans 来逐项任务实施此计划。步骤使用复选框（`- [ ]`）语法进行跟踪。
**目标：** [用一句话描述要构建的内容]
**架构：** [用 2-3 句话说明实现方法]
**技术栈：** [关键技术/库]
**规格说明：** [本计划实现的规格/设计文档路径——计划以规格说明为依据，规格说明会随计划一起传递；执行者需要同时阅读二者]
## 全局约束
[规范中的项目级要求——最低版本、依赖限制、
命名和文案规则、平台要求——每项一行，精确值逐字
从规范中复制。每项任务的要求均隐含包含本节。]
---
任务结构
### 任务 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"（重复写出代码——工程师可能不会按顺序阅读任务）
- 只描述要做什么，却不展示如何做的步骤（代码步骤必须包含代码块）
- 引用任何任务中都未定义的类型、函数或方法
自我审查
撰写完整计划后，以全新的视角审视规范，并对照规范检查计划。这是你自己执行的检查清单——不是派遣子 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
- 分批执行，并设置检查点以供审查