Superpowers 入门指南：让 AI 助手真正成为你的编程伙伴

notes › tutorial
, , ,

让 AI 助手不再”跳过步骤”，变成真正可靠的编程伙伴。

📋 目录

  1. 什么是 Superpowers？
  2. 核心理念：流程优先
  3. 技能分类一览
  4. 核心技能详解
  5. 实战示例
  6. 最佳实践
  7. 安装与配置

什么是 Superpowers？

想象一下这个场景：你让 AI 助手帮你实现一个新功能，它直接开始写代码。写完之后你发现遗漏了边界情况，修复后又引入了新 bug。反复几次后，你开始怀疑 AI 是否真的能帮你提效。

这不是 AI 能力的问题，而是工作流程的问题。

Superpowers 是由 Jesse Vincent 和 Prime Radiant 团队开发的完整软件开发工作流，建立在一系列可组合的”技能”(Skills)之上。

它不是让 AI “更聪明”，而是给 AI 一套标准化的工作流程——就像给一个聪明但没有纪律的工程师一本详细的操作手册。

工作原理

  1. 启动时：当你启动编码助手，它不会直接跳进去写代码
  2. 澄清需求：它会退一步，问你真正想做什么
  3. 设计验证：提取规格后，分段展示让你审核
  4. 计划制定：设计通过后，编写清晰的实现计划
  5. 自主执行：启动子代理开发流程，自动工作数小时
1
模糊需求 → Brainstorming → Writing Plans → TDD Implementation → Verification

核心理念：流程优先

Superpowers 的核心原则很简单：永远遵循流程，不跳过任何步骤。

这套理念体现在它的”铁律”中：

Skill 铁律
TDD 没有失败的测试，就不写生产代码
Debugging 没有找到根因，就不尝试修复
Verification 没有运行验证命令，就不声称完成
Brainstorming 没有设计文档被批准，就不开始实现

听起来很死板？但正是这种”死板”，让 AI 的输出变得可预测、可信赖。

设计哲学

  • 测试驱动开发 - 永远先写测试
  • 系统化优于临时方案 - 流程优于猜测
  • 降低复杂度 - 简洁是首要目标
  • 证据优于声称 - 声明成功前必须验证

技能分类一览

Superpowers 包含 14 个核心技能，按功能分为三类：

流程控制类

技能 触发时机 作用
using-superpowers 每次对话开始时 确保正确调用其他技能
brainstorming 任何创造性工作前 将模糊想法转化为清晰设计
writing-plans 有需求规格后 编写详细的实现计划
executing-plans 有实现计划后 执行计划中的任务

实施执行类

技能 触发时机 作用
test-driven-development 实现功能或修复 bug 前 测试先行，红-绿-重构
systematic-debugging 遇到 bug 或测试失败时 系统化定位根因
subagent-driven-development 有独立任务时 并行执行多个子任务
dispatching-parallel-agents 有并发子代理工作时 并发子代理工作流
using-git-worktrees 设计批准后 创建隔离工作空间

质量保障类

技能 触发时机 作用
verification-before-completion 声称完成前 确保验证证据
requesting-code-review 任务之间 按计划审查，报告严重问题
receiving-code-review 收到审查反馈后 处理审查意见
finishing-a-development-branch 任务完成时 验证测试，提供合并/PR/丢弃选项

核心技能详解

1. Brainstorming：从想法到设计

触发条件：任何需要创造新功能、构建组件、修改行为的任务。

这个技能的核心价值是在写代码前先思考清楚。

流程：

  1. 探索项目上下文
  2. 逐个提问澄清需求
  3. 提出 2-3 种方案（附推荐理由）
  4. 呈现设计方案
  5. 用户确认后编写设计文档
  6. 进入 writing-plans

关键规则：

  • 一个问题一条消息：不 overwhelm 用户
  • 提供多选项：2-3 种方案，附带推荐理由
  • 增量验证：每个设计部分都需要确认
  • YAGNI 原则：砍掉不必要的功能

实际对话示例：

1
2
3
4
5
6
7
8
9
10
11
12
AI: 我理解你想添加用户认证功能。让我先了解一下：
    1. 需要支持哪些登录方式？（邮箱密码 / 社交登录 / 手机验证码）
    2. 是否需要"记住我"功能？
    3. 密码重置流程是邮件还是短信？

你: 只需要邮箱密码，不要"记住我"，密码重置用邮件。

AI: 好的，我推荐两种方案：
    A) 使用 JWT 无状态认证 - 适合分布式部署，token 存客户端
    B) 使用 Session 状态认证 - 实现简单，安全性高
    
    考虑到你是单体应用起步，我推荐 B 方案。你觉得呢？

2. Test-Driven Development：测试先行

触发条件：实现任何功能或修复任何 bug 之前。

TDD 的铁律：没有看到测试失败，就不知道测试是否正确。

1
NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST

红-绿-重构循环：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# RED: 先写失败的测试
def test_retry_failed_operations():
    attempts = 0
    def operation():
        nonlocal attempts
        attempts += 1
        if attempts < 3:
            raise Exception("fail")
        return "success"
    
    result = retry_operation(operation)
    assert result == "success"
    assert attempts == 3

# 运行测试 -> FAIL (function not defined)
1
2
3
4
5
6
7
8
9
10
# GREEN: 写最少的代码让测试通过
def retry_operation(fn, max_retries=3):
    for i in range(max_retries):
        try:
            return fn()
        except Exception as e:
            if i == max_retries - 1:
                raise e

# 运行测试 -> PASS

常见借口 vs 现实：

借口 现实
“太简单不用测试” 简单代码也会出错，测试只需 30 秒
“我先实现再补测试” 先写的测试会立刻通过，证明不了什么
“TDD 太慢了” TDD 比事后调试快得多
“我手动测过了” 手动测试无法重复，无法回归

3. Systematic Debugging：根因驱动

触发条件：遇到任何 bug、测试失败、意外行为时。

调试的铁律：没有找到根因，就不尝试修复。

1
NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST

四阶段流程：

  1. Phase 1: 根因调查 - 读错误日志 → 重现问题 → 检查变更 → 收集证据
  2. Phase 2: 模式分析 - 找正常案例 → 对比差异 → 理解依赖
  3. Phase 3: 假设测试 - 单一假设 → 最小改动 → 验证结果
  4. Phase 4: 实施修复 - 写测试 → 修复根因 → 验证通过

多组件系统的证据收集：

当问题涉及多个层面（CI → 构建 → 签名）时，在每个边界添加诊断：

1
2
3
4
5
6
7
8
9
10
11
# Layer 1: Workflow
echo "=== Secrets in workflow: ==="
echo "IDENTITY: ${IDENTITY:+SET}${IDENTITY:-UNSET}"

# Layer 2: Build script
echo "=== Env vars in build: ==="
env | grep IDENTITY || echo "IDENTITY not in environment"

# Layer 3: Signing
echo "=== Keychain state: ==="
security find-identities -v

3 次修复失败法则：

如果 3 次修复尝试都失败了，停止修复，重新审视架构。这通常意味着不是 bug，而是设计问题。

4. Verification Before Completion：证据为王

触发条件：声称工作完成、修复成功、测试通过之前。

1
NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE

门禁函数：

1
2
3
4
5
6
声称任何状态之前：
1. 确认：什么命令能证明这个声称？
2. 运行：执行完整命令（全新的、完整的）
3. 阅读：完整输出，检查退出码，统计失败数
4. 验证：输出是否确认声称？
5. 只有此时：才能做出声称

正确做法 vs 错误做法：

声称 需要 不够
“测试通过” 测试命令输出：0 失败 “应该通过”
“Lint 干净” Linter 输出：0 错误 部分检查、推断
“构建成功” 构建命令：exit 0 Linter 通过、日志看起来正常
“Bug 已修复” 测试原始症状：通过 代码改了，假设已修复

实战示例：一个功能的完整流程

假设你要实现”用户登录限流”功能，Superpowers 的完整流程是这样的：

Step 1: Brainstorming

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
你: 帮我实现登录限流，防止暴力破解

AI: 明白。让我澄清几个问题：
    1. 限流策略是什么？（N 次失败后锁定 / 滑动窗口 / 令牌桶）
    2. 锁定时间多长？
    3. 是否需要区分 IP 和账号？
    
你: 5 次失败后锁定账号 15 分钟，不需要区分 IP

AI: 推荐两种方案：
    A) Redis 计数器 + TTL - 适合分布式，性能高
    B) 数据库字段记录 - 实现简单，单机够用
    
    你的系统目前是单体，我推荐 B 方案。同意吗？
    
你: 同意

AI: [呈现详细设计文档，包含数据模型、API 变更、错误处理...]
    这部分设计看起来对吗？

Step 2: Using Git Worktrees

设计批准后，AI 创建隔离的工作空间：

1
2
# 自动在新分支上创建工作树
git worktree add ../my-project-feature -b feature/login-rate-limit

Step 3: Writing Plans

AI 编写详细的实现计划（每个步骤 2-5 分钟）：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
## Task 1: 添加数据库字段

**Files:**
- Modify: `models/user.py`
- Test: `tests/models/test_user.py`

- [ ] Step 1: 写失败的测试
- [ ] Step 2: 运行测试确认失败
- [ ] Step 3: 添加字段定义
- [ ] Step 4: 运行测试确认通过
- [ ] Step 5: 提交

## Task 2: 实现限流逻辑
...

## Task 3: 添加 API 端点处理
...

Step 4: Subagent-Driven Development

启动子代理流程：

  • 每个任务启动全新的子代理
  • 两阶段审查：规格合规性 → 代码质量
  • Claude 可以自主工作数小时

Step 5: TDD Implementation

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
# RED
def test_locks_account_after_5_failures(db):
    user = create_user(db, password="correct")
    for _ in range(5):
        result = login(user.email, "wrong")
        assert result.error == "Invalid credentials"
    
    result = login(user.email, "correct")  # 即使密码正确
    assert result.error == "Account locked"

# 运行 -> FAIL

# GREEN
def check_login_limit(user):
    if user.failed_attempts >= 5:
        if user.locked_until and user.locked_until > now():
            raise AccountLocked()
    # ...

Step 6: Verification

1
2
3
4
5
6
7
8
9
10
11
12
$ pytest tests/auth/test_rate_limit.py -v
===== test session starts =====
test_locks_account_after_5_failures PASSED
test_unlocks_after_15_minutes PASSED
test_resets_on_success PASSED
===== 3 passed =====

$ npm run lint
# 无错误

$ npm run build
# exit 0

只有此时，AI 才能说：”功能已实现，测试全部通过。”

Step 7: Finishing a Development Branch

完成所有任务后，AI 提供：

  • 验证所有测试通过
  • 提供选项：合并 / PR / 保留 / 丢弃
  • 清理工作树

最佳实践

1. 不要跳过 Brainstorming

即使需求看起来很简单，也要走一遍设计流程。”简单”的需求往往隐藏着最容易被忽视的假设。

2. 信任流程，不要”灵活变通”

当 AI 说”这个很简单，直接开始写吧”时，正是最容易出问题的时候。

3. 让 AI 解释”为什么”

如果 AI 跳过了某个步骤，问它：”为什么不需要走 X 流程？”

4. 善用 Red Flags

每个 Superpowers 技能都有”Red Flags”列表——当 AI 有这些想法时，说明它在试图绕过流程。

常见的 Red Flags：

  • “只是简单问题” / “这个太简单了”
  • “先试试这个改动能不能修复” / “让我先试试”
  • “应该可以了” / “应该能工作了”
  • “保持这份代码作为参考”（TDD 的 Red Flag）

5. 要求看到失败的测试

如果 AI 说”测试通过了”，但你没看到它运行测试失败的过程，要求它演示 Red-Green 循环。

安装与配置

注意：不同平台安装方式不同。Claude Code 和 Cursor 有内置插件市场，Codex 和 OpenCode 需要手动配置。

Claude Code 官方市场

1
/plugin install superpowers@claude-plugins-official

Claude Code（通过插件市场）

1
2
3
4
5
# 先注册市场
/plugin marketplace add obra/superpowers-marketplace

# 然后安装
/plugin install superpowers@superpowers-marketplace

Cursor

在 Cursor Agent 聊天中：

1
/add-plugin superpowers

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

Codex

告诉 Codex：

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

OpenCode

告诉 OpenCode：

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

Gemini CLI

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

更新：

1
gemini extensions update superpowers

验证安装

启动新会话，请求触发技能的内容（如”帮我规划这个功能”或”调试这个问题”）。代理应自动调用相关的 superpowers 技能。

更新

通过插件更新自动更新技能：

1
/plugin update superpowers

社区与支持

总结

Superpowers 的核心价值不在于让 AI 变得更聪明，而在于给聪明但没有纪律的 AI 一套严格的工作流程。

它的价值体现在：

  1. 可预测性：你知道 AI 会怎么做，不会跳过什么步骤
  2. 可追溯性：每个决策都有记录，每个实现都有测试
  3. 可信赖性：声称完成之前，必须有验证证据

如果你曾在使用 AI 编程助手时遇到过：

  • AI 跳过测试，结果上线后出 bug
  • AI”修复”了一个问题，引入了两个新问题
  • AI 声称”完成”，实际上漏了很多需求

那么 Superpowers 可能就是你需要的——不是更好的 AI，而是更有纪律的 AI。

延伸阅读：