Superpowers 技术指南：让 AI 编程助手拥有超能力

一、什么是 Superpowers？

1.1 问题背景

如果你曾经用 AI 编程助手开发过复杂应用，大概率会遇到下面这些让人头疼的情况：

• 代码不完整：AI 写了一半就撂挑子，或者干脆跳过了关键功能。
• 缺乏规划：AI 上来就敲代码，根本不先想想整体要怎么做。
• 测试缺失：AI 好像“忘了”还有写测试这回事，或者测试写得马马虎虎。
• 风格不一致：代码质量忽高忽低，缺少统一的开发规范。
• 重复犯错：AI 在不同项目里犯同样的错误，完全没有从过去的教训中学习。

说白了，这些问题的根源在于：AI 编程助手没有一个系统化的工作流程。它只是在被动响应你的指令，而不是主动遵循最佳实践。

Superpowers 就是为解决这个痛点而生的。它是一套完整的软件开发工作流框架，通过一系列可以自由组合的“技能（Skills）”，让 AI 编程助手变得更可靠、更专业。

1.2 核心理念

Superpowers 的设计哲学非常简洁，可以概括为几个关键原则：

→ 测试驱动开发（TDD）——先写测试，再写代码。
→ 系统化优于临时方案——流程胜于猜测。
→ 降低复杂度——简洁是首要目标。
→ 证据胜于声称——验证之后才能宣布成功。

1.3 工作原理

Superpowers 从你启动编程助手的那一刻就开始发挥作用。当你描述想要构建的内容时，它不会急着写代码，而是按部就班地推进：

0. 停下来思考：先搞清楚你真正想要实现什么。
1. 提炼规格：通过对话，把模糊的想法变成清晰的设计。
2. 逐步展示设计：把设计拆成小段，让你逐段审阅确认。
3. 制定实现计划：创建足够详细、可操作的任务清单。
4. 使用子袋里执行：逐个任务落地，每个任务完成后进行代码审查。
5. 自动完成分支：完成后自动处理 Git 工作流的收尾工作。

最关键的是，所有这些技能都是自动触发的——你完全不需要做任何特殊操作。你的编程助手就这么拥有了“超能力”。

二、安装指南

2.1 系统要求

Superpowers 是一个插件，需要配合特定的 AI 编程工具使用。目前支持的平台如下：

平台	支持方式
Claude Code	内置插件市场
Cursor	内置插件市场
Codex	手动安装
OpenCode	手动安装

Claude Code 版本要求：需要 2.0.13 或更高版本。

2.2 安装方式

2.2.1 Claude Code（通过插件市场）

这是最简单的安装方式。在 Claude Code 中执行以下命令：

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

安装完成后，退出并重启 Claude Code，你会看到一个新的注入提示：

You ha ve Superpowers.
**RIGHT NOW, go read**: @/Users/你的用户名/.claude/plugins/cache/Superpowers/skills/getting-started/SKILL.md

2.2.2 Cursor（通过插件市场）

在 Cursor Agent 聊天中，执行：

/plugin-add superpowers

2.2.3 Codex（手动安装）

告诉 Codex：

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

2.2.4 OpenCode（手动安装）

告诉 OpenCode：

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

2.3 验证安装

安装完成后，启动一个新会话，尝试请求一些应该触发技能的内容，例如：

• “帮我规划这个功能”
• “让我们调试这个问题”

如果安装正确，AI 应该会自动调用相关的 Superpowers 技能。

2.4 更新

技能会随插件更新自动更新，只需运行：

/plugin update superpowers

三、技能详解

Superpowers 的核心是一系列可以自由组合的“技能（Skills）”。每个技能都是一份详细的指导文档，告诉 AI 如何正确地完成特定类型的任务。

3.1 基本工作流程

Superpowers 定义了一个完整的开发工作流：

1. brainstorming（头脑风暴）↓ 在写代码之前激活，通过对话提炼需求
2. using-git-worktrees（使用 Git 工作树）↓ 设计批准后激活，创建隔离的工作空间
3. writing-plans（编写计划）↓ 有批准的设计后激活，拆分为小任务
4. subagent-driven-development（子袋里驱动开发）或 executing-plans（执行计划）↓ 有计划后激活，实现各个任务
5. test-driven-development（测试驱动开发）↓ 实现过程中激活，强制 RED-GREEN-REFACTOR 循环
6. requesting-code-review（请求代码审查）↓ 任务之间激活，审查是否符合计划
7. finishing-a-development-branch（完成开发分支）↓ 任务完成后激活，处理合并/PR/清理

重要提醒：AI 会在执行任何任务之前，自动检查是否有相关技能可用。这些是强制性的工作流程，不是可选的建议。

3.2 核心技能详解

3.2.1 brainstorming — 头脑风暴

这是任何创造性工作的起点。AI 在写代码之前，必须通过这个技能先理解你的需求。

触发条件：创建功能、构建组件、添加新功能或修改行为之前。

工作流程：

0. 探索项目上下文——检查文件、文档、最近的提交。
1. 提出澄清问题——每次只问一个问题，逐步理解目的、约束和成功标准。
2. 提出 2-3 种方案——包含权衡分析和推荐建议。
3. 展示设计——按复杂度分节展示，每节后获取你的确认。
4. 编写设计文档——保存到 docs/plans/YYYY-MM-DD-<主题>-design.md 并提交。
5. 过渡到实现——调用 writing-plans 技能创建实现计划。

硬性规则：
在展示设计并获得用户批准之前，不得调用任何实现技能、编写任何代码、搭建任何项目或采取任何实现行动。这条规则适用于每个项目，无论看起来多么简单。

示例对话：
你: 我想给应用添加一个通知系统。
AI: 好的，让我先了解一下项目情况……[检查项目文件和最近提交] 我看到你使用的是 React 和 Node.js。让我问几个问题：你希望通知以什么方式呈现？A) 浏览器推送通知 B) 应用内通知横幅 C) 两者都需要。
你: B，应用内的通知横幅就好。
AI: 明白了。那么通知的触发来源是什么？A) 系统自动生成（如订单状态更新） B) 其他用户发送 C) 两者都需要。
你: A，主要是系统自动生成的。
AI: 好的，让我整理一下设计方案……我推荐三种方案：1. 简单轮询方案——定期查询新通知，实现简单，但可能有延迟。2. WebSocket 实时方案——实时推送，即时显示，但需要维护连接。3. Server-Sent Events 方案——单向实时推送，比 WebSocket 简单。考虑到你的需求，我推荐方案 3：Server-Sent Events。它能提供实时的通知体验，同时实现相对简单。你觉得这个方向如何？

3.2.2 writing-plans — 编写计划

将设计转化为详细的实现计划。这个技能假设执行者是一个“热情但缺乏判断力、没有项目上下文、不喜欢测试的初级工程师”。

触发条件：有了规格或需求的多步骤任务，在触碰代码之前。

任务粒度要求：
每个步骤应该是一个独立的动作，耗时大约 2-5 分钟：

• “编写失败的测试”——一个步骤
• “运行确保它失败”——一个步骤
• “实现最小代码使测试通过”——一个步骤
• “运行测试确保通过”——一个步骤
• “提交”——一个步骤

计划文档格式示例：
计划文档应该包含以下结构：

• 标题：功能名称实现计划
• 目标：一句话描述构建什么
• 架构：2-3 句描述方法
• 技术栈：关键技术/库

每个任务的格式：
### 任务 N: [组件名称]
**文件：**
- 创建: 精确路径/文件.py
- 修改: 精确路径/现有文件.py:123-145
- 测试: tests/精确路径/test.py
**步骤 1: 编写失败的测试**[测试代码]
**步骤 2: 运行测试验证失败**运行命令及预期输出
**步骤 3: 编写最小实现**[实现代码]
**步骤 4: 运行测试验证通过**运行命令及预期输出
**步骤 5: 提交**git commit 命令

执行选择：
计划完成后，AI 会提供两种执行方式：

0. 子袋里驱动（当前会话）——每个任务派发新的子袋里，任务间审查，快速迭代。
1. 并行会话（单独）——在工作树目录打开新会话，批量执行带检查点。

3.2.3 test-driven-development — 测试驱动开发

这是 Superpowers 最核心的技能之一。它强制执行严格的 RED-GREEN-REFACTOR 循环。

铁律：
没有失败的测试先行，就没有生产代码。

RED-GREEN-REFACTOR 循环：
RED（红）↓ 编写失败的测试验证失败↓ 确认测试正确地失败
GREEN（绿）↓ 编写最小代码使测试通过验证通过↓ 确认所有测试通过
REFACTOR（重构）↓ 清理代码保持绿色↓ 确保测试仍然通过
下一轮 → RED

如果已经写了代码怎么办？
Superpowers 的态度非常明确。来看几个常见借口与真相的对比：

借口	真相
“太简单不用测试”	简单代码也会出错。写个测试只需 30 秒。
“我之后再写测试”	之后通过的测试证明不了任何事。
“已经手动测试过了”	临时测试 ≠ 系统测试。没有记录，无法重跑。
“删掉 X 小时的代码太浪费”	沉没成本谬误。保留未验证的代码就是技术债。
“TDD 太教条了，我要务实”	TDD 本身就是务实：在提交前发现 bug 比之后调试快得多。

3.2.4 subagent-driven-development — 子袋里驱动开发

这是一种创新的开发模式：为每个任务派发一个全新的子袋里，实现后进行两阶段审查。

两阶段审查：

0. 规格合规性审查——实现是否符合计划中的规格。
1. 代码质量审查——代码风格、命名、结构是否合理。

优势：

• 每个任务从干净的上下文开始，避免上下文污染。
• 审查确保质量和一致性。
• Claude 可以自主工作数小时而不偏离原始计划。

3.2.5 using-git-worktrees — 使用 Git 工作树

在开始实现之前，自动创建一个隔离的 Git 工作树。

工作流程：

0. 在新分支创建隔离的工作空间。
1. 运行项目设置。
2. 验证干净的测试基准。

优势：

• 可以在同一个项目上并行处理多个任务。
• 不同任务之间不会互相干扰。
• 完成后可以轻松合并或丢弃。

3.2.6 finishing-a-development-branch — 完成开发分支

当所有任务完成后，自动处理收尾工作。

提供的选项：

• 合并到源分支。
• 创建 GitHub Pull Request。
• 保留工作树。
• 丢弃更改。

3.3 其他技能

调试相关

• systematic-debugging — 4 阶段根因分析流程。
• verification-before-completion — 确保问题真正被修复。

协作相关

• dispatching-parallel-agents — 并发子袋里工作流。
• requesting-code-review — 预审查检查清单。
• receiving-code-review — 响应审查反馈。

元技能

• writing-skills — 创建新技能（包含测试方法论）。
• using-superpowers — 技能系统介绍。

3.4 技能文件结构

每个技能都是一个 SKILL.md 文件，包含以下结构：

YAML 头部：

• name：技能名称。
• description：触发条件描述。

正文结构：

• 概述：简要说明技能的目的和用法。
• 流程：详细的步骤说明。
• 原则：关键原则和注意事项。
• 示例：实际使用示例。

四、注意事项

4.1 什么时候使用 Superpowers

推荐使用：

0. 新功能开发：任何需要规划的功能开发都适合。
1. 复杂重构：需要系统性地重构代码时。
2. 学习新项目：Superpowers 会先探索项目上下文，帮助你理解现有代码。
3. 团队协作：生成的计划和文档可以作为团队沟通的基础。
4. 需要高质量代码：TDD 强制保证代码质量。

不推荐使用：

0. 简单的一行修改：比如改一个配置值或修复一个拼写错误。
1. 探索性代码：不确定是否保留的实验性代码。
2. 紧急修复：生产环境紧急修复时，可以先修复再补充文档。
3. 生成的样板代码：如配置文件、构建脚本等。

4.2 关键问题：紧急修改功能代码后，需要重新走流程吗？

这是一个常见问题。分情况讨论会更清楚：

情况一：修改的是当前正在进行的任务
如果你正在使用 Superpowers 实现一个功能，发现需要紧急修改：

• 不需要重新从头开始。
• 应该更新当前的计划和任务以反映变化。
• 继续使用 TDD 流程实现修改。
• 正常完成代码审查和分支合并。

Superpowers 的设计是“流畅迭代”——你可以随时调整方向。

情况二：修改的是已完成的旧功能
如果需要修改一个已经合并的功能：

• 应该作为一个新任务处理。
• 可以快速过一遍 brainstorming（如果问题清楚的话可以简化）。
• 编写失败测试 → 修复 → 验证通过。

情况三：真正的紧急情况
对于生产环境的紧急修复：

0. 先修复问题——不要让流程阻碍紧急响应。
1. 事后补充测试——如果时间紧迫，先修复，但一定要事后补充测试。
2. 更新文档——如果修改影响了系统行为，更新相关文档。

核心原则：流程是为质量服务的，而不是为了束缚手脚。

4.3 常见问题及解决方案

问题 1：技能没有被正确触发

症状：AI 直接开始写代码，没有先进行头脑风暴。
原因：安装后没有重启 Claude Code；插件版本过旧；AI 没有正确识别到应该触发技能。
解决方案：退出并重启 Claude Code。如果问题仍然存在，更新插件：/plugin update superpowers

问题 2：Git Worktree 创建失败

症状：在头脑风暴后，工作树没有被创建。
原因：当前目录不是 Git 仓库；Git 版本过旧（不支持 worktree）；权限问题。
解决方案：确保 Git 版本 >= 2.5（git --version）；确保在 Git 仓库中（git status）。

问题 3：子袋里执行超时或卡住

症状：任务派发给子袋里后长时间没有响应。
原因：任务过于复杂；上下文过大；网络问题。
解决方案：将大任务拆分为更小的任务；清理上下文窗口；选择“并行会话”模式手动执行。

问题 4：TDD 流程被跳过

症状：AI 在没有测试的情况下编写了实现代码。
原因：AI 认为代码“太简单不需要测试”；技能触发失败。
解决方案：明确告诉 AI：“请使用 test-driven-development 技能，即使代码很简单也要先写测试。”

问题 5：升级到新版本后技能失效

症状：升级 Claude Code 或 Superpowers 后，技能不再工作。
原因：技能文件路径变化；新版本的兼容性问题。
解决方案：清除缓存并重新安装：/plugin uninstall superpowers，然后 /plugin install superpowers@superpowers-marketplace。之后退出并重启 Claude Code。

问题 6：设计文档太长，难以审阅

症状：AI 生成的设计文档篇幅过长，难以快速确认。
原因：AI 没有按照“分节展示”的原则；项目本身复杂。
解决方案：提醒 AI：“请分节展示设计，每节不要太长，让我可以逐节确认。”

4.4 最佳实践

保持任务粒度适当

好的任务粒度是 2-5 分钟一个步骤。如果任务太大，拆分它；如果太小，合并它。

好的粒度：
步骤 1: 编写测试验证用户名不能为空
步骤 2: 运行测试确认失败
步骤 3: 添加验证逻辑
步骤 4: 运行测试确认通过

不好的粒度：
步骤 1: 实现完整的用户注册功能（太大）

善用 Git Worktree

Worktree 让你可以同时处理多个任务而不互相干扰。善用这个特性：

# 查看所有 worktrees
git worktree list
# 任务完成后清理
git worktree remove path/to/worktree

定期更新技能

Superpowers 是活跃开发的项目，定期更新可以获得新的技能和改进：/plugin update superpowers

参与技能贡献

如果你创建了有用的技能，可以通过 Pull Request 贡献回社区：

0. Fork 仓库。
1. 创建技能分支。
2. 遵循 writing-skills 技能的指导。
3. 提交 PR。

五、实战案例：为网站添加主题切换功能

下面通过一个完整的实战案例，演示如何使用 Superpowers 为网站添加主题切换功能。

5.1 场景描述

假设我们有一个 Next.js 网站，用户反馈希望在夜间使用时能够切换到深色主题，减少眼睛疲劳。我们需要：

0. 添加浅色/深色主题切换。
1. 支持系统偏好检测。
2. 持久化用户选择。

5.2 步骤一：启动会话，触发 Brainstorming

你: 我想给网站添加一个深色模式切换功能。
AI: 好的，我正在使用 brainstorming 技能来探索你的需求。让我先了解一下项目情况……[检查 package.json、组件目录、样式系统] 我看到你使用的是 Next.js 和 Tailwind CSS。这很好，Tailwind 内置了深色模式支持。让我问几个问题来明确需求：你希望主题切换的方式是什么？A) 仅在设置页面切换 B) 在导航栏提供快速切换按钮 C) 两者都需要。
你: B，在导航栏提供快速切换按钮。
AI: 明白了。那么主题的初始值如何确定？A) 始终使用浅色主题 B) 跟随系统偏好 C) 记住用户上次的选择。
你: B 和 C，首次访问跟随系统，之后记住用户选择。
AI: 好的，让我整理一下设计方案……我推荐两种实现方案：方案 1: 使用 next-themes 库——专为 Next.js 设计，自动处理 SSR 和系统偏好，开箱即用，但增加一个依赖。方案 2: 原生实现——使用 Tailwind 的 class 策略，完全控制实现细节，不增加依赖，但需要处理 SSR 细节。考虑到你的需求（系统偏好 + 持久化 + SSR），我推荐方案 1：使用 next-themes。它能更好地处理 Next.js 的服务端渲染问题。你觉得这个方向如何？
你: 同意，用 next-themes。
AI: 好的，让我展示详细设计：## 架构设计，使用 next-themes 作为主题管理核心，通过 ThemeProvider 包装应用，在导航栏添加 ThemeToggle 组件。这部分看起来对吗？
你: 对的。
AI: ## 组件设计，ThemeProvider：包装 _app.tsx，配置 attribute="class"（Tailwind 兼容），启用系统偏好检测。ThemeToggle：显示太阳/月亮图标，点击切换主题，显示当前主题状态。这部分看起来对吗？
你: 对的。
AI: ## 数据流，1. 用户首次访问 → ThemeProvider 检测系统偏好。2. 用户点击切换 → 更新主题状态 → localStorage 持久化。3. 用户再次访问 → 从 localStorage 恢复主题。这部分看起来对吗？
你: 完美，开始实现吧。
AI: 好的，我正在将设计文档保存到 docs/plans/2025-01-24-theme-toggle-design.md。现在调用 writing-plans 技能创建实现计划……

5.3 步骤二：编写实现计划

AI: 我正在使用 writing-plans 技能创建实现计划。计划已保存到 docs/plans/2025-01-24-theme-toggle.md。## 计划概要，目标：为网站添加深色/浅色主题切换功能。架构：使用 next-themes 管理主题状态，Tailwind dark: 前缀定义深色样式。技术栈：Next.js, Tailwind CSS, next-themes。## 任务列表，1. 安装 next-themes 依赖。2. 创建 ThemeProvider 组件。3. 配置 Tailwind 深色模式。4. 创建 ThemeToggle 组件。5. 在导航栏集成 ThemeToggle。6. 添加过渡动画。7. 测试和验证。你想如何执行？1. 子袋里驱动（当前会话）— 每个任务派发子袋里，任务间审查。2. 并行会话（单独）— 在工作树目录批量执行。
你: 用子袋里驱动。

5.4 步骤三：子袋里执行任务

AI: 好的，我正在使用 subagent-driven-development 技能。首先，让我创建一个 Git worktree 来隔离这个功能……[创建 worktree: .worktrees/theme-toggle]
### 执行任务 1: 安装 next-themes 依赖
[派发子袋里……] 子袋里报告：✓ 已安装 next-themes@0.4.4 ✓ package.json 已更新。任务 1 完成。
### 执行任务 2: 创建 ThemeProvider 组件
这个任务需要编写测试。让我使用 test-driven-development 技能……[进入 TDD 循环] RED - 编写失败的测试。我创建了一个测试，验证 ThemeProvider 正确渲染子组件：
// tests/components/ThemeProvider.test.tsx
import { render, screen } from '@testing-library/react';
import { ThemeProvider } from '@/components/ThemeProvider';
test('renders children correctly', () => {
render(

Test Child

);
expect(screen.getByText('Test Child')).toBeInTheDocument();
});
运行测试：npm test。结果：FAIL - 模块未找到。
GREEN - 编写最小实现。
// src/components/ThemeProvider.tsx
'use client';
import { ThemeProvider as NextThemesProvider } from 'next-themes';
import { ReactNode } from 'react';
export function ThemeProvider({ children }: { children: ReactNode }) {
return ({children});
}
运行测试：npm test。结果：PASS。任务 2 完成。
### 执行任务 3: 配置 Tailwind 深色模式
[修改 tailwind.config.js] module.exports = { darkMode: 'class', // 启用 class 策略 // ... }。任务 3 完成。
### 执行任务 4: 创建 ThemeToggle 组件
[进入 TDD 循环] RED - 编写失败的测试。
// tests/components/ThemeToggle.test.tsx
import { render, screen, fireEvent } from '@testing-library/react';
import { ThemeToggle } from '@/components/ThemeToggle';
test('renders toggle button', () => {
render();
expect(screen.getByRole('button')).toBeInTheDocument();
});
test('toggles theme on click', () => {
render();
const button = screen.getByRole('button');
fireEvent.click(button);
// 验证主题切换逻辑
});
运行测试：FAIL。
GREEN - 编写实现。
// src/components/ThemeToggle.tsx
'use client';
import { useTheme } from 'next-themes';
import { useEffect, useState } from 'react';
export function ThemeToggle() {
const { theme, setTheme } = useTheme();
const [mounted, setMounted] = useState(false);
useEffect(() => { setMounted(true); }, []);
if (!mounted) return null;
return ( setTheme(theme === 'dark' ? 'light' : 'dark')} className="p-2 rounded-lg hover:bg-gray-200 dark:hover:bg-gray-700" aria-label="Toggle theme">{theme === 'dark' ? '☀️' : '