Superpowers:给 AI 编程助手装上工程纪律的技能框架

摘要

Superpowers 是一个面向 AI 编程助手（如 Claude Code、Cursor、Codex 等）的开源技能框架，由 Jesse Vincent 创建，GitHub 星标超过 14 万。它的核心价值不在于让 AI “更聪明”，而在于让 AI “更守规矩”——通过 14 个可组合的技能（Skill），将 TDD、设计先行、代码审查、系统化调试等工程实践编码为 AI 的强制行为约束，形成从需求澄清到代码交付的完整工作流。官方基准测试与社区实践均显示，Superpowers 能显著提升测试覆盖率（从 30% 提升至 85%+）、降低返工率（60%-70%），并使 AI 在计划指引下连续自主工作数小时而不偏离方向。但它并非万能——Token 消耗增加、小任务流程过重、无跨会话记忆等局限性同样值得关注。本文基于官方文档和多篇中文社区实践文章，对 Superpowers 进行全面的技术解析与使用指导。

一、Superpowers 是什么？

1.1 定位：一个行为约束框架，而非能力增强插件

Superpowers 的本质是一套面向 AI 编程代理的”开发方法论操作系统”。它不修改模型能力，不提供新的 API 调用，也不替代任何编程工具。它做的事情更为根本——控制 AI 的行动序列。

正如一位深度分析者所总结的：”普通的 Prompt 集合影响的是输出内容；Superpowers 影响的是 Agent 的行动顺序。”这是一个关键区分。传统的 Prompt 像是”限速标志”——建议性的，在压力下容易被忽略；而 Superpowers 的 Skill 像是”减速带”——物理性地嵌入流程，无法绕过。

1.2 要解决的核心痛点

AI 编程助手在无约束状态下，普遍存在以下行为模式：

一位创业者的真实经历颇具代表性：”去年我引入了 10 多个 AI 工具，Bug 率反而飙升了 40%，项目延期两周，团队差点解散。”问题不在于 AI 不够聪明，而在于 AI 不够有纪律。

1.3 四大设计哲学

Superpowers 的整体设计围绕四条核心原则展开：

1. 测试驱动开发（TDD）：先写测试，永远先写测试。写了代码再补测试？删掉重来。
2. 系统化优于临场发挥（Systematic over Ad-hoc）：用流程替代猜测，用方法论替代直觉。
3. 降低复杂度（Complexity Reduction）：严格遵守 YAGNI（你不需要它）、DRY（不要重复自己）、KISS（保持简单）。
4. 证据优于声明（Evidence over Claims）：必须运行验证命令并展示实际输出，禁止说”应该能通过”或”我很有信心”。

1.4 创建者背景

Jesse Vincent 并非普通的开源爱好者——他是 Request Tracker（RT，广泛使用的工单系统）的创建者、Keyboard.io 的发明人、K-9 Mail 的作者，在开源社区深耕超过 20 年。这一背景赋予了 Superpowers 显著的工程实践深度。正如一位社区分析者所言：”这个人做的东西，往往很硬核。”

二、核心工作流深度解析

Superpowers 定义了一条从需求到交付的 7 步标准流水线。Agent 在每个任务开始前都会检查是否有匹配的技能需要触发——这不是建议，而是强制工作流。

2.1 第一步：Brainstorming（头脑风暴）

目的：在写任何一行代码之前，先搞清楚到底要做什么。

触发时机：当 AI 检测到用户意图构建或修改功能时自动触发。这是 Superpowers 的官方冒烟测试——如果你说”帮我做个 React Todo 列表”，AI 不是开始写代码而是开始提问，说明 Superpowers 在工作。

具体操作：

• AI 通过苏格拉底式提问，逐步挖掘需求细节（存储方式、功能边界、技术栈选择、目标用户等）
• 探索多种设计方案的优劣，而非直接给出单一答案
• 将设计文档分段呈现，每段长度控制在可快速阅读和消化的范围内
• 设计确认前存在硬门禁（Hard Gate）：禁止写任何代码、创建任何文件、调用任何实现技能

社区实践反馈：

这一步被社区公认为”杠杆率最高的环节”。一位开发者在构建多文件 Markdown 转 PDF 工具时遭遇了典型教训：头脑风暴过程看起来很彻底（格式、排序、水印等都讨论了），设计文档也非常专业，但核心需求——复杂 Markdown 渲染（GFM 表格、URL 图片、Mermaid 图表）——完全没有被提及。最终工具生成后完全无法使用。教训是：”AI 不会质疑你没说的东西。核心功能需求必须在一开始就明确提出，不要期望 AI 替你发现遗漏。”

另一位有三个项目实践经验的开发者反馈，在复杂工作流项目中，计划阶段曾两次卡住：一次是 AI 读了一个多小时的无关文件仍未输出计划，另一次是在一个 1000+ 行的文件上卡了 30-40 分钟。解决方案是拆分任务范围，并在必要时明确告诉 AI：”你已经有了所有需要的信息，停止读文件，现在输出计划。”

Brainstorming 还有一个鲜为人知的功能：视觉伴侣模式。一位开发者在迭代项目时发现，头脑风暴技能可以自动启动本地 HTTP 服务器，在浏览器中展示 HTML 线框图供用户选择确认——尽管这个功能”为了一个轻量级技能启动整个服务器，感觉有点重”。

预计耗时：5-15 分钟。消耗约 3,000-5,000 Token。

2.2 第二步：Using Git Worktrees（使用 Git 工作树）

目的：创建隔离的工作环境，确保开发不影响主分支。

触发时机：设计获得用户批准后自动触发。

具体操作：

• 在新分支上创建独立的 Git Worktree
• 检查 .worktrees/ 目录是否存在，验证 .gitignore 配置
• 运行 git check-ignore 确认忽略规则
• 安装项目依赖
• 运行基线测试，确保测试环境干净

源码分析者指出，这不仅仅是一个 Git 技巧——”它不是简单地创建一个 worktree，而是要求一个干净的基线。”在创建之前，会进行完整的环境验证。

社区反馈：有开发者指出 Git Worktree 会导致编辑器需要切换不同目录，体验不够流畅。但社区主流观点认为，工作隔离带来的安全性远大于这一不便。

2.3 第三步：Writing Plans（编写实施计划）

目的：将设计拆解为足够细粒度的可执行任务。

触发时机：设计文档获批后自动链式触发。

具体操作：

• 将工作拆分为 2-5 分钟即可完成的小任务
• 每个任务包含精确的文件路径、完整的代码片段和验证步骤
• 按职责而非技术层组织任务
• 计划的编写标准是：“假设执行者对代码库零了解、品味堪忧”——必须详尽到即使一个没有上下文的初级工程师也不会轻易偏离

关键禁令：计划中不得出现”TBD”、”TODO”、”后续实现”、”添加适当的错误处理”、”类似任务 N”等模糊占位符。每一步都必须有实际代码和具体验证命令。

社区经验：一位构建电商 SKU 库存扣减逻辑的开发者分享了粒度示例：”写一个测试”是一步，”运行它确认失败”是另一步——Superpowers 不允许将多个步骤合并。

社区中有一条被广泛认同的建议：不要把计划写得过于详细，要为 TDD 留出指导实现的空间。计划定义”做什么”和”验证什么”，而 TDD 过程负责”怎么做”。

2.4 第四步：Subagent-Driven Development 或 Executing Plans（子代理驱动开发或执行计划）

目的：按计划执行实现，同时防止上下文污染和自我评估闭环。

触发时机：计划就绪后。executing-plans 可自动触发，subagent-driven-development 可能需要手动启用。

Superpowers 提供两种执行模式：

模式一：Subagent-Driven Development（子代理驱动）

• 为每个任务分配独立的子代理（干净上下文，仅包含当前任务描述和相关文件）
• 每个任务经过两阶段审查：先检查规格合规性（是否遗漏/多余功能），再检查代码质量（风格、边界、性能、测试）
• 适合复杂、多文件、需要高质量的任务

模式二：Executing Plans（直接执行）

• 在当前 Agent 上下文中批量执行
• 每批次完成后设置人工检查点
• 适合简单、低上下文的任务

社区实践反馈——关键争议点：

子代理模式是社区讨论最激烈的功能。一位开发者在构建简单工具时发现，项目被拆成 8 个任务、每个任务 3 个子代理（1 个编码者 + 2 个审查者），总计 24 次代理调用。更关键的是，审查仅检查代码格式和与设计文档的字面对齐，并不验证实际运行功能。”即使完成了完整的 Subagent 流程，你拿到的也可能是’通过所有检查但完全不能用’的代码。”

另一方面，在中大型项目中，子代理的价值得到了验证。有开发者在实现一个跨 15 个文件的功能时分享：”不用 Superpowers 时，Claude Code 做到一半就开始修改之前的代码，不得不手动 git rollback。用了 Superpowers，同样的任务，Claude Code 自主工作了两个小时没有偏离计划。”

社区共识：小项目跳过子代理模式，使用直接执行；中大型项目或需要高质量保证的场景才使用子代理。

Token 消耗数据：一位提供了具体数据的作者指出，6 个独立 API 任务——串行执行约 15 分钟 / ~80K Token，并行子代理执行约 6 分钟 / ~90K Token。Token 略高（子代理有独立上下文），但时间节省了 60%。

2.5 第五步：Test-Driven Development（测试驱动开发）

目的：在实现过程中强制执行 RED-GREEN-REFACTOR 循环。

触发时机：每个实现任务中自动触发。

具体操作：

1. RED：编写一个失败的测试
2. 运行测试，确认它确实失败（如果不失败，测试有问题）
3. GREEN：编写最少量的代码使测试通过
4. 运行测试，确认通过
5. 提交（commit）
6. REFACTOR：优化代码，确保测试仍然通过

铁律：如果先写了实现代码再补测试——删除代码，重新开始。这是 Superpowers 中最严格的约束。

社区效果数据：

一位使用 TDD 三个月的开发者分享了体验转变：”以前的节奏是：想很多 → 写很多 → 跑一下看看。现在是：写一个测试 → 写几行代码 → 绿了 → 下一个测试。每个循环不到 5 分钟，认知负荷明显降低。”

争议点：多位社区作者指出，TDD 的强制性在某些场景下不合适——前端页面、快速原型、内部工具不一定需要单元测试，但 Agent 会坚持”先写测试”。一位作者建议在 CLAUDE.md 中为特定场景覆盖 TDD 规则。

2.6 第六步：Requesting Code Review（请求代码审查）

目的：在任务之间进行独立的质量检查。

触发时机：每个任务完成后自动触发。

具体操作：

• 阶段一——规格合规性审查：检查实现是否遗漏了设计中的功能，或添加了设计中没有的功能
• 阶段二——代码质量审查：检查风格、边界处理、性能、测试质量
• 两个阶段的顺序是固定的——先检查”做对了没有”，再检查”做好了没有”
• 严重问题会阻塞进度，需要人工决策

一个值得注意的设计细节是 receiving-code-review 技能：它明确禁止 AI 对审查反馈做出表演性回应（如”您说得对！””好建议！”），要求 AI 先技术验证每条反馈的正确性——如果审查者理解有误，AI 必须用技术论据反驳。

2.7 第七步：Finishing a Development Branch（完成开发分支）

目的：确保所有工作完成后进行最终验证和清理。

触发时机：所有任务完成后自动触发。

具体操作：

• 运行完整测试套件，验证所有测试通过
• 向用户呈现选项：合并到主分支 / 创建 PR / 保留分支 / 丢弃
• 清理 Git Worktree

社区提示：多位开发者强调，即使你”很确定”代码没问题，也绝对不要跳过最终的测试验证门禁。这是防止虚假完成的最后一道防线。

工作流总结图

brainstorming ──(自动)──> writing-plans ──(自动)──> [worktree创建]     │                                                    │     │                                                    ▼     │                              subagent-driven-development     │                              或 executing-plans     │                                    │     │                           ┌────────┴────────┐     │                           │  每个任务循环:   │     │                           │  TDD ──> 实现    │     │                           │  ──> code-review │     │                           └────────┬────────┘     │                                    │     │                                    ▼     │                         finishing-a-development-branch     │     └── systematic-debugging（贯穿全程，遇到 Bug 时触发）

三、技能库（Skills）详解

Superpowers 包含 14 个可组合的技能，按功能分为四大类。所有技能均为纯 Markdown 文件（存储在 ~/.claude/plugins/superpowers/skills/ 中），没有 Python、TypeScript 或任何可执行文件——纯文本指令。

3.1 测试类

3.2 调试类

社区数据显示，系统化调试方法 vs 随机修复方法：前者 15-30 分钟解决问题，后者 2-3 小时仍在混乱中。

3.3 协作类

3.4 元技能类

3.5 自动触发机制

技能的自动触发是 Superpowers 最精妙的设计之一。其工作原理是：

1. 会话启动时，using-superpowers 通过 Hook 注入引导指令（”你拥有 Superpowers，去读取它们”）
2. Agent 在执行任何任务前，都会扫描技能库寻找匹配
3. 触发是基于对话意图的：说”帮我规划这个功能”自动触发 brainstorming，说”开始实现”自动触发 subagent-driven-development

CSO（Claude Search Optimization）：技能描述字段被刻意设计为仅包含”何时使用”，绝不包含”如何操作”。这是反直觉的——如果在描述中写了工作流概要，LLM 的注意力机制会认为”信息已足够”而跳过加载完整的 SKILL.md，导致遗漏铁律和反合理化表格。源码分析者将此称为”描述陷阱”（Description Trap）。

3.6 技能的三层分类

从约束强度来看，技能分为三类：

四、安装与配置指南

4.1 多平台安装

Claude Code（官方市场）

/plugin install superpowers@claude-plugins-official

Claude Code（通过插件市场）

# 先注册市场/plugin marketplace add obra/superpowers-marketplace# 再安装插件/plugin install superpowers@superpowers-marketplace

Cursor

/add-plugin superpowers

或在插件市场中搜索 “superpowers”。

Codex

告诉 Codex：

Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.codex/INSTALL.md

重要提示：Codex 用户需要在配置中启用 multi_agent = true，否则只能获得流程纪律（头脑风暴、计划、TDD），无法获得真正的多代理编排能力。

OpenCode

告诉 OpenCode：

Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.opencode/INSTALL.md

GitHub Copilot CLI

copilot plugin marketplace add obra/superpowers-marketplacecopilot plugin install superpowers@superpowers-marketplace

Gemini CLI

gemini extensions install https://github.com/obra/superpowers

更新：

gemini extensions update superpowers

4.2 安装验证

启动新会话，输入一个应该触发技能的请求，例如”help me plan this feature”或”let’s debug this issue”。如果 Agent 开始提问而非直接写代码，说明安装成功。

社区提示：一种更简洁的安装方式是直接告诉 Agent：”去 https://raw.githubusercontent.com/obra/superpowers/master/README.md 读取安装说明，然后帮我安装。”

4.3 常见配置问题

4.4 中文本地化版本

社区提供了中文本地化分支 jnMetaCode/superpowers-zh，在完整汉化基础上新增 6 个原创中文技能（中文代码审查、中文 Git 工作流、中文技术文档规范等），支持 14 种 AI 编程工具，一键安装：

npx superpowers-zh

4.5 加速配置（高级）

对于熟练用户，可以在 CLAUDE.md 中配置跳过规则以加速简单任务：

• 跳过头脑风暴（当你能清晰表述需求时）
• 禁用 Worktree（当不需要分支隔离时）
• 使用 executing-plans 替代 subagent-driven-development（当任务简单时）

有开发者通过此配置将一个登录功能的实现时间从约 65 分钟压缩到约 26 分钟。

五、实践案例与社区声音

5.1 案例一：从零构建完整功能——多租户 RBAC 权限系统

一位开发者使用 Superpowers 构建了完整的多租户 RBAC 权限系统（NestJS + Prisma + PostgreSQL 后端，Next.js 14 + Tailwind + shadcn/ui 前端），并开源了项目代码。

流程：

1. 头脑风暴阶段明确了关键决策：权限粒度（页面/按钮/API 级别）、超级管理员绕过逻辑、refreshToken 存储方式、审计日志需求、租户维度
2. 设计文档锁定核心决策后才生成计划
3. 后端执行包含 curl 验证命令
4. 前端切换到 ui-ux-pro-max 技能处理设计成熟度
5. 最终通过 Docker Compose 一键启动集成

结果：项目基本可用，流程整体可控。作者坦诚承认：”过程中有不少 Bug 需要处理；由于 AI 幻觉，部分分支出现了偏离，做了一些调整。”

Token 成本警示：作者特别指出，”跑完整个 RBAC 项目的完整流程，实际花费可能远超你的预期——特别是在子代理并行、多轮审查、TDD 反复验证的场景下。”

5.2 案例二：从翻车到上手——大规模自动化重构的教训

一位自称”Claude Code 纯粹主义者”的开发者分享了从失败到成功的真实经历。

第一次尝试——失败：试图用 Superpowers 进行大规模自动化重构。”Superpowers 无法实现全自动重构。对于代码量巨大、历史悠久的代码库，期望一个命令就让 AI 全部改写，目前仍是幻想。”根本原因是”AI 的每一步操作都包含不确定性，这些不确定性逐步累积，最终导致结果偏离预期。”

关键教训：执行过程中未果断判断哪些步骤应该继续、哪些不应强推。”有些做不好的步骤应该延后，而不是硬上。”

第二次尝试——成功：调整策略，在每个确认检查点真正停下来审查，该砍的砍，不该硬推的推迟。

给新手的忠告：”别一上来就用 Superpowers，别一上来就搞大项目。先从小工具、小功能开始。用武侠打比方：内功不足的时候硬练高层心法，会走火入魔。”

5.3 案例三：复杂业务逻辑——电商 SKU 库存扣减

一位开发者使用 Superpowers 完整实现了电商 SKU 库存扣减功能（Python/FastAPI/SQLAlchemy），展示了 7 步工作流在复杂业务逻辑中的表现。

关键价值点：

• 头脑风暴阶段强制讨论了悲观锁 vs 乐观锁、错误详情级别、部分扣减行为——这些是很多人类开发者也容易忽略的设计决策
• 计划中每个步骤的验证命令精确到具体的 curl 调用和预期响应
• 两阶段审查在实践中确实捕获了规格遗漏

模型选择优化建议（来自社区经验）：

• 机械性实现（定义 DTO、写校验）：使用便宜/快速模型
• 集成判断（多文件协调）：使用标准模型
• 架构/审查：使用最强模型
• “不要用旗舰模型来定义 DTO。”

5.4 社区普遍认同的优势

1. 防止方向漂移：计划机制迫使 Agent 在每个任务前”签字确认”，长任务自主工作时间从 10-15 分钟延长到数小时
2. 需求对齐成本下降：头脑风暴主动挖掘未澄清的部分，减少”做完才发现不对”的返工
3. 子代理并行确实更快：中型功能 2-3 倍提速
4. 可扩展性：可以将团队编码规范写成 Markdown 技能，Agent 自动遵循
5. 跨平台支持：一套技能框架适配所有主流 AI 编程工具

5.5 社区普遍讨论的挑战

1. Token 消耗显著增加：短期增加 10-20%，子代理模式下更高。一位作者直言”Opus 调用占总调用的 60%+，一下午开发就烧掉一周的 Token 配额。”社区提出的 Sonnet-first 策略可节省 40%-80%。
2. 小任务流程过重：5 分钟能解决的问题，走完头脑风暴+计划准备就要 10 分钟
3. 无跨会话记忆：每次会话从零开始，不会记住上次学到的教训。Compound Engineering 和 Gstack 在这方面更优
4. 子代理可观测性差：长时间自主运行时，无法实时看到进展
5. AI 仍会跳过流程：即使安装了 Superpowers，AI 仍有可能跳过设计文档直接写代码——必须显式强制
6. 生成的代码仍有 Bug：一位 QA 专业人士明确指出，输出”包含不少 Bug”，用户自身的专业能力对于评估和修复不可或缺
7. 强制性终究是”君子协定”：所有纪律门禁最终是 Markdown 中的约束。如果 AI 幻觉或强行违规，Superpowers 没有外部运行时（如 CI 级阻断）来物理阻止它

六、与其他框架的对比

社区中存在大量对比讨论。以下综合多篇深度分析文章的结论：

6.1 核心对比

6.2 基准测试数据

一项严格的对照实验（相同模型 Claude Opus 4.6、相同 Prompt、零人工干预）显示：

• 质量评分：Gstack 7.6 vs Superpowers 6.1（Gstack 产出更丰富的设计系统、动画、无障碍支持）
• 效率：Superpowers 快 40%，Token 少 50%
• 实验成本：总计约 283K Token，7 个 Agent

核心结论：”Superpowers 是手术刀，Gstack 是手术室。”——Superpowers 适合想写代码的工程师，Gstack 适合想做产品的构建者。

6.3 选型建议

• 需要代码纪律和 TDD：Superpowers
• 需要端到端项目状态管理：GSD
• 需要产品级设计和完整团队模拟：Gstack
• 需要跨会话知识积累：Compound Engineering
• 组合使用（社区共识）：Superpowers 管纪律 + GSD/Gstack 管交付 + ECC 管增强

七、Token 成本优化策略

Token 消耗是社区反馈最集中的实际问题。以下策略来自社区中最系统的成本优化实践：

7.1 Sonnet-first 策略

核心思路：默认使用较小模型（Sonnet/Haiku），仅在特定条件下升级到 Opus。

7.2 五条团队级规则

1. 连续两次 Sonnet 输出不满意后，才升级到 Opus
2. 单文件、小改动、需求明确：永远不直接用 Opus
3. 审查任务：仅高风险模块用 Opus
4. 摘要、归档、格式化：永远不用 Opus
5. 子代理实现：优先低阶模型，在审查环节补偿质量

八、总结与展望

8.1 核心价值

Superpowers 的价值不在于让 AI 编程更快（短期它甚至会更慢），而在于让 AI 编程更可预测、更可控、更可信赖。它将数十年积累的软件工程最佳实践——TDD、设计先行、代码审查、系统化调试——编码为 AI 的行为约束，填补了”AI 能力强但纪律弱”这一关键缺口。

正如一位社区成员所总结的：”AI 需要的不是更多自由，而是更多约束。纪律不是束缚，是杠杆。”

8.2 适用场景建议

8.3 渐进式采用建议

社区多位有经验的作者建议分阶段采用：

• 第 1 周：只用 brainstorming——培养”先想再做”的习惯
• 第 2 周：加入 writing-plans——培养任务拆解能力
• 第 3 周：加入 test-driven-development——培养测试先行的纪律
• 第 4 周：加入 systematic-debugging——培养根因分析能力
• 第 5 周+：组合使用全部技能

8.4 展望

Superpowers 代表了 AI 编程工具演进中一个重要方向：从关注”AI 能生成什么”转向关注”AI 如何工作”。随着 AI 编程能力的不断增强，行为约束框架的价值只会越来越大——正如人类工程团队中，越是能力强的工程师，越需要清晰的流程来防止个人英雄主义。

从社区讨论中可以观察到几个演进方向：

• 跨会话记忆：当前每次会话从零开始，未来可能引入向量索引的历史对话检索，使 AI 能记住过去的教训
• 技能共享生态：基于 agentskills.io 开放标准的技能市场，像 GitHub PR 一样贡献和分享技能
• 运行时级执行：从 Markdown “君子协定”演进到 CI 级别的物理阻断，真正实现不可绕过的质量门禁
• 与 IDE 深度集成：原生的 Agent HUD（操作面板），解决子代理运行时”不知道它在干什么”的可观测性焦虑

一位深度分析者的判断或许最为精准：”设计 AI 工作流不是在写 Prompt——而是在对 LLM 行为进行深入理解 + 基于这种理解的精密系统工程。”Superpowers 正是这种理解的一个优秀实现。

（全文完）

球外势力 从宇宙尺度，看地球小事

宇宙司令 球外势力常驻代表，星系文明观察员

如果觉得还不错，请关注、点赞、在看、转发，谢谢^-^

关注公众号回复“AI”可一起交流学习 AI 等领域知识，大佬请绕道^-^