编写计划 (writing-plans)

编写计划（writing-plans）

概述

writing-plans 是从“设计确认”过渡到“工程执行”的桥梁 Skill。它解决的问题非常现实：

很多团队有 spec，但没有真正可执行的 implementation plan。

没有计划时，工程师会临场发挥；计划太粗时，执行者会迷路；计划不考虑测试和验证时，任务看似推进，实际质量失控。

所以这个 Skill 要求你在动代码之前，先把实现路径写成一个对“几乎没有上下文的人”也能执行的计划文档。它要求你把以下东西写清楚：

要改哪些文件
每个文件承担什么责任
任务怎么拆分
每一步怎么测试
每一步怎么验证
每一段完成后如何提交

工作流程

writing-plans 的逻辑是把“我知道大概要做什么”变成“任何一个合格执行者都可以按步骤完成”。

graph TD
  A[拿到 spec 或明确需求] --> B{是否覆盖多个独立子系统？}
  B -->|是| C[建议拆分为多个独立计划]
  B -->|否| D[先梳理文件结构与责任边界]
  C --> D
  D --> E[把实现拆成多个任务]
  E --> F[每个任务再拆成 2-5 分钟粒度步骤]
  F --> G[为每个步骤补测试、命令、预期结果]
  G --> H[写入计划文档]
  H --> I[进入 plan review loop]
  I --> J{计划是否通过审查？}
  J -->|否| H
  J -->|是| K[提供执行方式选择]
  K --> L[进入 subagent-driven-development 或 executing-plans]

步骤 1：先判断范围是否过大

Skill 明确要求先做 scope check：

如果 spec 覆盖多个独立子系统
那不该写成一个大而模糊的计划
应该拆成多个独立 plan

这一步的核心思想是： 每一份计划都应该对应一块可独立交付、可测试的软件。

步骤 2：先梳理文件结构，再拆任务

这是这个 Skill 最工程化的地方之一。

原文强调：在写任务之前，先回答这些问题：

哪些文件会创建？
哪些文件会修改？
每个文件各自负责什么？
文件边界是不是清楚？

也就是说，它不是从“功能点”开始写计划，而是从实现结构开始。

步骤 3：任务必须足够小

原文给出的标准非常具体：

每一步应是一个动作
每步大约 2~5 分钟

例如：

写 failing test
运行测试确认失败
写最小实现
再运行测试确认通过
commit

这其实是在强制你把计划写成一种“可机器执行、可人类跟踪、可中断恢复”的形式。

步骤 4：每一步都要附带验证方式

这个 Skill 不允许你写：

“补充验证逻辑”
“完善测试”
“实现接口”

这种模糊语言。

它要求你写：

具体文件路径
具体代码片段
具体命令
预期输出

因为计划的目标不是显得专业，而是保证执行时不迷路。

步骤 5：写完后必须走 review loop

和 brainstorming 的 spec review 类似，plan 写完后也不是直接执行，而是先走 plan review loop。

也就是说，Superpowers 不把计划视为“作者脑内已经想清楚”的私有产物，而是把它视为：

需要被检查完整性
需要被检查与 spec 对齐程度
需要被检查 task decomposition 是否合理

速查卡片

何时使用

已经有 spec 或明确需求
准备开始实现多步骤任务前
需要把任务交给执行者或子代理前

何时不用

还没完成 brainstorming
还没有用户批准设计
任务不是多步骤实现问题

关键要点

先梳理文件结构，再拆任务
每步粒度保持 2-5 分钟
每一步都带测试/命令/预期结果
计划写完必须先 review

常见错误

计划写成高层 TODO 列表
不写具体文件路径
不写测试与验证方式
计划未 review 就直接执行

关键概念

英文术语	中文翻译	解释
Implementation plan	实现计划	从 spec 落到执行层的详细任务文档。
Scope check	范围检查	判断 spec 是否过大，是否应拆分成多个计划。
Task decomposition	任务拆分	把功能拆成边界清晰、可执行的任务与步骤。
Bite-sized steps	小步粒度步骤	每一步尽量控制在 2~5 分钟内完成。
Plan review loop	计划审查循环	写完计划后先做 reviewer 审查，再进入实现。
Execution handoff	执行交接	计划完成后，选择交给子代理或当前会话继续执行。

常见错误与红旗

错误行为	为什么是错的	正确做法
“我脑子里有计划，不用写那么细”	计划不是写给作者自己看的	按零上下文执行者标准写清楚
直接按功能点列几个大标题	执行时仍然会卡住	继续往下拆到可执行步骤
不写文件路径	执行者不知道从哪里开始	明确 create / modify / test 文件
不写命令与预期结果	验证标准不明确	每一步都写 run 与 expected
不走 plan review	计划可能有缺口但没人发现	写完先审，再执行

深度解读

原文的设计哲学

这个 Skill 的设计哲学可以总结成：

实现计划是交付物，不是作者的脑内草稿。

很多团队的问题并不是没有计划，而是“计划只有作者自己能看懂”。比如：

“先做后端，再做前端”
“补测试”
“改下 schema”
“把逻辑抽出去”

这些在作者脑中也许很清楚，但对执行者来说毫无操作性。

writing-plans 的目标，就是把这种模糊计划强制转化为：

可执行
可验证
可 review
可交接

的工程文档。

与日常开发的关联

这在真实工作中非常常见：

需求已经定了，但团队成员对实现顺序理解不一致
有些人先改数据库，有些人先改 API，有些人先改 UI
最后不是做不出来，而是返工很多次

如果前面写了一个足够细的 implementation plan，这些混乱会少很多。

对 AI 协作来说更是这样： AI 非常会“填空”，但不天然擅长“稳妥执行模糊计划”。所以计划越具体，AI 的执行质量越稳定。

实际使用场景举例

场景 1：实现一个新登录流程

错误做法：

写成“前端做页面、后端做接口、最后联调”

正确做法：

先列出 auth service、route、UI、test 文件
再拆成写 failing test → 跑失败 → 最小实现 → 跑通过 → commit

场景 2：重构一个大文件

错误做法：

计划里写“拆分模块”

正确做法：

明确拆成哪些文件
每个文件各自负责什么
如何逐步迁移并保持测试通过

场景 3：把任务交给子代理

错误做法：

只给一句模糊目标

正确做法：

先写清楚 plan
再把 plan 交给子代理执行
这样 reviewer 才有标准可检查

关联 Skill

前置：brainstorming，因为 design/spec 先于 implementation plan。
后续：subagent-driven-development 或 executing-plans，这是这个 Skill 明确给出的执行交接。
互补：test-driven-development、verification-before-completion，因为高质量计划必须内建测试与验证。

附属文档

Plan Reviewer Prompt

这份 reviewer prompt 的作用是检查：

计划是否完整
是否对齐 spec
task decomposition 是否合理
执行者能不能真正照着做完

它最重要的判断标准不是“写得漂不漂亮”，而是：

执行者会不会因为这份计划而做错、漏做、或者中途卡住。

reviewer 主要关注四类问题：

Completeness：是否有 TODO / placeholder / 缺项
Spec Alignment：是否偏离 spec，是否 scope creep
Task Decomposition：任务边界是否清晰，步骤是否足够可执行
Buildability：执行者是否能顺利走完而不迷路

这份 prompt 很好地说明了 Superpowers 的一个核心立场： 计划不是形式文档，而是面向执行质量的控制工具。

查看源文件: GitHub原始文件