SKILL.md
编写实施计划
概览
编写全面的实施计划，默认读者对代码库几乎没有上下文，对当前技术栈和业务领域也不熟。你要把他们需要知道的内容尽量写全：每个任务改哪些文件、写什么代码、怎么验证、要参考哪些文档。
假设他们是熟练工程师，但几乎不了解当前工具栈，也不擅长测试设计。
开场声明： "我将使用 superpowers-writing-plans 技能编写实施计划。"
上下文： 如果当前处在隔离 worktree 中，它应在执行阶段通过 superpowers-using-git-worktrees 创建或确认。
计划存放： docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md
- 若用户对计划路径有明确偏好，以用户要求为准。
范围检查
如果 spec 同时覆盖了多个彼此独立的子系统，这本来就应该在 brainstorming 阶段被拆开。若你发现它没有拆开，请先建议拆成多个计划，每个计划只交付一个可独立验证的结果。
文件结构先行
在列任务前，先明确哪些文件会被新建或修改，以及每个文件负责什么。这一步决定了后续任务的拆分方式。
- 单个文件应只承担一个清晰职责。
- 代码单元之间应有明确边界和接口。
- 经常一起改动的内容应尽量放在一起，按职责拆，而不是机械按技术层拆。
- 在现有代码库中要跟随既有模式；若某个目标文件已经过大，可以把适度拆分写进计划，但不要无端重构。
任务大小校准
一个任务是最小的独立交付单元：它拥有自己的测试循环，也值得通过一次新的 reviewer gate。划分任务边界时：
- setup、configuration、scaffolding、documentation 要并入需要这些内容的交付任务
- 只有当 reviewer 可以合理地拒绝某个任务、同时批准相邻任务时，才拆成两个任务
- 每个任务结束时都必须产出可独立验证的结果
颗粒化任务粒度
每一步是一个动作，理想上在 2-5 分钟内可完成：
- “编写失败测试” 是一步
- “运行测试确认失败” 是一步
- “写最小实现让测试通过” 是一步
- “再次运行测试确认通过” 是一步
- “提交代码” 是一步
计划文档头部
每个计划必须以此开头：
# [功能名称] 实现计划
> **对于 agent 型执行者：** 必需子 skill：优先使用 `superpowers-subagent-driven-development`，否则使用 `superpowers-executing-plans` 逐任务实施本计划。所有步骤使用 `- [ ]` 复选框格式追踪。
**目标：** [一句话描述这构建什么]
**架构：** [2-3 句话说明方法]
**技术栈：** [关键技术 / 库]
## Global Constraints
[从 spec 中逐字复制项目级要求：版本下限、依赖限制、命名和文案规则、平台要求等。每行一条，保留精确值。所有任务默认都包含这些约束。]
---任务结构
````markdown
任务 N: [组件名称]
文件：
- 创建：
exact/path/to/file.py - 修改：
exact/path/to/existing.py:123-145 - 测试：
tests/exact/path/to/test.py
Interfaces：
- Consumes: [本任务依赖前序任务产物的内容，写出精确签名]
- Produces: [后续任务依赖本任务产物的内容，写出精确函数名、参数和返回类型。实现者只会看到自己的任务；此块告诉它相邻任务使用哪些名字和类型。]
- 步骤 1: 编写失败的测试
def test_specific_behavior():
result = function(input)
assert result == expected- 步骤 2: 运行测试验证失败
运行: pytest tests/path/test.py::test_name -v 预期: 失败并显示 "function not defined"
- 步骤 3: 编写最小实现
def function(input):
return expected- 步骤 4: 运行测试验证通过
运行: pytest tests/path/test.py::test_name -v 预期: 通过
- 步骤 5: 提交
git add tests/path/test.py src/path/file.py
git commit -m "feat: add specific feature"````
禁止占位符
每一步都必须包含实施者真正需要的信息。下面这些都属于计划失败，不能写：
TBD、TODO、稍后实现、自行补全细节- “补充适当的错误处理” / “加上校验” / “处理边界情况”
- “给上面的逻辑补测试”，但不提供真实测试代码
- “类似任务 N”，却不把关键代码和步骤再次写出
- 只描述做什么，却不展示怎么做
- 引用了计划中从未定义过的函数、类型或方法名
记住
- 始终使用精确文件路径
- 每个改代码的步骤都要包含完整代码，不要只写“补上验证”
- 命令要精确，并写明预期输出
- 遵循 DRY、YAGNI、TDD，保持频繁提交
自审
写完整份计划后，用新的视角快速复查一遍：
- 需求覆盖：把 spec 各节快速扫一遍。每一项需求都能在计划中找到对应任务吗？
- 占位符扫描：检查是否还残留上面“禁止占位符”一节中的反模式。
- 类型与命名一致性：后续任务里使用的函数名、类型名、属性名，是否和前文定义一致？
如果发现缺口，就直接补进文档；不用额外再开一次审查流程。
执行移交
保存计划后，给出执行选项：
计划完成并保存到 docs/superpowers/plans/<filename>.md。两种执行选项：
1. 子代理驱动（推荐） - 我为每个任务派遣新的子代理，任务间做审查，快速迭代
2. 当前会话内执行 - 在本会话里使用 superpowers-executing-plans 执行整份计划
选择哪种方法？
如果选择子代理驱动：
- 需要使用的子技能：
superpowers-subagent-driven-development - 每个任务使用新的子代理 + task review（spec compliance + code quality）
如果选择当前会话内执行：
- 需要使用的子技能：
superpowers-executing-plans - 按任务推进，遇阻就停下澄清