04 设计与计划：从想法到可执行任务¶

一、为什么第一步不是写代码¶

Superpowers 先把“我要做一个功能”当成一个尚未收敛的问题。原因很实际：如果需求、边界和验收标准还在变化，直接写实现会把不确定性藏进代码，之后每次返工都更贵。

因此 brainstorming 和 writing-plans 之间存在一个明确的人类确认门：

模糊想法
  → 逐个澄清问题
  → 2–3 种方案与取舍
  → 分段设计
  → 用户批准
  → 写入 spec
  → 逐文件、逐任务实施计划

skills/brainstorming/SKILL.md 甚至把“先呈现设计并等待批准”列为硬门槛，规定在批准前不得调用实现技能、写代码或 scaffold 项目。

二、Brainstorming 的真实输出不是“头脑风暴”¶

它要求的产物更接近一个可执行 spec：

阶段	主问题	可验证输出
理解上下文	当前项目有哪些约束？	文件、文档、历史与范围
澄清目的	用户真正要解决什么？	一次一个问题，避免假设堆积
探索方案	可以怎么做？	2–3 个方案及取舍
呈现设计	具体结构是否合理？	架构、组件、数据流、错误和测试
用户确认	谁对范围负责？	显式批准或修改意见
写入 spec	如何留存决策？	`docs/superpowers/specs/...-design.md`

这里的“一个问题一个消息”不是形式主义，它减少了模型一次性抛出十个问题后又自行填空的机会。

三、为什么要先给方案，而不是只给一个答案¶

brainstorming 要求提供 2–3 个方案，理由是设计问题通常没有唯一技术答案。对 Agent 来说，明确展示取舍可以把隐含偏好暴露给用户：成本、复杂性、可扩展性、交付速度和兼容性分别如何变化。

例如对一个新增报告功能，可以比较：

方案	优点	代价
直接追加 Markdown	快，零依赖	无结构化查询能力
引入数据库	查询灵活	部署、迁移和测试成本上升
生成静态索引	易部署，读写分离	更新链路更复杂

Superpowers 的设计原则不是“总选最复杂的架构”，而是先让选择被看见，再根据范围选择足够小的方案。

四、Writing Plans：把设计翻译成“另一个人也能执行”的任务¶

skills/writing-plans/SKILL.md 要求计划从以下头部开始：Goal、Architecture、Tech Stack 和 Global Constraints。之后每个任务必须明确：

哪些文件创建或修改；
消费哪些前置接口；
产出哪些后续任务依赖的接口；
具体测试；
每一步的预期结果；
何时提交。

这个格式的核心思想是降低隐含上下文。执行者不应该需要重新翻阅整段对话才能知道任务边界。

五、计划任务为什么要小到“2–5 分钟一步”¶

计划不是项目管理甘特图，而是 Agent 执行的控制面。步骤太大，reviewer 无法定位失败原因；步骤太小且没有独立价值，又会让流程变成机械勾选。

一个合格的任务通常形成一次短闭环：

写失败测试 → 运行并确认 RED → 最小实现 → 运行并确认 GREEN → 重构 → 提交

这和 TDD 的红绿重构对齐，也和 SDD 的“一个任务一个 implementer/reviewer”对齐。

六、Spec、Plan 和 Code 的边界¶

flowchart LR
    S[Spec\n为什么做 / 做什么] --> P[Plan\n改哪些文件 / 按什么顺序]
    P --> C[Code\n实现具体行为]
    C --> E[Evidence\n测试 / review / diff]
    E --> V{满足验收?}
    V -- 否 --> S
    V -- 是 --> D[Delivery]

Spec 解决目标、范围、用户体验和选择理由；
Plan 解决实现路径、文件边界、接口和测试顺序；
Code 只负责把当前任务做出来；
Evidence 证明结果，而不是重复描述意图。

混淆这几层会产生两类失败：计划变成一篇没有动作的愿景文，或者代码实现了一个未经用户确认的假设。

七、为什么 Spec 自己也要 review¶

brainstorming 的后半段要求对 spec 做 placeholder、矛盾、范围和歧义检查。因为文档一旦成为计划输入，文档里的模糊会被复制到每一个实现任务中。

典型检查问题：

有没有 TBD、TODO 或“稍后补充”？
架构描述和功能描述是否互相冲突？
是否把多个独立子项目塞进一个计划？
同一名词是否在不同章节指不同对象？

这是一种“在最便宜的阶段修复错误”的策略：在 spec 中改一句话，远比在多文件实现和多个子 Agent 之后回滚成本低。

八、执行方式的选择点¶

当计划完成后，writing-plans 把执行分为两条路径：

Inline execution¶

由当前 Agent 逐任务执行，适合小范围、上下文连续、review 成本低的改动。对应 executing-plans，重点是加载计划、逐项执行、遇到偏差停下来并回到计划。

Subagent-driven development¶

每个任务派一个 implementer，再由 reviewer 检查；适合任务较多、希望隔离上下文和获得独立审查的改动。它不是“多开几个 Agent”这么简单，而是一个有 fix loop 和最终 review 的控制流程，第 5 章会详细展开。

小结¶

设计与计划层把软件开发从一次长对话变成一串可确认的状态迁移。它没有消除不确定性，而是把不确定性提前暴露给用户，把实现阶段留下的问题缩小为文件、接口和测试层面的局部问题。