Agent 方法论框架 superpowers 的写计划技能拆解
本文基于 superpowers 仓库 commit 44c9b2d（2026-07-27）梳理，该项目仍在持续迭代，具体行为以仓库 https://github.com/obra/superpowers 最新代码与文档为准。
把步骤压到 2-5 分钟，本质不是为了”任务小一点好干”，而是为了让每一步都有一个明确的、马上能看到的结果——步骤一旦跨过这个尺度，你就失去了判断 Agent 是不是已经跑偏的最后一个观测点。 superpowers 的 writing-plans 技能把这条要求写成了硬约束，同时配了另外两条：每一步要说清楚跑什么命令、期望看到什么；任务描述要自带全部上下文，不能靠”参考上一个任务”。这三条不是三个独立的风格偏好，它们各自堵的是一类具体的失败模式。
这篇拆的是这三条要求分别在防什么。站内已经写过任务拆解的通用尺度（Agent 任务分解粒度）和规格驱动开发的方法论（规格驱动开发 SDD），那两篇讲的是道理本身；本篇讲一个真实的开源项目把这些道理落成了什么样的文件、什么样的模板、什么样的检查动作——你可以直接打开仓库对着看。项目采用 MIT 许可证。
一、粒度：一步一个动作，防的是”错误被淹没在一大段动作里”
skills/writing-plans/SKILL.md 里有个叫 Bite-Sized Task Granularity 的小节，它给的定义只有一句话：每一步是一个动作（2-5 分钟）。然后直接列了一个 TDD 循环作为范例：
- "Write the failing test" - step
- "Run it to make sure it fails" - step
- "Implement the minimal code to make the test pass" - step
- "Run the tests and make sure they pass" - step
- "Commit" - step
注意”跑一遍确认它失败”被单独列成了一步。如果你把”写测试并确认它失败”合成一步，Agent 完全可能写出一个根本没断言任何东西的测试，然后报告”测试已就绪”。拆成两步之后，“期望 FAIL”就成了一个必须被打印出来的中间结果。
这个粒度和任务粒度是两回事。同一份文档里的 Task Right-Sizing 小节给任务下的定义是：任务是能独立走完一轮测试循环、且值得让一个全新的审查者过一道闸的最小单元。它的切分判据很实用——只有当一个审查者可能否掉这个任务、同时批准它旁边那个任务时，才值得切开；配置、脚手架、文档这类附属动作，一律折进它们服务的那个任务里，不单独成任务。
所以结构是两层：任务是审查粒度，步骤是观测粒度。任务过大，你的审查就变成了”看一大坨 diff 找问题”；步骤过大，你就没有中途叫停的机会。
二、可验证性：每一步都写清楚跑什么、期望看到什么
文档里的 Task Structure 给了一个完整的任务骨架，可以直接看它的字段布局：
### 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`
**Interfaces:**
- Consumes: [what this task uses from earlier tasks — exact signatures]
- Produces: [what later tasks rely on — exact function names, parameter
and return types. ...]
后面每个 step 都用 - [ ] 复选框写，而验证类的 step 长这样：
- [ ] **Step 2: Run test to verify it fails**
Run: `pytest tests/path/test.py::test_name -v`
Expected: FAIL with "function not defined"
关键在 Run: 和 Expected: 这一对。写了 Run 而没写 Expected，Agent 跑完命令看到一屏输出，会倾向于把任何不崩溃的结果解释成成功；写了 Expected，判断就从”感觉对不对”变成了字符串比对。这里期望的甚至是一条失败信息——“FAIL with function not defined”，这就把”测试真的红过”变成了可核对的事实，而不是一句自我声明。
这条要求防的是幻觉式完成：Agent 报告做完了，但没有任何一处留下能回溯的证据。它和站内讲的验收标准写法（Agent 任务验收标准）是同一个思路，区别在于 superpowers 把它下沉到了每一个步骤，而不只是任务出口。
配套的还有一节 No Placeholders，直接把一批写法定义成计划失败，不是风格问题：TBD、TODO、“implement later”；“Add appropriate error handling”、“add validation”、“handle edge cases”；“Write tests for the above”（不给出实际测试代码）；只描述做什么而不给出怎么做的步骤（代码类步骤必须带代码块）；引用了任何一个任务里都没定义过的类型、函数或方法。
“add appropriate error handling”这种话为什么危险？因为它读起来像个要求，实际上把决策整个甩给了实现者，而实现者恰恰是文档一开始就假定”对你的代码库零上下文、品味存疑”的那个角色。写计划的人当时脑子里是有具体想法的，写成一句抽象话，那个想法就丢了。
三、上下文自足：不许写”同 Task N”
No Placeholders 里有一条单独值得拎出来：“Similar to Task N”（同 Task N）是禁止的——代码要重复写一遍，因为工程师可能在乱序阅读任务。
这条在单人手写计划的年代看起来纯属啰嗦，但放到 superpowers 的执行链路里就变成了刚需。同仓库的 skills/subagent-driven-development/SKILL.md 描述的执行方式是：每个任务派一个全新的子代理，用 scripts/task-brief PLAN_FILE N 把该任务的完整文本抽成一个单独的文件交给它。文档里写得很明确——永远不要让子代理去读整份计划文件。那么一个写着”同 Task 3”的任务，交到子代理手上就是一句无法解析的话。
Task Structure 里那个 Interfaces 块也是同一个约束的产物。文档自己的解释是：任务的实现者只看得见自己这一个任务，这个块就是它了解相邻任务用什么名字、什么类型的唯一途径。所以 Consumes 要写精确签名，Produces 要写确切的函数名、参数与返回类型。
顺带说一句上下文成本。subagent-driven-development 里提到，派发提示词里贴的东西和子代理打印回来的东西，会在整个会话里一直占着控制方的上下文、每一轮都被重读；它举了一个真实会话中派发提示词达到 42k 字符、其中 99% 是粘贴的历史记录的例子，结论是产物一律用文件交接。这和站内讲的上下文预算（Agent 上下文预算）是一回事，只是它给出了具体的落地手段：脚本抽取、文件路径传递、返回值限长。
四、这套东西由哪些部分组成
下面这张表只列本文实际读过的文件和目录。
| 组成部分 | 它负责什么 | 对应仓库位置 | 你什么时候会碰到它 |
|---|---|---|---|
| 写计划技能本体 | 定义计划文档的头部、任务结构、步骤粒度、禁用写法、自查清单 | skills/writing-plans/SKILL.md | 手上有了规格，准备动代码之前 |
| 计划评审提示词模板 | 派一个评审者检查计划的完整性、与规格的一致性、任务拆分、可实施性 | skills/writing-plans/plan-document-reviewer-prompt.md | 计划写完、还没开始执行时 |
| 子代理驱动执行 | 每任务一个新子代理，任务简报 + 审查包 + 修复轮次 + 台账 | skills/subagent-driven-development/SKILL.md | 计划要在当前会话里执行，且任务之间基本独立 |
| 执行简报与审查包脚本 | 抽取单任务文本、生成 diff 包、解析每份计划专属的工作目录 | skills/subagent-driven-development/scripts/（task-brief、review-package、sdd-workspace） | 派发实现者与审查者之前的每一次准备动作 |
| 实现者提示词模板 | 规定实现者的自查项、四种状态回报、报告写进文件而非塞回上下文 | skills/subagent-driven-development/implementer-prompt.md | 你要自己拼派发提示词的时候 |
| 独立会话执行技能 | 没有子代理能力时，在另一个会话里按检查点逐任务执行 | skills/executing-plans/SKILL.md | 你的工具链不支持派子代理 |
| 需求探索技能 | 产出设计文档（规格），存到 docs/superpowers/specs/ 下按日期命名 | skills/brainstorming/SKILL.md | 计划的上游，需求还没定型时 |
计划文档本身的默认存放位置是 docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md，文档同时说明用户自己的偏好可以覆盖这个默认值。
计划头部是强制的，包含 Goal（一句话）、Architecture（两三句）、Tech Stack，以及一个 Global Constraints 段——用来放规格里的项目级约束：版本下限、依赖限制、命名与文案规则、平台要求，每条一行，取值从规格里逐字抄过来。文档写明这一段隐式包含在每个任务的要求里。这个设计解决的是一个很常见的问题：全局约束如果只写在规格里，每任务只看简报的实现者就永远看不到它。
五、计划写完之后的两道关
第一道是自查，写在 SKILL.md 的 Self-Review 节里，明确说这是你自己跑的清单，不是派子代理，只有三项：
- 规格覆盖：把规格每一节过一遍，能不能指到实现它的那个任务，列出缺口。
- 占位符扫描：拿 No Placeholders 那张清单在自己的计划里搜一遍。
- 类型一致性：后面任务里用的类型、方法签名、属性名，和前面任务定义的对不对得上。文档给的例子是 Task 3 里叫
clearLayers()、Task 7 里叫clearFullLayers()——这就是个 bug。
发现问题就地改，不需要再评审一遍。规格里有条要求找不到对应任务，就补一个任务。
第二道是 plan-document-reviewer-prompt.md 这份模板，用来派一个计划评审者。它的检查项是四类：Completeness（TODO、占位符、不完整的任务、缺失的步骤）、Spec Alignment（覆盖规格要求、没有大幅范围蔓延）、Task Decomposition（任务边界清晰、步骤可执行）、Buildability（工程师照着走会不会卡住）。
这份模板里最值得抄的其实是它的校准段：只标记那些会在实施中造成真实麻烦的问题——实现者做错了东西或者卡住了，算问题；措辞、风格偏好、“有更好”类建议，不算。除非有严重缺口（规格要求缺失、步骤自相矛盾、占位符内容、任务模糊到无法执行），否则一律批准。输出格式也只有 Approved / Issues Found 两个状态，加一段”建议（仅供参考，不阻塞批准）”。
没有这段校准，评审者会把每一处措辞不完美都报成问题，评审就退化成噪音。superpowers 的做法是把校准标准直接写进提示词模板，而不是指望每次派发时临场补一句。
六、边界与代价：它放弃了什么
这套流程有明确的代价，而且不小。
它会让开发变慢。 把每步压到 2-5 分钟意味着计划文档本身要写很长——每个代码步骤都得带真实代码块，不许写”同上一个任务”就得原样重复。对一个改三行的 bug 修复，写这样一份计划的成本远超过直接改。文档自己也划了适用边界：writing-plans 的描述里写的是”当你手上有一份规格或需求、面对一个多步骤任务时”使用。多步骤是前提。
它会让 Agent 更啰嗦。 每步一个 Run 加一个 Expected，意味着执行时要打印大量中间输出；子代理驱动的执行还要额外维护台账文件、简报文件、报告文件、审查包文件。这些都是 token 和 wall-clock。
它不管需求从哪来。 规格是上游 brainstorming 技能的产物，writing-plans 只负责把规格翻成任务。规格本身错了，这套流程会非常高效地把错误实现出来。它的 Scope Check 只做一件事：如果规格覆盖了多个互相独立的子系统，建议拆成多份计划、每份能独立产出可运行可测试的软件——它不判断需求本身对不对。
它对紧耦合的任务不适用。 subagent-driven-development 的判断图里写得很直白：任务不是大体独立、而是紧耦合时，走的分支是”手工执行或先做需求探索”，不进这套子代理循环。
它假定了 TDD。 SKILL.md 开头那行原则是 DRY. YAGNI. TDD. Frequent commits.，示例步骤序列也是标准的红-绿-提交。项目类型如果没法先写测试（比如纯前端视觉调整、探索性数据分析），这个步骤模板要重新设计，直接套会很别扭。
它假定了实现者的画像。 文档明写：假设工程师对你的代码库零上下文、品味存疑，假设他是熟练开发者但几乎不了解你的工具链和问题域，假设他不太懂好的测试设计。这个画像很贴合编码 Agent，但如果执行者是熟悉这套代码库多年的人，这份计划的信息密度对他就是冗余。
七、上手清单：会踩什么，怎么避
只切了任务、没切步骤。 会踩，是因为大多数人已经习惯了”把需求拆成几个任务”，觉得拆到这一层就够了。结果是任务里躺着一句”实现登录逻辑并加上测试”。避法：拿 Task Right-Sizing 和 Bite-Sized Granularity 当两把不同的尺子分两遍过——第一遍问”审查者会不会单独否掉它”来切任务，第二遍问”这一步能不能在几分钟内产出一个能看的结果”来切步骤。
验证步骤只写了命令，没写期望。 会踩，是因为写命令的时候你脑子里默认知道该看到什么，懒得敲出来。结果是执行时判断标准回到了主观感觉。避法：把 Expected: 当成和 Run: 一样的必填项，写不出期望值就说明这一步的设计本来就没想清楚。
用”同 Task 3”省字。 会踩，是因为写计划的人是从头顺着写下来的，脑子里有完整线性上下文。但执行者可能乱序读，子代理更是只拿到自己那一份简报。避法：接受重复，把代码原样再贴一遍。
Global Constraints 段留空或者只写个大概。 会踩，是因为这些约束在规格里已经写过一遍，感觉抄一遍是浪费。结果是每个只看简报的实现者都不知道版本下限和命名规则。避法：逐字抄，别转述。
跳过自查直接开工。 会踩，是因为计划刚写完时你对它最自信。但类型不一致这类问题恰恰只有回头对照才看得出来——Task 3 的 clearLayers() 和 Task 7 的 clearFullLayers() 在写的当下都很自然。避法：三项自查是机械动作，花不了多久，尤其类型一致性那一项必须逐个签名对。
给评审者的提示词里加了”这个不要报”。 会踩，是因为你预判某条会是误报，想省一轮修复循环。subagent-driven-development 里对此有一段很硬的话：不要替评审者预判，如果你写的提示词里出现了 “do not flag”、“don’t treat X as a defect”、“at most Minor” 这类字眼，停下——你是在预判，通常是为了给自己省一轮。避法：让评审者提，你在循环里裁决，并且把裁决记进台账。
忘了给计划留执行入口。 会踩，是因为计划文件写完就觉得完事了。SKILL.md 要求每份计划头部带一行给 Agent 的说明，指明用子代理驱动或独立会话执行来逐任务实施，步骤用复选框语法跟踪。少了这行，下一个会话拿到计划不知道该按什么方式执行。避法：把头部当模板固化，别每次现写。
结尾：一份计划的自检清单
把上面三条硬要求压成可以对着过的四问：
- 随便挑一个步骤，它能在几分钟内产出一个你能当场看到的结果吗？
- 每个验证步骤都写了跑什么命令、期望看到什么字符串吗？
- 随便剪下一个任务，单独发给一个对这个项目一无所知的人，他能开工吗？
- 后面任务里出现的每一个函数名和类型，都能在前面某个任务的
Produces里找到吗？
四问全过，再走 plan-document-reviewer-prompt.md 那道评审关。想继续往下读，顺序建议是先看 skills/subagent-driven-development/SKILL.md——它解释了为什么写计划的这几条要求非要这么严：计划是唯一跨越子代理边界的载体，写计划时省下的每一个字，都会在执行时变成一次澄清往返。如果你的工具链暂时派不了子代理，就看 skills/executing-plans/SKILL.md，它给的是同一份计划在单会话里带检查点执行的路子。要理解编码 Agent 里”技能”这种组织形式本身，可以先看 Claude Code Skills 机制。
本文属于 superpowers 方法论专题（共 30 篇，含三篇与其它开源 Agent 项目的对照）。想看把资产铺满的另一种取向，见 ECC 开源 Agent 套件专题。