Superpowers 教程 1：安装配置（Claude Code / Cursor / Codex / OpenCode）

教程概述

系列目录：Superpowers 教程系列索引

本教程是 Superpowers 系列的第一篇，将带你完成从零开始的安装配置过程。无论你使用哪个平台，都能找到对应的安装方法。

你将学到

✅ Superpowers 的核心工作原理
✅ 在 4 个主流平台上安装 Superpowers
✅ 验证安装是否成功
✅ 常见问题排查

Superpowers 是什么？

Superpowers 是一个** agentic skills 框架**，本质上是一套精心设计的提示词（Prompts）和工作流程规范，用于指导 AI 编程助手按照最佳实践进行开发。

核心特点

自动触发 - 技能会根据上下文自动激活，无需手动调用
强制规范 - 不是建议，而是必须遵循的工作流程
可组合 - 多个技能可以协同工作
平台无关 - 支持 Claude Code、Cursor、Codex、OpenCode

工作流程示意

flowchart TD
    A[用户提出需求] --> B{brainstorming 技能}
    B --> C[探索需求与设计]
    C --> D{writing-plans 技能}
    D --> E[创建实现计划]
    E --> F{subagent-driven-development}
    F --> G[执行任务 + 代码审查]
    G --> H{verification-before-completion}
    H --> I[验证完成]
    
    style B fill:#e1f5ff
    style D fill:#e1f5ff
    style F fill:#e1f5ff
    style H fill:#e1f5ff

安装前准备

系统要求

平台	要求
Claude Code	需要 Claude 订阅
Cursor	Cursor IDE v0.40+
Codex	OpenAI Codex 访问权限
OpenCode	OpenCode CLI

Git 配置

确保你的 Git 已正确配置：

git config --global user.name "Your Name"
git config --global user.email "[email protected]"

平台 1：Claude Code 安装

方法 A：通过 Plugin Marketplace（推荐）

步骤 1：注册 Marketplace

在 Claude Code 中运行：

/plugin marketplace add obra/superpowers-marketplace

步骤 2：安装插件

/plugin install superpowers@superpowers-marketplace

步骤 3：验证安装

启动新会话并询问：

帮我规划一个新功能

如果 AI 开始询问你的需求而不是直接写代码，说明安装成功！

方法 B：手动安装

如果 Marketplace 不可用：

# 克隆仓库
git clone https://github.com/obra/superpowers.git ~/.superpowers

# 在 Claude Code 中加载
/plugin load ~/.superpowers

更新插件

/plugin update superpowers

平台 2：Cursor 安装

安装步骤

步骤 1：打开 Cursor

启动 Cursor IDE，打开 Agent 聊天窗口。

步骤 2：安装插件

在 Agent 聊天中输入：

/plugin-add superpowers

步骤 3：确认安装

Cursor 会自动从 marketplace 下载并安装。安装完成后会显示确认消息。

配置建议

在 Cursor 的设置中，确保以下选项已启用：

✅ Agent Mode
✅ Auto-accept suggestions（可选，建议初期关闭）
✅ Git integration

验证安装

在 Cursor 中打开一个项目，然后在 Agent 聊天中输入：

我想添加一个用户登录功能

如果 Agent 开始询问：

用户认证方式（邮箱/手机/OAuth）
会话管理策略
安全要求

说明 brainstorming 技能已正确触发！

平台 3：Codex 安装

安装命令

告诉 Codex：

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

详细配置

详见官方文档：docs/README.codex.md

自定义配置

创建 ~/.codex/config.yaml：

superpowers:
  enabled: true
  auto_trigger: true
  skills:
    - brainstorming
    - writing-plans
    - test-driven-development
    - systematic-debugging

平台 4：OpenCode 安装

安装命令

告诉 OpenCode：

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

详细配置

详见官方文档：docs/README.opencode.md

环境变量配置

# ~/.bashrc 或 ~/.zshrc
export SUPERPOWERS_ENABLED=true
export SUPERPOWERS_AUTO_TRIGGER=true

验证安装成功

测试场景 1：Brainstorming 触发

输入：

我想给我的博客添加评论功能

期望行为：

❌ 直接开始写评论组件代码 → 失败
✅ 开始询问需求（评论系统选择、审核策略、存储方案）→ 成功

测试场景 2：TDD 触发

输入：

实现一个计算斐波那契数列的函数

期望行为：

❌ 直接实现函数 → 失败
✅ 先写测试用例 → 成功

测试场景 3：Git Worktree 触发

输入：

开始实现刚才设计的评论功能

期望行为：

❌ 直接在当前分支修改 → 失败
✅ 创建新的 worktree 和分支 → 成功

常见问题排查

问题 1：技能不触发

症状：AI 直接开始写代码，没有触发任何技能

排查步骤：

检查插件是否正确加载：
```
/plugin list
```
确认 using-superpowers 技能是否激活

尝试显式触发：

使用 brainstorming 技能来规划这个功能

重启会话

问题 2：安装失败

症状：安装命令报错

解决方案：

# 清除缓存
rm -rf ~/.cache/superpowers

# 重新安装
# Claude Code
/plugin install superpowers@superpowers-marketplace --force

# Cursor
# 在设置中删除插件后重新添加

问题 3：技能冲突

症状：多个技能同时触发，行为混乱

解决方案：

编辑配置文件，禁用不需要的技能：

# ~/.superpowers/config.yaml
skills:
  enabled:
    - brainstorming
    - writing-plans
    - test-driven-development
  disabled:
    - subagent-driven-development  # 暂时禁用

问题 4：Git Worktree 失败

症状：创建 worktree 时报错

解决方案：

# 检查 Git 版本（需要 2.5+）
git --version

# 清理残留的 worktree
git worktree prune

# 手动测试 worktree
git worktree add ../test-worktree -b test-branch

最佳实践建议

1. 渐进式采用

不要一开始就启用所有技能。建议顺序：

第 1 周：brainstorming + writing-plans
第 2 周：+ test-driven-development
第 3 周：+ systematic-debugging
第 4 周：+ 代码审查技能

2. 配置个性化

根据你的项目类型调整技能参数：

# 快速原型项目
superpowers:
  mode: rapid-prototyping
  skip_code_review: true
  
# 生产环境项目
superpowers:
  mode: production
  require_tests: true
  require_code_review: true

3. 团队协作

如果是团队使用，建议：

统一配置文件
定期技能复盘
建立内部最佳实践文档

性能优化

减少子代理数量

如果资源有限，可以限制并发子代理：

subagent:
  max_concurrent: 2
  timeout_minutes: 30

缓存设计文档

brainstorming 生成的设计文档会被缓存，避免重复讨论：

brainstorming:
  cache_enabled: true
  cache_ttl_hours: 24

下一步

安装完成后，继续学习：

📖 教程 2：brainstorming 技能详解
📖 教程 3：writing-plans 技能详解

参考资源

官方仓库：github.com/obra/superpowers
插件市场：github.com/obra/superpowers-marketplace
作者博客：Superpowers for Claude Code

📚 完整教程系列导航

你正在阅读本系列的 教程 1，以下是完整目录：

遇到问题？ 在评论区留言或前往 GitHub Issues 提问！

系列导航：

教程概述

你将学到

Superpowers 是什么？

核心特点

工作流程示意

安装前准备

系统要求

Git 配置

平台 1：Claude Code 安装

方法 A：通过 Plugin Marketplace（推荐）

方法 B：手动安装

更新插件

平台 2：Cursor 安装

安装步骤

配置建议

验证安装

平台 3：Codex 安装

安装命令

详细配置

自定义配置

平台 4：OpenCode 安装

安装命令

详细配置

环境变量配置

验证安装成功

测试场景 1：Brainstorming 触发

测试场景 2：TDD 触发

测试场景 3：Git Worktree 触发

常见问题排查

问题 1：技能不触发

问题 2：安装失败

问题 3：技能冲突

问题 4：Git Worktree 失败

最佳实践建议

1. 渐进式采用

2. 配置个性化

3. 团队协作

性能优化

减少子代理数量

缓存设计文档

下一步

参考资源

📚 完整教程系列导航

🍪 Cookie 使用通知

Cookie 偏好设置

必要 Cookie

分析 Cookie

广告 Cookie