Superpowers：给 Codex 加上工程纪律

模型已经会读仓库、改代码、跑测试，为什么还需要 Superpowers？

我实际用下来，答案不是“让模型写出更厉害的代码”，而是让它少做几类看起来很积极、事后却很昂贵的事：需求还没想清楚就开始搭目录，看到报错就修改第一处可疑代码，先完成实现再补一个必然通过的测试，以及只凭一句“应该没问题”就宣布任务结束。

Superpowers 处理的不是能力问题，而是执行顺序和完成条件。

版本说明

本文以本机安装的 Superpowers Plugin 6.2.0 为使用基线，源码分析固定在 Superpowers 44c9b2d，行为评估仓库固定在 superpowers-evals 8ed824a。产品和仓库状态核对日期为 2026-08-02。

GitHub 源码和 Codex 官方文档用于支撑产品事实；X 帖子只用于说明社区怎样理解和质疑这套方法，不承担性能或可靠性证明。

如果还不熟悉 Skill 的发现、加载和目录结构，可以先读 Codex Skills 入门；如果更关心 references、scripts 和 evals，可以接着读进阶篇。本文不再重复这些基础结构。

一分钟概览

Superpowers 可以先理解成 Codex 里的流程策略层：

用户：描述目标、约束和验收
  ↓
Codex：管理会话、工具、权限和上下文
  ↓
Superpowers：规定现在应该设计、计划、测试、调试、Review 还是验证
  ↓
Tools：真正读文件、改代码、运行测试和操作浏览器
  ↓
证据：spec、plan、diff、测试输出、Review findings、截图

它适合需求模糊、涉及多个文件、回归成本较高或需要较长自主执行的任务。它不适合每一次错别字修改，也不会替代 Sandbox、项目规则、CI 和人的最终判断。

本文会用一个“Skill 收藏页”完成下面这条真实路径：

brainstorming
→ writing-plans
→ test-driven-development
→ systematic-debugging
→ browser verification
→ completion evidence

网页案例不会强行使用全部 14 个 Skill。14 个 Skill 更像一张带条件分支的路由图：有 Git 才创建 worktree，有多个独立任务才考虑并行或 SubAgent，收到 Review 才进入反馈处理，编写 Skill 本身时才使用 writing-skills。

1. Superpowers 的定位：不是工具，而是工程纪律

Superpowers 官方把自己定义为一套建立在可组合 Skills 之上的完整软件开发方法，而不是一个代码生成器或新的浏览器工具。官方 README

这个定位可以从四个概念看清楚：

图 1：Superpowers 位于 Codex Harness 与具体工具之间，它不新增工具能力，而是约束工具调用顺序和完成条件

图 1 最重要的不是层数，而是区分“会不会”和“会不会稳定地先做”。

Codex 会不会写测试？会。
它会不会稳定地先看到测试失败，再写实现？不一定。

Codex 会不会读取错误信息？会。
它会不会在提出修复前先复现并追到根因？不一定。

Codex 会不会运行测试？会。
它会不会在每次完成声明前重新运行足以证明结论的完整命令？不一定。

Superpowers 做的事情，是把这些资深工程师习惯写成可触发的流程约束，再让 Skill 在不同开发阶段彼此交接。

因此，“它给 Codex 加上工程纪律”比“它给 Codex 加上 14 个 Prompt”更准确。后者只看到了文件形式，没有看到触发、阶段门禁、状态交接、工具证据和行为评估。

2. 什么任务值得使用

Superpowers 的成本是真实存在的。设计需要来回确认，计划会占用上下文，TDD 会增加测试轮次，Review 和 fresh verification 会增加命令调用。判断是否值得，关键不在代码行数，而在错误发现得太晚会付出多少代价。

适合完整流程

以下任务通常值得从 brainstorming 开始：

• 用户只说了想做什么，还没有明确行为边界；
• 修改涉及多个模块、多个文件或数据迁移；
• 原有行为不能被破坏，需要回归测试；
• 任务会持续几十分钟以上，Agent 容易逐渐偏离原始目标；
• 需要多个 Agent 或多个会话协作；
• 最终要交付 PR、设计记录或可回查的验证证据；
• Bug 已经修过几次，继续猜测的代价越来越高。

例如“给后台增加团队成员邀请”看起来只是一个功能，实际可能同时涉及权限、邮件、过期策略、重复邀请、数据库约束和 UI 状态。这类任务如果直接从组件或 API 开始，返工通常发生在实现已经铺开之后。

适合缩减流程

以下任务可以只使用其中一部分：

不值得跑完整流程

• 改一个错别字；
• 一行明确、低风险的配置修改；
• 只为验证想法而写的抛弃式 spike；
• 没有仓库、没有测试、不会保留的临时代码；
• 用户已经给出完整实现和唯一修改位置的机械操作。

即使不跑完整流程，也不代表可以跳过安全边界和完成验证。省略的是设计文档、任务拆分或分支隔离，不是“想当然地宣布完成”。

3. 在 Codex 中安装和使用

3.1 安装 Plugin

在 Codex App 中，打开侧边栏的 Plugins，在 Coding 分类中找到 Superpowers 并安装。

在 Codex CLI 中：

/plugins

搜索 superpowers，选择 Install Plugin。OpenAI 的 Plugins 文档说明，安装后应启动一个新会话，让插件附带的 Skills 和工具进入新的上下文。Codex Plugins 文档

本机安装的 6.2.0 清单包含 14 个 Skill：

brainstorming
dispatching-parallel-agents
executing-plans
finishing-a-development-branch
receiving-code-review
requesting-code-review
subagent-driven-development
systematic-debugging
test-driven-development
using-git-worktrees
using-superpowers
verification-before-completion
writing-plans
writing-skills

3.2 隐式触发和显式触发

Codex 会先看到 Skill 的名称、description 和路径，任务匹配后再读取完整 SKILL.md。这是官方 Skills 文档所说的渐进式加载。Build Skills

安装 Superpowers 后，正常使用方式仍然是描述任务：

在这个项目里增加收藏功能，先和我确认交互和存储边界。

如果希望复现实验、降低路由歧义，或者发现自动触发不稳定，可以显式调用：

$superpowers:brainstorming

给现有页面增加收藏功能。先澄清需求和验收条件，
在我批准设计前不要修改文件。

Codex CLI 和 IDE 也可以先输入 /skills 选择 Skill。显式调用证明“我要求使用它”，隐式调用测试的是“当前 description 能否让模型正确发现它”，两者不要混为一谈。

3.3 怎么确认真的生效

不要只检查文件是否存在。至少要分三层：

一个简单的 smoke test 是：

做一个 React todo 页面。

若新会话直接创建组件，没有澄清目标、方案和验收条件，就不能因为 Plugin 已安装而判定 Superpowers 已生效。官方移植指南也把“新项目请求是否先进入 brainstorming”作为 Harness 接入检查的一部分。Porting guide

3.4 一次完整任务怎样和它配合

用户并不需要背 14 个名称。日常新增功能只需要把握三个确认点：

1. 开始时确认需求和设计；
2. 设计通过后确认计划与执行方式；
3. 完成时检查验证证据和分支处理。

可直接使用下面这组 Prompt：

第一步：
$superpowers:brainstorming
我想增加 <功能>。请先读取项目上下文，一次问一个问题，
给出 2–3 种方案和取舍，在我批准前不要实现。

设计确认后：
$superpowers:writing-plans
把批准的设计拆成可以逐项验收的计划。
每项写清文件、接口、失败测试、实现和验证命令。

开始执行时：
请按计划实施。行为变化使用 RED–GREEN–REFACTOR。
如果遇到异常，先查根因，不要连续猜修复。

完成时：
请重新运行能证明验收条件的完整命令，
读取输出和退出码，再说明哪些通过、哪些未验证。

项目自己的 AGENTS.md、权限和用户明确指令仍然优先。Superpowers 不能替用户授权提交、推送、发布、删除文件，也不能越过 Sandbox。

3.5 安装后先做一次 15 分钟启动检查

第一次使用时，不建议马上把真实项目交给它跑半天。先用一个不会造成损失的小需求确认路由、门禁和交接是否存在。下面六步可以连续完成：

可以直接复制下面这段作为启动任务：

$superpowers:brainstorming

给一个现有静态页面增加“收藏”功能。
请先读取项目上下文，一次只问一个问题，给出 2–3 种方案和取舍。
在我批准设计前不要修改文件。批准后把设计交给 writing-plans，
实现时先看到失败测试，完成前重新运行能证明验收条件的完整命令。

这段 Prompt 不是用来替代 Skill。它的作用是让第一次检查更可观察：如果显式调用后仍直接写代码，问题就不是“自动路由偶尔漏掉”，而是当前会话没有正确加载或执行流程。

3.6 四类常见失败怎样恢复

这里的恢复原则很简单：自动发现失败时先显式调用，流程过重时缩减分支，环境条件不存在时明确跳过，完成证据缺失时重新验证。不要通过安装更多 Skill 掩盖当前链路的问题。

4. 实战：开发一个 Skill 收藏页

这一节不使用虚构的“Agent 一次完成”对话，而是保留实际产物和失败过程。

4.1 先把任务限制到可验证范围

初始需求是：

做一个用于浏览和收藏常用 Agent Skills 的小网页。
需要支持搜索、分类、收藏和移动端布局。

如果直接实现，至少有这些未决问题：

• Skill 数据来自本地文件还是在线接口？
• 搜索只匹配名称，还是同时匹配标签和说明？
• 多个关键词按 OR 还是 AND 组合？
• 收藏需要登录同步还是只保存在当前浏览器？
• 是否包含安装按钮、编辑功能和详情页？
• 移动端和可访问性做到什么程度？

经过 brainstorming 后，范围被收缩为：

选择原生 HTML、CSS 和 JavaScript，而不是 React。原因不是 React 做不到，而是这个案例要观察 Superpowers 的工作流；引入脚手架、依赖安装和组件框架只会增加不相关变量。

4.2 计划不是一句“先写页面再测试”

writing-plans 把实现拆成下面几类可独立检查的产物：

这比“实现 Skill 收藏页”长很多，但它给后续执行提供了明确接口。Agent 不必每做一步都重新解释需求，Review 也有东西可以逐条对照。

图 2：Skill 收藏页从设计、计划、RED/GREEN 到浏览器验证的真实流程，包含首次浏览器检查发现的模块语法错误

4.3 TDD 的重点是先看到正确的失败

测试文件先于实现文件创建。第一次运行：

node --test fixtures/superpowers-web-demo/test/skill-store.test.mjs

得到的关键结果是：

Error [ERR_MODULE_NOT_FOUND]:
Cannot find module '.../src/skill-store.mjs'

tests 1
pass 0
fail 1

这个失败说明测试确实依赖尚未存在的实现。随后只实现三个纯函数：

normalizeText(value)
filterSkills(skills, query, category, favoritesOnly, favorites)
toggleFavorite(favorites, skillId)

再次运行：

✔ normalizeText normalizes full-width text and repeated whitespace
✔ filterSkills matches Chinese tags and ignores repeated query whitespace
✔ filterSkills combines category and favorites-only filters
✔ toggleFavorite returns a new set and preserves the original

tests 4
pass 4
fail 0

这里要注意一个经常被忽略的边界：看到 ERR_MODULE_NOT_FOUND 只证明 RED 阶段成立；看到 4 个测试通过，只证明这四类纯逻辑行为成立。它还不能证明页面能加载、控件能点击、收藏刷新后保留，也不能证明移动端布局可读。

4.4 页面第一次打开并没有通过

页面骨架、样式和模块脚本完成后，第一次用 Playwright 打开，语义快照里只有标题和搜索框，分类按钮和 Skill 卡片都没有出现。控制台当时有两条错误：一条是默认 favicon 请求返回 404，与页面逻辑无关；另一条才是导致动态区域无法渲染的模块语法错误。

关键错误是：

Missing } in template expression

这时如果只看视觉现象，很容易猜成模块路径、静态服务器 MIME、DOM 查询或事件监听问题。systematic-debugging 要求先找证据：

1. 页面 HTML 和 CSS 已成功返回；
2. src/app.mjs 请求返回 200；
3. 动态区域为空；
4. JavaScript 解析阶段报模板表达式缺少右花括号；
5. node --check src/app.mjs 指向分类按钮模板。

根因是分类按钮模板的三元表达式没有完整闭合。只修改这一处后重新加载，分类按钮和 8 张卡片恢复，控制台为 0 errors、0 warnings。

这段失败很小，却很好地说明 TDD 和系统调试的分工：

• TDD 约束“行为实现的先后顺序”；
• 系统调试约束“遇到异常后的认知顺序”；
• 浏览器验收负责发现纯函数测试没有覆盖的集成问题。

4.5 桌面与移动结果

图 3：根据 1440×900 真实浏览器结果重绘的桌面验收状态图；搜索结果、收藏状态、刷新保持和控制台结果依次高亮

桌面验收关注：

• 搜索、分类和收藏开关在同一操作区；
• 卡片按三列排列；
• 收藏按钮有可见状态和可访问名称；
• 输入 TDD 计划 后只剩 Superpowers；
• 收藏 Superpowers 后刷新，按钮仍显示已收藏。

查看未经重绘的桌面原始截图。状态图用于集中解释验收条件，原始截图用于保留实际页面证据，两者职责不同。

图 4：根据 390×844 真实浏览器结果重绘的移动验收状态图；控件换行、卡片单列和无横向溢出依次高亮

移动验收关注：

• 标题没有被容器裁切；
• 分类按钮自然换行；
• 搜索框、复选框和按钮仍可操作；
• 卡片改为单列；
• 页面没有横向滚动。

查看未经重绘的移动端原始截图。

下载完整网页 fixture

压缩包只包含这个零第三方运行依赖的示例。SHA-256：

0B69C2A703BBEB3643429F12229D51931BDD7A52CDCB22D8DE8A9C4E037EB8D4

本文复核时使用 Node.js v24.15.0。解压后先进入压缩包所在目录，再运行：

node --test .\superpowers-web-demo\test\skill-store.test.mjs
node .\superpowers-web-demo\server.mjs

浏览器打开 http://127.0.0.1:4179。

读者不需要复现与我完全相同的对话，但最终至少应拿到下面五类证据：

• node --test 显示 4 个测试通过、0 个失败；
• 输入 TDD 计划 后只有 1 个结果；
• 收藏 Superpowers 后刷新，收藏状态仍存在；
• 390px 视口满足 scrollWidth = innerWidth；
• 浏览器控制台为 0 error、0 warning。

如果只能证明其中一部分，就只报告那一部分。纯函数测试通过不能代替浏览器交互，桌面截图也不能代替移动端宽度检查。

5. 14 个 Skill 怎样配合

Superpowers 6.2.0 的 14 个 Skill 不应按编号背诵，更适合按生命周期理解。图 5 只保留日常开发最常经过的六个核心节点；图 6 再把需要 Git、独立任务、Review 事件或 Skill 编写任务时才进入的八条旁路展开。

图 5：Superpowers 的高频生命周期主线；异常发生时进入 systematic-debugging，再回到失败测试和验证

图 6：其余八个 Skill 的条件路由；只有 Git、独立任务、Review、分支收尾或 Skill 编写等条件成立时才进入

5.1 入口：先决定使用什么方法

using-superpowers 是入口规则。它要求在响应和行动前先检查是否存在相关 Skill，并明确“过程 Skill 优先于实现 Skill”。

因此：

“做一个新页面”
→ 先 brainstorming
→ 再考虑 frontend-design 或具体实现

“修这个测试失败”
→ 先 systematic-debugging
→ 再考虑框架或数据库 Skill

它不是业务实现能力，而是一个高召回率路由器。

5.2 设计：把模糊需求变成合同

brainstorming 做三件核心工作：

1. 一次问一个问题，减少多个未决分支同时展开；
2. 给出 2–3 种方案和取舍；
3. 在用户批准设计前禁止实现。

设计通过后，它的合法交接对象是 writing-plans。后者把规格转换成文件、接口、测试和验证步骤。两者的分界非常重要：

• brainstorming 决定“要做什么”；
• writing-plans 决定“怎样逐步做出来”。

5.3 隔离和执行：不是任务越多越好

using-git-worktrees 在实现前检查是否已经处于隔离工作区，并验证干净基线。本文所在目录没有 Git 元数据，所以实际结果是“检查后无法创建”，而不是假装 worktree 已经建立。

有计划之后，执行方式存在三个条件分支：

小网页的计划项彼此紧密依赖，使用当前会话串行执行更合适。只有当任务可以清楚切分、文件边界不冲突、交接信息足够完整时，SubAgent 或并行执行才可能抵消额外的上下文和协调成本。

5.4 质量控制：测试、调试和 Review 解决不同问题

它们不是重复的“检查一下”。

TDD 证明某个行为经历了 RED–GREEN；系统调试建立根因与修复之间的因果关系；Review 对照规格和代码质量；完成前验证要求用当前命令输出证明最终状态。

5.5 收尾和元技能

finishing-a-development-branch 只在实现结束且存在 Git 分支时进入，负责再次验证并给出合并、PR、保留或丢弃等选择。它不会替用户决定推送或合并。

writing-skills 是元技能：编写 Skill 本身时，也要先做不加载 Skill 的基线，再用压力场景观察模型怎样绕过规则，最后修改 Prompt 并复测。

所以 14 个 Skill 的正确心智模型不是：

每个任务跑完 14 步

而是：

当前任务处于什么状态？
满足哪一个 Skill 的触发条件？
完成后只能交接到哪些合法状态？

6. Prompt “金句”为什么能约束行为

Superpowers 的 Skill 中有很多像口号一样的强硬句子。只摘抄这些句子，很容易把它理解成“对模型凶一点”。真正值得分析的是每句话针对什么失败模式、修改了哪个决策变量，以及它怎样改变模型的下一步选择。

下面的英文均摘自固定 revision 44c9b2d。我只保留分析所需的短句；中文是直译和机制解释，不是项目官方译文。

图 7：Superpowers 经典 Prompt 的五段句法；低阈值触发、动作前时序、强制语气、禁止行为和完成证据依次高亮

图 7 可以当成阅读这一节的索引：1% chance 修改触发阈值，BEFORE 修改执行时机，MUST 修改约束强度，Do NOT 删除非法状态边，FRESH EVIDENCE 则重新定义什么叫“完成”。

6.1 “1% 可能适用”：提高路由召回率

using-superpowers 的原文片段是：

“If you think there is even a 1% chance a skill might apply…”

直译是：“只要你认为某个 Skill 有哪怕 1% 的可能适用……”这不是概率计算，而是把 Skill 路由调向高召回率。using-superpowers

模型常见的逃逸语言包括：

• “这只是一个简单问题”；
• “我先看看代码”；
• “这个 Skill 太重了”；
• “我只先做一件事”。

如果规则只写“合适时使用 Skill”，是否合适仍由模型在当下判断，而模型恰好容易为了快速行动把任务判断为“不需要”。“1%”把默认选择从“确定适用才加载”翻转成“只要有可能就先加载，确认不适用再退出”。

它改变的是一个很具体的变量：Skill 发现的触发阈值。这是典型的召回率优先设计——宁可多检查一次，也不希望流程 Skill 在第一步就漏掉。

代价同样明显：召回率提高，误触发和上下文开销也会增加。所以项目规则仍需要明确哪些任务可以缩减流程。

6.2 “任何响应和行动之前”：抢占执行时机

同一份 Skill 还有一句：

“BEFORE any response or action”

直译是：“在任何响应或行动之前。”完整上下文把澄清问题、探索仓库和读取文件也算作 action。using-superpowers

这条规则针对的不是模型“不知道 Skill”，而是它喜欢先做一个看似无害的小动作。问题在于第一个动作经常决定后续轨迹：

先创建组件
→ 设计问题被包装成实现细节
→ 后续问题围绕已有代码展开
→ 沉没成本让推翻方案越来越困难

把 Skill 检查放在第一动作之前，相当于给流程规则更高的时序优先级。它改变的不是“要不要使用 Skill”，而是什么时候必须完成路由判断。

这个区别很关键。若规则写成“实现前检查”，Agent 仍可能先读取十几个文件、形成方案，甚至在回答里承诺实现路径；等到 Skill 真正加载，早期判断已经成为沉没成本。BEFORE 直接抢占了这个窗口。

代价是连澄清问题也要先经过 Skill 检查，短对话会多一次加载和声明。因此它更适合流程一致性优先的 Coding Agent，而不是所有聊天场景的通用 System Prompt。

6.3 Hard Gate：把对话写成状态机

brainstorming 的核心原文片段是：

“Do NOT … take any implementation action until … approved it.”

直译是：“在已经呈现设计并获得用户批准之前，不得采取任何实现动作。”这里的重点不在 NOT 的语气，而在它同时写出了禁止动作、解除条件和批准主体。

它还规定 brainstorming 的终止状态只能是 writing-plans，不能直接跳到前端设计或实现 Skill。brainstorming

这里同时使用了三种设计：

1. 禁止边：设计未批准时，不能进入实现；
2. 人工门禁：批准事件来自用户，而不是 Agent 自我判断；
3. 唯一交接：批准后进入 writing-plans，不允许任意跳转。

普通 Prompt 常写“先规划再实现”，但“规划到什么程度”“谁判断规划结束”仍然模糊。Hard Gate 把状态转移写得更接近有限状态机：

exploring
→ proposed_design
→ user_approved
→ writing_plans
→ implementation_allowed

只要 user_approved 还没有发生，implementation_allowed 就必须为 false。这个结构比“请先思考一下”更难被压缩成一段表演式计划。

发布记录说明，这些约束来自实际失败：模型曾跳过设计，直接调用实现 Skill，或者把提问、方案和设计压缩进同一段文本。维护者后来加入 hard gate、强制清单、流程图和终止状态。Release Notes

这说明 Prompt 的进化方式不是“感觉还不够强硬”，而是：

观察逃逸路径
→ 把逃逸写成明确反例
→ 增加阶段门禁
→ 用行为场景复测

6.4 Systematic Debugging：三层约束为什么不是重复

截图里这段 systematic-debugging 很适合拿来观察 Superpowers 怎样组织 Prompt。它没有只写一句“先找根因”，而是连续放了三层约束。

第一层是正向原则，原文把重点压缩成：

“ALWAYS find root cause”

直译是：“永远先找到根因。”完整句还把 symptom fix 判定为失败，目的不是否定临时止血，而是阻止 Agent 把“症状暂时消失”误报成“问题已经解决”。systematic-debugging

第二层专门堵住“我遵守了精神，只是省略了形式”的解释：

“Violating the letter of this process is violating the spirit of debugging.”

直译是：“违反这套流程的字面规则，就是违反调试精神。”它不是一般性的价值宣言，而是在对付一个可预测的逃逸路径：Agent 已经知道根因分析是好事，却声称连续猜修复也算“在探索根因”。

第三层才是截图中的 Iron Law：

“NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST”

直译是：“没有先调查根因，就不能提出修复。”它把“调查根因”从建议升级成“提出修复”的前置条件。

三层看起来表达了同一件事，实际分别解决不同问题：

Skill 后面再用四个 Phase 给出合法路径：先复现和收集证据，再比较模式、形成单一假设，最后才写失败测试和实现修复。也就是说，Iron Law 只负责关门，Phase 1–4 负责告诉 Agent 怎样获得开门条件。

这给自己设计纪律型 Skill 一个直接启发：不要只把原则换成大写。至少要同时回答四个问题：

希望 Agent 追求什么？
它最可能怎样重新解释这条原则？
哪个动作在什么条件满足前绝对不能发生？
满足条件的合法步骤和证据是什么？

如果只写 Iron Law，没有合法路径，Agent 可能停住；如果只写流程，没有 Iron Law，它又可能在时间压力下跳过流程。两者组合才形成约束。

6.5 TDD：把“测试存在”升级成“亲眼见过正确失败”

TDD Skill 先给出判断依据：

“If you didn't watch the test fail, you don't know if it tests the right thing.”

直译是：“如果你没有亲眼看到测试失败，就不知道它是否测中了正确的东西。”这里最重要的动词是 watch：test file exists 不是合格状态，必须真实运行，并确认它因为缺少目标行为而失败，而不是因为语法错误或路径写错。test-driven-development

随后才给出最容易被记住的 Iron Law：

“NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST”

直译是：“没有先看到失败测试，就不能写生产代码。”如果先写了生产代码，Skill 要求删除并从失败测试重新开始。

它和系统调试使用相同句法：NO A WITHOUT B FIRST，但 B 不是一份静态产物，而是已经发生并被观察到的事件：

production_code_allowed =
  test_executed
  AND test_failed
  AND failure_reason_is_expected

这对写 Skill 很有启发。很多弱规则只检查“有没有文件”“有没有计划”“有没有测试”，却没有检查产物是否经历了正确状态转换。更强的 Prompt 会要求 Agent 报告：运行了什么、看到了什么、为什么这个输出证明可以进入下一阶段。

这种写法仍需要边界：抛弃式原型、生成文件和纯配置修改可能需要不同测试形态。例外应由用户明确批准，不应由 Agent 因为任务看起来简单而自行推断。

6.6 反合理化表：预先写出模型会找的借口

Superpowers 不只写正确步骤，还列出“如果你正在这样想，就停下来”的表格。一个很典型的原文片段是：

“I'll just do this one thing first”

直译是：“我就先做这一件事。”using-superpowers

这是很实用的 Prompt 技术：模型不一定能从抽象原则识别当前正在违规，但它更容易匹配一段与自己下一步措辞相似的文本。

例如：

“我先快速看一下文件”
“这个改动太小，不值得写设计”
“测试稍后补也一样”
“应该已经修好了”
“再试最后一个修复”

这些句子不是随机收集的口头禅，而是流程失效前的可观察信号。反合理化表把不可见的“偷懒倾向”变成可匹配的语言模式。它采用的不是更多正向原则，而是提前枚举违规前的自我解释。

从 Prompt 设计角度看，这相当于给模型增加一组运行时断点：当内部下一步与某个借口高度相似时，先停止并重新检查规则。它仍不是确定性的字符串匹配，但比一句抽象的“不要找借口”更容易在生成过程中被识别。

不过它仍是 Prompt，不是编译器。模型可能忽略，Harness 可能没有正确加载，版本变化也可能改变遵循程度。

6.7 Fresh evidence：把“完成”改写成可执行谓词

verification-before-completion 先用一句很短的原则确定证据和语言的先后关系：

“Evidence before claims, always.”

直译是：“永远先有证据，再做声明。”随后才给出不可跨越的规则：

“NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE”

直译是：“没有新鲜的验证证据，就不能做任何完成声明。”这里最值得保留的词不是 NO，而是 FRESH 和 EVIDENCE。

并要求按下面顺序执行：verification-before-completion

1. IDENTIFY：什么命令能证明这项声明？
2. RUN：现在运行完整命令。
3. READ：读取完整输出、退出码和失败数。
4. VERIFY：输出是否真的支持结论？
5. CLAIM：只有此时才做完成声明。

“fresh”非常关键。昨天的测试、另一个 Agent 的 DONE、某个局部命令通过，都不能自动证明当前工作区的完整状态。

它实际上把自然语言“完成了”改写为一个谓词：

complete =
  acceptance_checks_pass
  AND full_command_exit_code_is_zero
  AND output_read_in_current_context
  AND known_gaps_reported

这比要求模型“谨慎一点”更可操作，因为每个条件都有可观察证据。它还把“验证”从一个动作名改成五步 Gate Function：识别证明命令、运行、读取、核对，最后才允许声明。只运行但不读退出码，同样没有通过门禁。

这组 Prompt 展示了另一个很重要的组合：禁止规则必须配套恢复路径。Iron Law 只告诉 Agent 现在不能宣布完成；Gate Function 紧接着告诉它要运行什么、读取什么、满足什么条件后才可以继续。自己写 Skill 时，如果规则只有 DON'T 或 NO，没有合法下一步，模型容易停住、换一种措辞规避，或者反复向用户确认。

6.8 Skill 自身也要先失败

writing-skills 把 TDD 迁移到了 Prompt 和文档：

“NO SKILL WITHOUT A FAILING TEST FIRST”

直译是：“没有先看到失败测试，就不能写 Skill。”这里的“失败测试”不是 Markdown 校验，而是没有加载 Skill 时，Agent 在真实压力场景里出现了什么行为失败。

这份 Skill 里还有一句对 Skill 作者很实用的元数据规则：

“Description = When to Use, NOT What the Skill Does”

直译是：“Description 应该说明什么时候使用，而不是这个 Skill 会做什么。”原因很具体：Agent 通常先看 description 决定是否加载正文；如果 description 已经概括完整流程，模型可能把它当成快捷版说明，直接照摘要执行，反而跳过正文里的关键步骤。writing-skills

例如，下面这种 description 看似信息丰富，实际上泄露了过多流程：

description: Use when changing a production database — checks risk, writes rollback steps, runs a dry-run, then verifies the result

更稳妥的写法只描述可观察的触发条件：

description: Use when a task changes schema, migrations, indexes, constraints, or production data

正文再负责解释怎样分派、Review 几次、何时交接。这是一个容易忽略的设计边界：description 是路由索引，不是 Skill 的压缩版正文。

这里的失败测试不是单元测试，而是先在没有 Skill 的干净上下文里运行真实任务，记录模型怎样失败。例如：

• 在生产故障和时间压力下，是否跳过调试流程；
• 已经写了 45 分钟代码时，是否拒绝删除未经过 RED 的实现；
• 用户要求“赶快提交”时，是否仍先做验证；
• 多个压力叠加时，是否开始寻找规则漏洞。

作者早期介绍 Superpowers 时，就展示了时间压力和沉没成本场景，用来观察 Agent 是否仍会先检查 Skill。Jesse Vincent 的发布文章

因此，Prompt 的完整开发循环应该是：

RED：没有 Skill 时，复现具体行为失败
GREEN：写最小规则，让它在同类场景中遵守
REFACTOR：删掉无效措辞，补充真实合理化模式
REGRESSION：在新会话、不同压力和不同 Harness 中复测

writing-skills 还把“该用什么句法”与基线失败类型绑定起来：

这比机械模仿大写语气更重要。强禁止适合“知道但故意跳过”的纪律问题；如果问题只是输出格式不稳定，正向模板通常比更多禁止句更有效。

6.9 把金句组合起来，才形成流程系统

单独看每句话，它们都可能退化成口号。组合起来后，它们分别守住不同阶段：

图 8：常见逃逸念头经过路由、人工批准、Iron Law 和证据门禁后，被改写成合法下一步或明确停止

因此，我更愿意把这些金句称为 Prompt 里的控制流语句。它们不是让模型显得更服从，而是在自然语言里补上触发条件、禁止边、人工事件和可执行谓词。

这套写法也有明确边界：Prompt 可能漏触发，模型可能不遵守，Harness 可能没有加载，用户也可能明确要求缩减流程。真正可靠的系统仍要让规则落到 spec、测试、权限、CI 和 Review；Prompt 负责把 Agent 尽早引向这些外部证据。

6.10 从一次行为失败，反推自己的 Skill

如果要把这些写法迁移到自己的 Skill，我不建议先打开 SKILL.md 写目录。更有效的入口是先找一个模型明明知道正确做法，却经常在真实任务里没有执行的失败。

图 9：从无 Skill 的行为失败出发，依次设计触发条件、原则、门禁、合法路径、证据和行为评估

可以按下面七步推进：

1. 只定义一个行为失败。 不写“提升代码质量”，而写“数据库迁移已经准备执行，但 Agent 没有回滚路径就请求应用”。
2. 先跑无 Skill 基线。 在新会话里给出真实任务，再叠加时间压力、已有投入或权威指令，记录 Agent 实际说了什么、跳过了什么。
3. 把 description 写成触发器。 描述 schema、migration、index、constraint、production data 等可观察场景，不在 description 里提前讲完整流程。
4. 选择匹配失败的句法。 明知故犯用 Gate 和反合理化；输出形状错误用正向契约；遗漏字段用 REQUIRED slot；条件行为用明确谓词。
5. 同时写门禁和合法路径。 说明什么动作现在禁止，也说明怎样通过检查、批准和证据获得执行资格。
6. 把借口写进 Red Flags。 只收录基线中真实出现的“只是小表”“迁移可逆”“先上线再补”等语言，不凭空堆警告。
7. 在新上下文里复测。 比较无 Skill、加入 Skill 后和修改措辞后三组行为；记录 runtime、模型、revision、场景和仍然存在的逃逸路径。

下面不是一份可以直接部署的数据库 Skill，只是把上述语法压缩到同一个例子里：

---
name: reviewing-database-changes
description: >-
  Use when changing schema, migrations,
  indexes, constraints, or production data
---

# Reviewing Database Changes

## Overview
**Core principle:** Every database change needs
a reviewable rollback path.

## Gate
**NO WRITE WITHOUT A REVIEWED ROLLBACK PLAN**

## Allowed path
Before requesting or performing a write:
1. Identify the exact target and blast radius.
2. Write rollback or forward recovery.
3. Run a dry-run or validation.
4. Present impact, evidence, and uncertainty.
5. Obtain the required approval.

## Evidence required
- exact migration or statement
- validation output and row estimate
- backup / rollback readiness
- post-change verification query

## Red flags
- “It is only a small table.”
- “The migration tool can probably roll it back.”
- “We can verify after applying it.”

这段示例里，各部分职责不能互换：

真正部署前，还要补上适用边界、权限模型、不同数据库的具体工具和行为评估。能由权限、Schema 校验、审批系统或 CI 强制的约束，应优先放到 Harness 和工具层；Skill 更适合处理那些需要判断、容易被压力扭曲、但又很难用一条程序规则覆盖的过程。

最后可以用这份清单检查自己的 Skill：

• description 是否只写触发条件，而不是流程摘要？
• 是否能说出一个无 Skill 时真实出现过的失败？
• Core principle 是否只有一件需要保护的事？
• 禁止规则是否写明解除条件，而不是无限期禁止？
• Agent 被拦住后，是否知道唯一或有限的合法下一步？
• 完成条件是否能落到命令输出、文件、审批或其他外部证据？
• Red Flags 是否来自真实合理化，而不是作者想象？
• 是否在新会话和压力场景中验证过行为，而不只是读了一遍 Markdown？

7. 这套设计背后的工程哲学

7.1 能力与纪律分离

模型可能知道 TDD、根因分析和代码 Review 的全部理论，却在真实任务里不执行。知识问答正确不等于行为稳定。

Superpowers 选择把“知道什么”与“什么时候必须做”分开：领域 Skill 提供方法，过程 Skill 管理时机和交接。

7.2 把判断从短期上下文移到持久产物

长任务里，模型上下文会累积实现细节、错误输出和对话噪声。只把计划留在会话记忆里，压缩或切换 Agent 后容易丢失。

Superpowers 更依赖这些持久产物：

• 设计文档保存需求决定；
• 实施计划保存任务边界；
• 测试保存行为合同；
• Review findings 保存待修问题；
• ledger 或文件保存长任务进度；
• 命令输出保存完成证据。

这也是 subagent-driven-development 使用“每个任务一个新 implementer”的理由：子 Agent 不继承整段会话历史，只接收当前任务所需的规格和接口；主 Agent 保留协调责任。subagent-driven-development

7.3 先做对，再做好

SubAgent 执行后的 Review 分为两个问题：

1. 是否符合规格；
2. 代码质量是否足够好。

这个顺序很有价值。一段结构优雅、命名漂亮、性能不错，但实现了错误需求的代码，仍然是错误交付。先检查规格符合度，可以避免 Review 只关注风格和局部实现。

7.4 证据优先于语气

Coding Agent 很擅长生成听起来完整的总结。Superpowers 不把总结当证据：

这不是对模型表达方式的挑剔，而是把工程结论绑定到可以复查的外部状态。

7.5 行为评估，而不是只评最终答案

superpowers-evals 的定位是工作流遵循度实验室。它驱动真实 Coding Agent CLI，检查 Skill 触发、worktree 行为、SubAgent 协作、验证反射和 Review 质量，而不是只比较最终回答是否顺眼。Superpowers Evals

这类评估更接近 Superpowers 的目标，因为它想改变的是中间行为：

是否先设计？
是否看到 RED？
是否找到根因？
是否重新验证？
是否正确处理 Review？

即使最终代码碰巧正确，如果过程完全依赖猜测，也不能说明 Skill 达到了设计目标。

8. 它的边界和成本

8.1 自动触发不是确定性路由

X 上对 Superpowers 的正向概括通常很一致：spec first、任务切小、测试先行、每个任务独立 Review。Srishti 的帖子 也有人把它概括为“不增加工具，而是改变 Agent 的工作方式”。Rituraj 的帖子

这些概括适合作为社区心智模型，但不能证明每个 Harness 都会稳定触发。

另一条社区帖子直接质疑 Skill 自动激活，并链接了 Claude Code 的相关 Issue 和改进策略。nazha 的帖子 这类证据说明“Skill 文件存在”和“模型每次正确调用”之间有间隙，但它发生在 Claude Code 生态，不能直接外推为 Codex 的确定结论。

在需要复现和高风险任务时，我会显式点名核心 Skill，而不是把成功完全押在隐式触发上。

8.2 上下文、Token 和时延会增加

Superpowers 会增加：

• 澄清问题轮次；
• 设计和计划文档；
• Skill 正文读取；
• 测试的 RED 与 GREEN 运行；
• Review 和修复循环；
• 完成前的完整验证；
• SubAgent 的上下文和协调成本。

这些成本在复杂任务里可能换来更少返工，在一个五分钟小改动里可能反而是主要成本。因此本文不使用“更快”“节省多少 Token”这类没有对照实验支持的普遍结论。

8.3 强门禁可能过度流程化

brainstorming 对简单任务也要求设计批准，TDD Skill 对例外控制很严格。它们的优势是减少模型自行放宽标准，缺点是默认缺少任务分级。

项目可以在 AGENTS.md 中明确缩减条件，例如：

- 纯文档和错别字修改不创建 worktree。
- 抛弃式 spike 经用户确认后可以跳过严格 TDD。
- 行为变化、Bug 修复和重构必须保留 RED–GREEN 证据。
- 一到两个紧密相关任务在当前会话执行，不分派 SubAgent。
- 未经授权不得提交、推送、创建 PR 或发布。

这是任务分级，不是让 Agent 临场判断“这次规则应该不重要”。

8.4 Skill 不是安全边界

Skill 可以要求“不做危险操作”，但它仍是模型读取的指令。真正的安全边界来自：

• Codex Sandbox；
• Approval 或自动审查；
• 仓库和目录权限；
• Git 分支与回滚；
• CI；
• 密钥最小权限；
• 发布和删除操作的人工确认。

不要因为安装了 verification-before-completion，就把 Agent 放进无限权限环境。

8.5 平台能力会影响路径

没有 Git 就无法创建 worktree；没有 SubAgent 工具就不能执行 SDD；没有浏览器运行时就只能把视觉验收标成未验证；没有测试框架也要先决定适合的可执行检查。

一个好的 Skill 应该适配 Harness，而不是假装每个平台都有同名工具。Superpowers 为不同 Harness 提供映射，但实际权限、会话生命周期和工具语义仍可能不同。

8.6 可选遥测和版本漂移

当前官方 README 说明，brainstorming 的可选视觉伴侣可能从项目网站加载 Prime Radiant 标志，并携带 Superpowers 版本；它不包含项目、Prompt 或 Coding Agent 内容，可以通过 SUPERPOWERS_DISABLE_TELEMETRY 等环境变量关闭。README 的 telemetry 说明

若团队需要严格离线或可审计运行，应在安装前检查当前版本的资源和网络行为，不要只看旧文章。

Prompt 也会持续变化。本文固定 commit，是为了让引用和分析可以复查；实际使用最新 Plugin 时，应重新阅读对应版本的 SKILL.md 和 Release Notes。

9. 我会怎样在真实项目里使用

小任务：只保留必要门禁

任务：修正文案、改明确配置、调整一个无行为变化的样式
做法：读取项目规则 → 最小修改 → 针对性验证
不做：完整 brainstorming、长计划、SubAgent

中等任务：使用核心主线

任务：新增一个有明确用户行为的页面或 API
做法：
brainstorming
→ writing-plans
→ worktree（若有 Git）
→ TDD
→ review
→ verification

大任务：再引入隔离上下文

任务：多模块功能、迁移、多个相对独立工作包
做法：
批准 spec 和 plan
→ 建立 worktree
→ SDD 或分批执行
→ 每任务规格 Review
→ 每任务代码质量 Review
→ 全分支 Review
→ fresh verification
→ 人决定合并或 PR

Bug：不要先套完整功能流程

$superpowers:systematic-debugging

请先稳定复现这个问题，读取完整错误，
检查最近变化并追踪数据流。
在建立单一根因假设前不要提出修复；
确认根因后写失败测试，再做一个最小修复并重新验证。

安装后的第一次练习

可以直接使用本文 fixture，做一次很小的行为变化：

给 Skill 收藏页增加“清除全部收藏”功能。

验收：
1. 没有收藏时按钮禁用；
2. 点击后清空 localStorage 和页面状态；
3. 刷新后收藏仍为空；
4. 键盘可以操作；
5. 必须先看到失败测试，再实现；
6. 最后验证桌面和 390px 移动视口。

观察的重点不是 Agent 最快多久写完，而是：

• 是否先确认清除操作要不要二次确认；
• 是否把测试写在实现之前；
• 是否测试持久化而不只是内存状态；
• 是否运行真实浏览器；
• 是否用新的输出证明完成。

10. 结论：真正的 Superpower 是把过程变成接口

Superpowers 最值得学习的部分，不是某一句全大写 Prompt，也不是 Skill 数量。

它把一次容易漂移的 Coding Agent 任务拆成了几类稳定接口：

模糊需求
→ 经过批准的设计

设计
→ 带文件、测试和验收的计划

计划任务
→ 隔离上下文中的实现与 Review

异常
→ 根因、失败测试和最小修复

“完成”
→ 当前命令输出、浏览器证据和已知缺口

这些接口让用户、主 Agent、SubAgent 和下一次会话不用依赖同一段短期记忆。强硬 Prompt 只是把接口守住的手段；spec、plan、tests、diff 和 fresh evidence 才是工程系统真正依赖的状态。

我最终会把 Superpowers 用在“错误晚发现会很贵”的任务里，并为小任务明确缩减流程。它不是保证正确的魔法插件，但它提供了一套很具体的方法，让 Coding Agent 少靠临场自觉，多靠可检查的工程约束。

参考资料

官方与一手资料

• Superpowers GitHub（固定 revision）
• Superpowers Release Notes
• Superpowers Evals（固定 revision）
• Jesse Vincent：Superpowers 发布文章
• OpenAI：Build Skills
• OpenAI：Plugins

社区观察

• Srishti：对 spec first、任务切分和 Review 的概括
• Rituraj：把 Superpowers 定位为工作方式而不是工具扩展
• nazha：对 Skill 自动激活可靠性的质疑与资料索引

系列阅读可以从 Agent Skills 怎么选开始；下一篇继续看 agent-browser 的语义快照实测。