obra/superpowers，是一个面向 AI 编程代理（如 Claude、Cursor 等）的“超能力”框架，它不是传统意义上的库或工具链，而是一套可被 AI 代理理解并自动执行的“技能协议”（Skills Framework）。

它的核心目标是：让 AI 编程助手从“随意写代码”升级为“遵循工程规范的可靠协作者”。

---

🔍 一、Superpowers 是什么？—— 定位澄清

❌ 它不是一个你直接 import 的 JavaScript 库
✅ 它是一套 AI 可读、可执行的指令集 + 工作流模板

你可以把它理解为：

• 给 AI 的“开发 SOP 手册”
• 一套可触发的自动化工作流脚本
• 一种“元编程”：教 AI 如何正确地编程

当你的 AI 编程代理（如 Claude Code）加载了 Superpowers 插件后，它会在对话中自动识别上下文，并激活相应技能（如 TDD、Git 分支管理、计划制定等）。

---

⚙️ 二、工作原理：如何运作？

Superpowers 的执行依赖于 Claude Code（或其他支持插件的 AI IDE）的插件系统，其流程如下：

1. 安装插件

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

这会将 Superpowers 的技能文件（Markdown + 指令）注入到 AI 的上下文中。

2. AI 自动感知上下文

当你开始和 AI 讨论开发任务时（例如：“帮我加个登录功能”），AI 会：

• 检查是否启用了 Superpowers
• 根据当前对话内容，匹配最合适的 Skill

3. Skill 被激活并执行

每个 Skill 是一个 .md 文件（如 skills/test-driven-development/SKILL.md），包含：

• 名称 & 描述（用于 AI 理解何时使用）
• 详细指令（告诉 AI 具体怎么做）

🌟 关键：这些指令是用自然语言写的，但结构化、可操作，AI 会逐条执行。

---

🧠 三、典型工作流示例：添加一个新功能

假设你说：“我想让用户能重置密码。”

Step 1: Brainstorming（头脑风暴）

• AI 不直接写代码，而是问你：
  • “重置密码需要邮箱验证吗？”
  • “是否要设置过期时间？”
• 最终生成一份可确认的设计文档

Step 2: Writing Plan（写计划）

• AI 输出一个清晰的实施计划，例如：

  - [ ] 创建 `/api/reset-password` POST 接口
  - [ ] 添加数据库字段 `reset_token` 和 `token_expires_at`
  - [ ] 编写失败测试（token 无效/过期）
  - [ ] 编写成功测试
  - [ ] 实现最小逻辑
  

Step 3: Subagent-Driven Development（子代理开发）

• AI 启动“子代理”模式：
  • 每个任务由一个独立的 AI 会话处理（避免上下文污染）
  • 每完成一步，自动进行两阶段审查：
    1. 是否符合计划？
    2. 代码质量是否达标？

Step 4: Test-Driven Development（TDD 强制执行）

• AI 必须先写失败测试，看到报错，再写实现
• 如果你试图跳过测试，AI 会拒绝：“根据 Superpowers 规范，必须先写测试”

Step 5: Finishing（收尾）

• 验证所有测试通过
• 提示你：“是否要创建 PR？还是保留分支？”

---

📂 四、代码是如何“执行”的？—— 关键机制

Superpowers 本身不包含可执行代码，它的“执行”完全依赖于 AI 对指令的理解与模拟操作：

组件	内容	如何“执行”
SKILL.md	自然语言指令	AI 阅读后，在对话中模拟执行步骤（如“我现在要创建一个新分支”）
Git 操作	using-git-worktrees 技能	AI 生成 shell 命令建议（如 git worktree add -b feat/reset-password），由你或 IDE 执行
代码生成	subagent-driven-development	AI 输出完整、可粘贴的代码块，带文件路径和验证说明
测试	test-driven-development	AI 先输出测试代码，要求你运行并确认失败，再输出实现

💡 本质上：Superpowers 是一套“AI 可遵循的剧本”，AI 是演员，你是导演（兼执行者）。

---

🧩 五、核心技能（Skills）一览

技能	作用
brainstorming	交互式需求澄清，输出设计文档
writing-plans	将需求拆解为 2–5 分钟可完成的小任务
test-driven-development	强制 RED-GREEN-REFACTOR 流程
using-git-worktrees	自动建议使用 git worktree 隔离开发环境
subagent-driven-development	为每个任务启动独立 AI 会话，避免上下文漂移
requesting-code-review	在任务间自动请求审查，报告问题严重性
finishing-a-development-branch	收尾时提供合并/PR/丢弃选项

---

🌐 六、技术栈依赖

Superpowers 本身是纯文本协议，但它假设你的项目满足以下条件：

• 使用 Git
• 有可运行的测试命令（如 npm test）
• 使用 现代 JS/TS 项目结构
• （推荐）使用 Claude Code 或 Cursor 等支持插件的 AI IDE

它不生成二进制，不编译代码，只生成人类/AI 可读的指令和代码片段。

---

✅ 七、为什么有效？—— 设计哲学

1. Systematic over ad-hoc
   用流程代替猜测，减少 AI 的“自由发挥”

2. Evidence over claims
   要求验证（如“运行测试看是否失败”），而非声称“应该能 work”

3. Complexity reduction
   把大任务拆成原子步骤，降低出错率

4. You Aren’t Gonna Need It (YAGNI)
   只实现当前需要的功能，避免过度设计

---

🚀 总结：Superpowers 的本质

Superpowers 不是一个工具，而是一套“AI 编程代理的操作系统”。
它通过结构化指令，将 AI 从“代码生成器”转变为“遵循工程规范的初级开发者”。

• 代码不是由 Superpowers 执行的，而是由 AI 根据 Superpowers 的规则生成，由你或 IDE 执行。
• 它的成功依赖于 AI 的理解能力 + 人类的监督。
• 它的目标是：让 AI 写的代码，能达到团队 Code Review 的基本标准。

如果你正在用 Claude 或 Cursor 进行 AI 编程，Superpowers 能显著提升代码质量和开发体验。

🔗 官方博客深入解读：Superpowers for Claude Code