一句话概括：Superpowers 是一套让 Claude Code / Codex / OpenCode 从"会写代码的实习生"升级为"有经验的工程师"的可执行工作流。GitHub 16.1k 星，专治"AI 写完代码不写测试""一口气甩出几千行"等老毛病。

一、为什么你需要 Superpowers？

场景一：你让 Claude Code 做一个待办事项应用，它一上来就给你写了 800 行代码，没有测试、没有设计文档、还改坏了主分支的登录功能。

场景二：你想给项目加一个新功能，AI 立刻就动键盘，问都不问你的真实需求，写出来的东西跟你想的不一样。

这两种痛点的根源，是 AI 缺少一个"工程化的脚手架"。

Superpowers 由 Jesse Vincent（GitHub: obra）开发，提供了一套可组合的"技能"（Skills）+ 触发机制，让 AI 在写代码时自动遵循 TDD（测试驱动开发）、工作区隔离、子代理审查等最佳实践。

本期教程，我们用 "一个完整的待办事项应用" 走完 Superpowers 的端到端流程。

二、四大核心设计哲学

关键洞察：技能文件里用 DOT/GraphViz 语法定义决策流程图——这不是装饰，而是 AI 必须遵循的"可执行规范"。描述只写触发条件（"Use when X"），绝不写流程细节——这是项目团队踩过的坑：写得太详细，AI 反而跳过流程图。

三、端到端工作流（5 阶段）

Superpowers 把"做一个功能"拆成 5 个强制阶段，每个阶段都有专门的技能：

阶段 1：头脑风暴（brainstorming）

你说"我想做一个 X 功能"时，AI 不会直接写代码。它会像苏格拉底一样，一次问一个问题，帮你把模糊想法变成清晰设计。

AI 的行为准则：

• 先侦察：看一眼你的项目目录，了解现有代码结构
• 一次一问：不会一上来甩 10 个问题
• 给你选项：尽量给 A/B/C 选择，而不是让你从零想

设计文档输出：问完所有关键问题后，AI 会把设计分成 200-300 字的小节，每节都问你"这部分对吗？"。全部确认后写入 docs/plans/2025-01-10-todo-app-design.md。

阶段 2：工作区隔离（using-git-worktrees）

设计确认后，AI 会自动创建新分支 + worktree（独立工作目录），确保不污染主分支。

类比：你不会在客厅里直接刷油漆——你会先找一块小墙试色。Git Worktree 就是那块"试验墙"。

为什么这么做？

• 主分支（main）保持干净
• 实验失败直接删 worktree，不影响任何东西
• 可以同时开多个功能分支，互不干扰

阶段 3：编写计划（writing-plans）

把设计拆成 2-5 分钟能完成的小任务。每个任务都有：

• 精确的文件路径
• 完整的代码片段
• 验证步骤（怎么确认这一步做对了）

目标读者："一个没有判断力、没有项目背景、讨厌写测试的热情初级工程师"也能照着做。

阶段 4：子代理驱动开发（subagent-driven-development）

v4.0 的重大创新。

主代理为每个任务派遣一个"新鲜"的子代理（不带历史上下文，避免污染），实现完后进行两阶段审查：

1. 规格符合性审查：代码是否完全符合需求？是否多做了？少做了？
2. 代码质量审查：仅在规格审查通过后才进行。检查代码是否干净、测试覆盖是否足够。

审查是循环的：发现问题→修复→再审查，直到通过。

阶段 5：收尾（finishing-a-development-branch）

所有任务完成后：

• 验证全部测试通过
• 呈现选项：合并 / 创建 PR / 保留分支 / 丢弃
• 清理 worktree

四、14 个核心技能一览

反合理化设计：using-superpowers 技能里专门列出了 AI 常见的"逃避借口"及反驳。例如 AI 说"我已经手动测试过了" → 错误，临时测试不等于系统化测试。

五、技术架构亮点

三套测试基础设施：

• 技能触发测试：验证技能能否从"朴素"提示触发
• Claude Code 集成测试：使用 claude -p 无头测试
• 子代理工作流端到端测试：包含完整的 Go 和 Svelte 测试项目

共享核心模块 lib/skills-core.js：Codex 和 OpenCode 通过它实现跨平台复用。

六、平台安装指南

6.1 Claude Code（最简单）

第一步：安装插件

打开 Claude Code，输入：

/plugin marketplace add obra/superpowers-marketplace

第二步：验证安装

输入 /help，你应该能看到：

• /superpowers:brainstorm - 头脑风暴
• /superpowers:write-plan - 写计划
• /superpowers:execute-plan - 执行计划

6.2 Codex（两种方式）

方式一：快速安装（推荐）

直接告诉 Codex：

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

Codex 会自动完成所有安装步骤。

方式二：手动安装

前置要求：OpenAI Codex CLI 已安装、Node.js v14+、Git 已安装、Shell 访问权限。

# 第一步：克隆 Superpowers 仓库
mkdir -p ~/.codex/superpowers
cd ~/.codex/superpowers
git clone https://github.com/obra/superpowers.git .

# 第二步：创建个人技能目录
mkdir -p ~/.codex/skills

# 第三步：配置 AGENTS.md
# 编辑 ~/.codex/AGENTS.md，添加以下内容：

## Superpowers System

<EXTREMELY_IMPORTANT>

You have superpowers. Superpowers teach you new skills and capabilities.

RIGHT NOW run: 
`~/.codex/superpowers/.codex/superpowers-codex bootstrap`
 
and follow the instructions it returns.

</EXTREMELY_IMPORTANT>

# 第四步：验证安装
~/.codex/superpowers/.codex/superpowers-codex bootstrap

如果看到技能列表和引导指令，说明安装成功。

常用命令：

# 查找可用技能
~/.codex/superpowers/.codex/superpowers-codex find-skills

# 加载特定技能
~/.codex/superpowers/.codex/superpowers-codex use-skill superpowers:brainstorming

# 加载完整引导
~/.codex/superpowers/.codex/superpowers-codex bootstrap

6.3 OpenCode（一键脚本）

#!/bin/bash
# Superpowers for OpenCode - 完整安装脚本

echo "=== 安装 Superpowers for OpenCode ==="

# 第一步：克隆 Superpowers 仓库
echo "[1/4] 克隆 Superpowers 仓库..."
mkdir -p ~/.config/opencode/superpowers
git clone https://github.com/obra/superpowers.git ~/.config/opencode/superpowers

# 第二步：注册插件
echo "[2/4] 注册插件..."
mkdir -p ~/.config/opencode/plugin
ln -sf ~/.config/opencode/superpowers/.opencode/plugin/superpowers.js \
       ~/.config/opencode/plugin/superpowers.js

# 第三步：创建个人技能目录
echo "[3/4] 创建个人技能目录..."
mkdir -p ~/.config/opencode/skills

# 第四步：验证安装
echo "[4/4] 验证安装..."
if [ -f ~/.config/opencode/plugin/superpowers.js ]; then
    echo "✅ 插件链接创建成功"
else
    echo "❌ 插件链接创建失败"
    exit 1
fi

if [ -d ~/.config/opencode/superpowers/skills ]; then
    echo "✅ 技能目录存在"
    echo "   可用技能数量: $(ls ~/.config/opencode/superpowers/skills | wc -l)"
else
    echo "❌ 技能目录不存在"
    exit 1
fi

echo ""
echo "=== 安装完成！==="
echo ""
echo "下一步操作："
echo "1. 重启 OpenCode"
echo "2. 在对话中输入: do you have superpowers?"
echo "3. 使用 find_skills 工具查看可用技能"
echo "4. 使用 use_skill 工具加载技能"
echo ""
echo "示例命令："
echo "  use find_skills tool"
echo "  use use_skill tool with skill_name: \"superpowers:brainstorming\""

七、版本演进亮点

• v4.0.0：核心创新是两阶段代码审查和调试技术整合（systematic-debugging）
• v3.0：迁移到 Anthropic 官方技能系统
• v2.0：实现技能仓库分离，支持社区贡献

八、实战案例：让 AI 真正写出可用的功能

回到开头的待办事项应用场景。装好 Superpowers 后，你不需要输入任何特殊命令。当 AI 看到你说"我想做一个待办事项应用"时，它会自动进入头脑风暴模式。

实际走完 5 阶段后，你拿到的是：

• 一份写入 docs/plans/ 的设计文档（每节都和你确认过）
• 一个干净的 feature/todo-app 分支 + 独立 worktree
• 一份按 2-5 分钟切分的实现计划
• 每个功能点都有"先失败再通过"的测试覆盖
• 一份两阶段审查通过的最终代码
• 测试报告 + 合并选项清单

对比没有 Superpowers 的常规 AI 编程：

九、结语

Superpowers 本质上在回答一个问题：如何让 AI 代理像有经验的工程师一样工作，而不是像"会写代码但不懂工程"的实习生？

答案是：把最佳实践编码成可执行的、不可逃避的工作流。用流程图定义决策点，用测试验证行为，用子代理实现关注点分离，用两阶段审查确保质量。

原视频：哔哩哔哩^[1] / YouTube^[2]

项目地址：github.com/obra/superpowers^[3]（16.1k ⭐）

对于想要提升 AI 编程效率与代码质量的开发者来说，Superpowers 是一个非常值得学习和使用的工具。

引用链接