Superpowers 系列（四）：计划契约
很多计划文档失败，是因为它写给“懂上下文的人”看。Agent 读到“补充错误处理”“按现有模式实现”“增加测试覆盖”时，会自动补完细节。问题是每个 Agent 补出来的细节都可能不同。
writing-plans 的设计很明确：计划要写给一个几乎没有项目上下文、测试品味不稳定、但会严格执行步骤的工程执行者。writing-plans/SKILL.md 还要求计划头部写清状态、关联 spec 和执行子技能，这让 plan 从一开始就不是自由备忘录，而是有上游来源和下游执行方式的契约。
计划不是 todo，而是执行契约
todo 描述意图，执行契约描述可操作事实。
一个 todo 可以写：
增加登录失败的错误处理。但执行契约必须回答：
- 修改哪些文件；
- 依赖哪些已有接口；
- 产出哪些函数、类型或行为；
- 先写哪条失败测试；
- 运行什么命令，预期怎样失败；
- 写哪段最小实现；
- 再运行什么命令，预期怎样通过；
- 提交边界是什么。
writing-plans 强迫计划写到这个粒度，是为了让执行者少推断。推断越少，漂移越少；漂移越少，审查越容易。
计划先锁文件结构，再拆任务
这个 Skill 要求在定义任务前先映射文件结构。这个顺序很重要。
如果先拆任务，任务往往按动作拆：写接口、写实现、写测试、写文档。这样的任务很容易跨越多个责任边界，也不一定能独立审查。
如果先锁文件结构，任务会更接近可交付单元：某个文件负责什么，某个接口消费什么，某个任务产出什么给后续任务使用。任务边界由可测试产物决定，而不是由工程动作清单决定。
writing-plans 对 task right-sizing 的定义也很有启发：一个任务是值得接受一次新 reviewer 门禁的最小单元。也就是说，任务不是越碎越好，而是要能独立被拒绝或通过。
No Placeholders 是防漂移的核心
这个 Skill 把很多常见计划语句直接判定为失败：
- “TODO”；
- “添加适当错误处理”；
- “写测试覆盖上述逻辑”；
- “类似上一任务”；
- “按现有模式实现”但不说明模式；
- 引用未定义的函数、类型或参数。
这些语句的问题不是不专业，而是把判断责任转移给执行者。执行者一旦自行补齐，计划就不再是约束，而只是建议。
Superpowers 在这里采用了一种很硬的写法：如果任务需要代码，计划里就应该给出足够具体的代码或测试片段；如果任务依赖接口，计划里就应该写出签名和类型；如果任务要验证，计划里就应该写出命令和期望结果。
plan 绑定 spec，避免计划自我合法化
writing-plans 要求计划头部引用 spec。这个设计避免计划脱离设计自我成立。
spec 是目标和约束的来源，plan 是实现论证。执行者读 plan 时也要能追溯回 spec。后续如果发现 plan 内部矛盾，或者 plan 与 spec 冲突，应该以 spec 为更高层事实来源。
这点让 plan 不会自我合法化。任务不是凭空存在，它必须能回到上游 spec。
好计划的判断标准
Superpowers 的 plan 不是任务列表，而是可执行合同。判断它是否合格，可以看几个问题。
一份好的计划至少应该具备这些性质：
- 有明确上游 spec；
- 有文件和接口边界；
- 有独立测试或验证方式；
- 有独立提交和回滚边界；
- 任务间接口不能靠执行者临场发明。
如果一个任务不能被低上下文执行者执行，也不能被独立 reviewer 审查，它就不是一个好的计划任务，只是一个愿望。
参考资料：
系列导航：