Superpowers 插件使用与触发指南

适用范围：Codex App、Codex CLI 、 Codex IDE 扩展、Claude Code、Cursor、Gemini CLI、GitHub Copilot CLI

1. Superpowers 是什么

Superpowers 是一套面向编码智能体的软件开发方法和 Skills 集合。它不会替换模型，也不会直接增加某个外部服务；它主要通过工作流约束，让 Codex 在开发过程中更系统地完成需求澄清、方案设计、任务拆分、测试驱动开发、调试、代码审查和完成验证。

当前 Codex 版 Superpowers 插件以 Skills 为主，不提供 /brainstorming、/systematic-debugging 等斜杠命令。日常使用时应通过自然语言、@ 选择器或明确指定 Skill 来触发。

2. 安装与启用

2.1 Codex App

1. 打开 Codex App 左侧的 Plugins。
2. 在 Coding 或 Developer Tools 分类中找到 Superpowers。
3. 点击插件旁的 +，按界面提示完成安装。
4. 安装后新建一个任务，使插件中的 Skills 在新任务中生效。

2.2 Codex CLI

进入 Codex CLI 后打开插件浏览器：

/plugins

然后：

1. 搜索 superpowers。
2. 打开插件详情并选择 Install Plugin。
3. 安装完成后启动一个新会话。

在 CLI 插件浏览器中，可以对已安装插件执行以下操作：

• 按 Space 启用或停用插件。
• 打开插件详情进行卸载。

2.3 Codex IDE 扩展

1. 打开扩展的 Settings。
2. 进入 Plugins。
3. 搜索并安装 Superpowers。
4. 安装后新建聊天。

2.4 验证是否生效

可以通过以下方式验证：

• 在插件管理页的 Installed 区域确认 Superpowers 已安装并启用。
• 安装后新建任务，再输入：

请说明当前可用的 Superpowers Skills，并指出处理新功能时会优先使用哪个 Skill。

如果安装成功，Codex 应能识别 Superpowers 提供的相关 Skills。若仍无法识别，优先检查是否新建了任务或 CLI 会话，以及插件是否处于启用状态。

3. 使用方法

3.1 直接描述目标

这是最推荐的日常用法。直接说明想要的结果，Codex 会根据任务语义判断应加载哪个 Skill。

给当前 Vue H5 项目增加一个订单详情页。
先澄清需求和交互方案，得到我批准后再制定实施计划。

适合：希望使用完整工作流，但不想记忆 Skill 名称。

3.2 使用 @ 显式选择

在支持插件选择器的 Codex App 中，在提示词输入框键入 @，然后从列表中选择 Superpowers 或具体 Skill，再描述任务。

适合：

• 需要确保本次任务使用 Superpowers。
• 自动触发没有选中预期 Skill。
• 想只运行某个特定工作流。

3.3 在提示词中指定 Skill

可以直接写明要使用的 Skill：

使用 Superpowers 的 brainstorming Skill 梳理这个需求。
先不要修改文件，方案得到我批准后再继续。

或者：

使用 Superpowers 的 systematic-debugging Skill 排查这个报错。
先复现和定位根因，只输出诊断报告，不实施修复。

适合：熟悉工作流，希望精确控制当前阶段。

3.4 指定完整工作流

对于中大型功能，可以明确规定执行顺序和批准节点：

使用 Superpowers 完成这个需求：
1. 先通过 brainstorming 明确需求和方案；
2. 方案批准后使用 writing-plans 输出实施计划；
3. 计划批准后使用 test-driven-development 实施；
4. 完成后进行 code review 和 verification；
5. 展示完整 diff，未经批准不要提交。

适合：跨多个文件、需要测试或需要多人审查的任务。

4. 触发方式

4.1 自动触发

安装并启用后，Codex 会根据 Skill 的描述和当前任务识别相关工作流。用户只需自然描述任务，不必输入固定命令。

例如：

我想给活动页增加一个抽奖记录弹窗。

这类新功能通常会触发 brainstorming，先明确需求和设计，再进入实施计划。

自动触发的优点是简单；缺点是当任务描述过于模糊时，Codex 选择的 Skill 可能与预期不同。这种情况下应使用 @ 或在提示词中写明 Skill。

4.2 显式触发

显式触发有两种方式：

1. 在输入框键入 @，选择插件或 Skill。
2. 在提示词中写出 Superpowers 和具体 Skill 名称。

推荐格式：

使用 Superpowers 的 <skill-name> Skill 完成 <任务>。
当前只执行到 <停止节点>，得到我批准后再继续。

示例：

使用 Superpowers 的 writing-plans Skill，为登录重构生成实施计划。
计划需要包含文件路径、每一步验证方式和回滚考虑；不要修改代码。

4.3 约束触发范围

如果只想使用某个阶段，应明确停止条件：

只使用 brainstorming，不进入实现。

只做 systematic-debugging，定位根因后停止，不修改文件。

只做 requesting-code-review，不直接修复发现的问题。

如果本次不想使用 Superpowers，可以明确说明：

本次不要使用 Superpowers 工作流，只回答概念问题，不执行任何操作。

项目指令和用户的直接要求优先于 Skills，因此明确的范围和停止条件非常重要。

4.4 不支持的触发方式

不要把 Superpowers Skill 当成 Codex 斜杠命令：

/brainstorming
/systematic-debugging
/test-driven-development

这些不是当前 Codex 版 Superpowers 提供的命令。应改用自然语言、@ 选择器或显式指定 Skill。

5. Skill 与触发场景对照

Skill	典型触发场景	推荐提示词开头
brainstorming	新功能、架构调整、交互设计、需求不清晰	“先使用 brainstorming 梳理需求和方案……”
writing-plans	设计已批准，需要拆分实施步骤	“使用 writing-plans 生成包含文件路径和验证步骤的计划……”
executing-plans	已有批准的实施计划，需要分批执行	“按照已批准计划执行，每批完成后等待检查……”
subagent-driven-development	多个明确任务需要分工、逐项审查	“按批准计划分派独立任务，并进行规范和质量两阶段审查……”
dispatching-parallel-agents	多个相互独立的问题可并行处理	“仅对无共享写入的独立任务并行处理……”
test-driven-development	新功能或修复需要测试先行	“使用 TDD，先写失败测试并确认失败原因……”
systematic-debugging	Bug、异常日志、测试失败、行为不稳定	“先复现问题并系统定位根因，不要猜测修复……”
requesting-code-review	实施完成，需要发起代码审查	“根据需求和计划审查当前 diff，按严重程度报告……”
receiving-code-review	收到审查意见，需要验证和处理	“逐条验证审查意见，确认后再修改……”
verification-before-completion	准备宣布完成，需要证据	“运行与改动匹配的验证，并基于实际输出报告结果……”
using-git-worktrees	希望隔离功能开发或并行分支	“为该任务创建隔离 worktree，并先验证基线……”
finishing-a-development-branch	开发完成，需要决定合并、提 PR 或保留	“验证完成后列出分支收尾选项，不要自行合并……”
writing-skills	创建或维护自定义 Skill	“使用 writing-skills 设计并验证一个新 Skill……”

6. 常用提示词模板

6.1 新功能设计

使用 Superpowers 的 brainstorming Skill 设计这个功能。
先阅读项目约束和相关文件，通过提问明确目标、边界条件和异常场景。
给出候选方案和推荐理由；方案批准前不要修改文件。

6.2 Bug 排查

使用 Superpowers 的 systematic-debugging Skill 分析这个问题。
先复现问题，收集日志和代码证据，定位根因并说明因果链。
当前只输出诊断结论和修复计划，不修改代码。

6.3 计划生成

使用 Superpowers 的 writing-plans Skill，根据已批准的方案生成实施计划。
每一步写明文件路径、预期改动、验证命令和通过标准。
计划输出后等待批准，不要开始实施。

6.4 测试驱动实施

使用 Superpowers 的 test-driven-development Skill 执行已批准计划。
严格遵循 RED-GREEN-REFACTOR：先写失败测试并运行，再写最小实现，
测试通过后重构。每个阶段报告实际验证结果。

6.5 代码审查

使用 Superpowers 的 requesting-code-review Skill 审查当前改动。
不要修改文件。重点检查需求符合度、回归风险、边界条件和测试覆盖，
按严重程度列出问题，并标注文件和行号。

6.6 当前项目推荐模板

使用 Superpowers 处理以下需求，并严格遵循项目 AGENTS.md：
<在这里填写需求>

要求：
1. 先列计划，得到批准后才能读取和实施；
2. 修改前读取目标文件，优先复用已有组件和封装；
3. 范围发生变化时停止并重新确认；
4. 完成后运行最小有效验证；
5. 展示完整 diff，未经批准不要提交。

7. 与当前项目规则的关系

当前项目根目录的 AGENTS.md 是仓库级持久约束。Superpowers Skills 必须在这些约束范围内工作，不能绕过项目的批准节点。

在本项目中，推荐执行顺序为：

1. Codex 先读取并遵守 AGENTS.md。
2. 输出本次任务的执行计划，等待明确批准。
3. 批准后，根据任务选择 Superpowers Skill。
4. 修改前读取目标文件，复用已有组件或封装。
5. 发现计划外问题时，只报告，不擅自扩大改动。
6. 实施后运行最小有效验证。
7. 展示完整 diff，并在提交前再次等待批准。

如果 Superpowers 的默认流程与 AGENTS.md 冲突，以用户直接指令和 AGENTS.md 为准。

8. 常见问题

8.1 安装后没有触发

按顺序检查：

1. 插件是否显示在 Installed 中。
2. 插件是否处于启用状态。
3. 安装后是否新建了任务或 CLI 会话。
4. 是否可以通过 @ 找到插件或具体 Skill。
5. 工作区或管理员策略是否限制插件。

8.2 自动选择了错误的 Skill

不要依赖模糊描述，改为显式指定：

使用 Superpowers 的 systematic-debugging Skill，仅诊断问题，不实施修复。

8.3 工作流太重

Superpowers 强调过程和验证，中大型任务收益更明显。对于简单问答，可以明确缩小范围：

这是只读解释任务，不需要 brainstorming、实施计划或代码修改。

8.4 如何停用或卸载

• Codex App：在插件页打开已安装的 Superpowers，选择停用或卸载。
• Codex CLI：运行 /plugins，对已安装插件按 Space 切换启用状态，或打开详情卸载。
• 停用或卸载后，新建任务或会话，避免旧任务继续保留已加载上下文。

8.5 可选遥测

Superpowers 的可选视觉伴侣默认可能从其网站加载品牌图片，并携带插件版本信息；官方说明称不会包含项目细节或用户点击内容。如果需要禁用，可设置环境变量：

SUPERPOWERS_DISABLE_TELEMETRY=true

9. 最佳实践

• 在提示词中同时写清目标、允许的操作和停止节点。
• 中大型任务先设计、再计划、后实施，不要在需求未确认时直接写代码。
• 调试时要求提供根因证据，避免试错式修改。
• 明确要求展示实际测试输出，不接受只说“应该通过”。
• 对跨文件任务使用完整工作流；对简单解释任务主动限制范围。
• 使用工作区既有的 AGENTS.md、组件和封装，避免插件流程覆盖项目规范。

10. 参考资料

• OpenAI：插件的安装、使用与权限说明
• Superpowers 官方 README
• Superpowers Codex 插件清单
• Superpowers：using-superpowers Skill
• Superpowers Skills 列表