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

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，你会看到一个新的注入提示：

<session-start-hook><EXTREMELY_IMPORTANT>
You have Superpowers.
​
**RIGHT NOW, go read**: @/Users/你的用户名/.claude/plugins/cache/Superpowers/skills/getting-started/SKILL.md
</EXTREMELY_IMPORTANT></session-start-hook>

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. 更新文档 --- 如果修改影响了系统行为，更新相关文档

核心原则：

Superpowers 是帮助你更好工作的工具，不是束缚你的枷锁。 在紧急情况下，使用你的判断力。但记住：没有测试的代码是技术债， 哪怕是紧急修复，也应该尽快补充测试。

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(
        <ThemeProvider>
          <div>Test Child</div>
        </ThemeProvider>
      );
      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 (
        <NextThemesProvider attribute="class" defaultTheme="system">
          {children}
        </NextThemesProvider>
      );
    }

    运行测试：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(<ThemeToggle />);
      expect(screen.getByRole('button')).toBeInTheDocument();
    });

    test('toggles theme on click', () => {
      render(<ThemeToggle />);
      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 (
        <button
          onClick={() => 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' ? '🌞' : '🌙'}
        </button>
      );
    }

    运行测试：PASS

    任务 4 完成。

    [继续执行剩余任务...]

5.5 步骤四：代码审查

AI: ### 代码审查

    任务 4 完成后，让我进行代码审查...

    规格合规性：
    ✓ ThemeToggle 组件存在
    ✓ 使用 next-themes 的 useTheme hook
    ✓ 正确处理客户端渲染（mounted 状态）
    ✓ 提供无障碍标签

    代码质量：
    ✓ 代码简洁，没有过度设计
    ✓ 使用 TypeScript 类型正确
    ✓ 遵循 React 最佳实践
    ⚠ 建议：可以将图标提取为独立组件，提高可测试性

    是否继续下一个任务？

你: 继续

5.6 步骤五：完成并合并

AI: 所有任务已完成！

    ### 完成开发分支

    我正在使用 finishing-a-development-branch 技能...

    验证结果：
    ✓ 所有测试通过
    ✓ 代码审查通过
    ✓ 没有未提交的更改

    你想要：
    1. 创建 Pull Request
    2. 直接合并到主分支
    3. 保留工作树，稍后处理
    4. 丢弃更改

你: 创建 PR

AI: 好的，我正在创建 Pull Request...

    [使用 gh CLI 创建 PR]

    ✓ PR 已创建: https://github.com/your-repo/pull/42

    标题: feat: 添加主题切换功能

    描述:
    - 添加 next-themes 依赖
    - 实现 ThemeProvider 组件
    - 实现 ThemeToggle 组件
    - 配置 Tailwind 深色模式
    - 支持系统偏好检测和用户偏好持久化

    工作树已保留在 .worktrees/theme-toggle
    你可以继续在此工作或删除它。

5.7 案例总结

通过这个实战案例，我们演示了 Superpowers 的完整工作流：

0. Brainstorming：通过问答明确需求，提出方案，分节展示设计
1. Writing Plans：创建详细的、小粒度的实现计划
2. Git Worktrees：创建隔离的工作空间
3. TDD：严格的 RED-GREEN-REFACTOR 循环
4. Subagent-Driven Development：任务派发 + 两阶段审查
5. Code Review：规格合规性 + 代码质量
6. Finishing Branch：自动处理 PR 创建和工作流收尾

整个过程体现了 Superpowers 的核心理念：系统化优于临时方案，流程胜于猜测。

---

六、创建自定义技能

Superpowers 允许你创建自己的技能。这是通过 writing-skills 技能完成的。

6.1 技能文件结构

skills/
└── your-skill-name/
    └── SKILL.md

6.2 技能模板

创建技能时，使用以下模板结构：

YAML 头部：

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

正文部分：

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

6.3 示例：创建代码审查清单技能

以下是一个代码审查清单技能的示例：

技能名称：code-review-checklist

触发条件：在代码审查前使用，确保审查质量

清单内容：

功能性：

• 代码实现了预期功能
• 边界情况已处理
• 错误处理恰当

代码质量：

• 命名清晰、有意义
• 没有重复代码（DRY）
• 没有过度设计（YAGNI）

测试：

• 有对应的测试
• 测试覆盖主要场景
• 测试遵循 TDD 流程

安全：

• 没有硬编码敏感信息
• 用户输入已验证
• 权限检查正确

---

七、总结

Superpowers 是一个让你的 AI 编程助手变得更可靠、更专业的工具。通过一系列精心设计的技能，它强制执行最佳实践，确保代码质量。

核心优势：

0. 强制规划：在写代码之前先思考清楚要做什么
1. 严格 TDD：先写测试，再写代码，保证代码可测试
2. 系统化调试：不是猜测问题，而是系统地找到根因
3. 自动审查：每个任务完成后自动审查，及时发现问题
4. 工作流自动化：Git 工作树、分支管理、PR 创建自动化

核心工作流：

brainstorming → writing-plans → subagent-driven-development → finishing-a-development-branch

获取帮助：

• GitHub Issues: github.com/obra/superp...
• Marketplace: github.com/obra/superp...

---

本文档基于 Superpowers 最新版本编写