交给编码智能体前，先厘清需求边界

把「让设计文档支持附加文档」交给 coding agent，可能很快就能做出编辑器和历史列表。但作者关心的是另一件事：工程师按旧版操作手册演练失败后，修改了步骤，后来的人还能不能看到当时真正执行的内容？

作者用 Superpowers 推敲需求，核心做法是先用具体场景确定行为，再写规格和实施计划。文章值得看的不是工具有多强，而是它展示了怎样把一句模糊需求，变成 agent 能实现、团队能验收的约束。

先问失败记录该保留什么，再问要不要版本历史

原文围绕一个 Redis 迁移场景展开：团队已有设计文档和实施计划，还需要一份预发布环境的操作手册，也就是 runbook。生产环境则需要另一份。

如果只把需求写成「支持添加文档」，很容易把注意力放在创建、编辑、展示上。真正的难点出现在使用之后：工程师按照 revision 1 演练，记录了一次失败；随后修改步骤，产生 revision 2，再次演练。此时打开第一次失败记录，应该看到哪个版本？

作者给出的要求是，第一次演练必须保留对 revision 1 的引用。后续编辑不能改变这个引用打开的内容。

有历史页面，不代表历史记录就可信。

这里要保存的是事件与当时依据的关系。操作手册描述怎么做，演练记录描述照着做之后发生了什么。两者不能混在一起，也不能因为手册更新，就让旧记录失去解释依据。作者还举了定价规则的例子：发票开出后，即使规则改变，也需要知道当时是哪条规则产生了这张发票。

这种推敲还会逼出范围决策：操作手册能否跨迁移共享？权限跟谁走？重命名或归档之后，旧引用还有效吗？

对于设想中的第一版，作者选择让每份辅助文档只属于一个变更，继承该变更的权限。跨迁移共享和自动执行命令，放到后续工作里。这些选择谈不上普遍最优，但它们让 agent 知道当前要完成什么，也知道哪些能力暂时不做。

好问题要带着使用情境，agent 也该先读项目

作者使用 Superpowers 的 brainstorming skill，在进入设计和实施计划之前，讨论需求与可选方案。按原文描述，这个 skill 还要求 agent 先检查项目，再提出代码和已有文档无法回答的问题。

这一步很实际。项目已经有的权限机制、修订历史或设计决策，应该先查清楚。如果这些信息全靠用户重新讲一遍，讨论既费时间，也可能绕开已有约束。

接下来，提问方式会直接影响规格质量。

「需要版本历史吗？」很容易得到一个「需要」，但这个答案仍然没有说明历史记录要保障什么。作者更希望 agent 给出具体情境：有人按 revision 1 演练失败，修改后按 revision 2 重试，复盘第一次演练的人应该看到什么？

这个问题让用户站到实际使用者的位置上，考虑他需要理解哪次失败、哪些步骤，以及什么证据。

权限也要这样追问。「继承父文档权限」不能只覆盖浏览器里打开的页面，还要覆盖旧版本、搜索结果和通过 agent 访问的内容。否则页面看似限制了访问，其他入口仍可能暴露数据。

作者对 Superpowers 的一个不满，则是外部调研仍需要自己提醒。他希望 agent 能识别哪些决策值得查阅当前文档、参考其他系统的处理方式，再解释资料如何影响建议，并区分来源能够证明的事实与 agent 自己的推断。

这里有个边界：这是作者期待改进的工作流，不能据此认定 Superpowers 已经会自动完成这些研究。原文也没有列出其他系统的实际调研结果。

规格写清行为，实施计划再决定怎么做

作者把 spec 与 implementation plan 分开。前者回答变更需要达成什么，后者回答在当前代码库里如何实现。

对于操作手册，规格可以明确：辅助文档属于一个设计文档并继承权限；演练记录能够引用实际使用的修订版本；编辑、重命名和归档不能破坏授权读者对旧引用的访问；创建了操作手册，也不代表迁移已经成功。

实施计划再处理引用如何存储、哪些 UI 和 agent 操作需要更新，以及如何验证。若项目已经有修订历史，计划还应解释如何复用；另建一套版本系统需要理由。

验收也不能停留在「支持历史版本」。作者把它写成连续操作：创建预发布操作手册，基于 revision 1 记录失败演练，编辑得到 revision 2，再记录一次演练，最后打开第一次演练的引用，确认看到的仍是 revision 1。

验收场景应该验证需要守住的行为，而不只是某个功能入口是否存在。

原文给了一段可直接调整的提示词，用来组织从项目调查到规格、再到实施计划的过程：

Use Superpowers to help me work through this feature before implementation.

Problem:
[Describe a specific situation and what someone needs to accomplish.]

Look through the relevant code, docs, and previous decisions first.
Tell me what already exists that affects this change.

Identify decisions that would benefit from outside research and
research them before recommending an approach. Look for current
documentation and relevant examples of how others solved similar problems.
Link the sources and explain how they affect your recommendation.
Distinguish what the sources establish from your own conclusions.

Ask about decisions we still need to make. Explain what the options
would mean for the feature and recommend an approach.

Make it clear when something is an assumption or your proposal.

Write a spec covering the intended behavior, what's in and out of scope,
unresolved questions, and concrete acceptance scenarios.

Once we've agreed on the spec, create an implementation plan based on
the codebase. Include how we'll check that the important behavior works.

要留意 Once we've agreed on the spec 这一行：实施计划建立在已经达成一致的规格上。同时，开头的 Problem 必须填入真实情境，不能只放一个功能名称。作者以通知功能为例，建议说明谁需要收到通知、发生了什么，以及收到后需要采取什么行动。

我的判断

我赞同这套方法对「历史依据必须保留」的强调。很多需求的难点藏在后续变化里：当前内容更新了，过去的事件还要能被解释。先把这个关系问清楚，比直接讨论数据库字段更有助于确定产品行为。

但原文是作者的工作流分享，操作手册功能也主要以设想方式展开。它没有给出交付耗时、缺陷数量或采用前后的对照数据，因此不能据此判断 Superpowers 比其他工具更有效。

与 agent 的 planning mode 配合一份 Markdown 文件相比，Superpowers 的价值更可能在于提醒团队按步骤检查遗漏；原文没有证明这些步骤必须依赖它。对于边界清楚的小改动，完整规格流程也可能增加维护成本。

外部研究同样需要取舍。权限、历史引用这类容易留下长期约束的决策，值得查证；已有代码足以回答的问题，继续搜索未必有收益。

文章还留下了一个未解决的问题：实现中发现假设错误，规格和计划如何同步？作者目前会在设计文档旁维护 work log，记录变化及原因，但没有给出完整的更新规则。团队采用时，需要明确什么变化应回写规格，什么只进入工作日志，避免下一轮 agent 读到互相矛盾的材料。

能拿来做什么

• 下次让 agent 开发功能时，先给一个具体使用过程，包含参与者、触发事件和后续动作。对于通知功能，写清谁收到、为什么收到、收到后要做什么，再讨论渠道和界面。
• 在现有前端或全栈项目里，让 agent 先检查相关代码、文档和已有决策，列出可以复用的权限与修订机制，然后再提出未决问题。
• 对涉及历史引用的功能，把「创建、使用、修改、重新查看」写成连续验收场景。检查旧记录打开的实际内容，而不只检查历史列表是否存在。
• 将规格、实施计划和变更原因分别记清。实现发现假设错误时，及时修正对应文档，让下一次 AI 编程会话能够理解当前决定及其依据。