Superpowers 使用指南

#Superpowers 使用指南

完整的软件开发工作流系统，为编码 AI 代理提供”超能力”

#项目概述

Superpowers 是一个为编码 AI 代理（如 Claude Code、OpenCode）设计的完整软件开发工作流系统，基于可组合的 “skills”（技能）构建。

#核心理念

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

#核心工作流程

阶段 技能 触发时机 说明
1. 头脑风暴 brainstorming 写代码前 通过提问细化需求，苏格拉底式设计
2. 工作区隔离 using-git-worktrees 设计批准后 创建独立分支，验证测试基准
3. 计划编写 writing-plans 设计批准后 将工作拆分为 2-5 分钟的小任务
4. 执行 subagent-driven-development 计划完成后 每个任务派发子代理执行
5. 测试驱动 test-driven-development 实现过程中 RED-GREEN-REFACTOR 循环
6. 代码审查 requesting-code-review 任务间 审查代码，严重问题阻塞进度
7. 完成分支 finishing-a-development-branch 任务完成后 验证测试，提供合并/PR 选项

#OpenCode 安装方法

#前置条件

  • OpenCode.ai 已安装
  • Git 已安装
  • Windows: 需要开启开发者模式或以管理员身份运行

#方法 1：让 OpenCode 自动安装

在 OpenCode 中输入：

1
Clone https://github.com/obra/superpowers to ~/.config/opencode/superpowers, then create directory ~/.config/opencode/plugins, then symlink ~/.config/opencode/superpowers/.opencode/plugins/superpowers.js to ~/.config/opencode/plugins/superpowers.js, then symlink ~/.config/opencode/superpowers/skills to ~/.config/opencode/skills/superpowers, then restart opencode.

#方法 2：Windows Git Bash 手动安装

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# 1. Clone 项目
git clone https://github.com/obra/superpowers.git ~/.config/opencode/superpowers

# 2. 创建目录
mkdir -p ~/.config/opencode/plugins ~/.config/opencode/skills

# 3. 移除旧链接（安全重装）
rm -f ~/.config/opencode/plugins/superpowers.js 2>/dev/null
rm -rf ~/.config/opencode/skills/superpowers 2>/dev/null

# 4. 创建插件符号链接（需要开发者模式或管理员权限）
cmd //c "mklink \"$(cygpath -w ~/.config/opencode/plugins/superpowers.js)\" \"$(cygpath -w ~/.config/opencode/superpowers/.opencode/plugins/superpowers.js)\""

# 5. 创建技能目录连接（不需要特殊权限）
cmd //c "mklink /J \"$(cygpath -w ~/.config/opencode/skills/superpowers)\" \"$(cygpath -w ~/.config/opencode/superpowers/skills)\""

# 6. 重启 OpenCode

#验证安装

Git Bash:

1
2
ls -l ~/.config/opencode/plugins/superpowers.js
ls -l ~/.config/opencode/skills/superpowers

命令提示符:

1
2
dir /AL "%USERPROFILE%\.config\opencode\plugins"
dir /AL "%USERPROFILE%\.config\opencode\skills"

应该显示 <SYMLINK> 或 <JUNCTION>。

#使用方法

#列出所有技能

1
use skill tool to list skills

#加载特定技能

1
use skill tool to load superpowers/brainstorming

#测试安装

1
2
3
4
5
6
7
8
# 检查插件加载
opencode run --print-logs "hello" 2>&1 | grep -i superpowers

# 检查技能可发现
opencode run "use skill tool to list all skills" 2>&1 | grep -i superpowers

# 检查引导注入
opencode run "what superpowers do you have?"

#技能库

#测试类

技能 说明
test-driven-development RED-GREEN-REFACTOR 循环，包含测试反模式参考

#调试类

技能 说明
systematic-debugging 4 阶段根因分析过程
verification-before-completion 确保问题真正修复

#协作类

技能 说明
brainstorming 苏格拉底式设计细化
writing-plans 详细实现计划编写
executing-plans 带检查点的批量执行
dispatching-parallel-agents 并发子代理工作流
subagent-driven-development 子代理驱动开发，两阶段审查
requesting-code-review 代码审查请求检查清单
receiving-code-review 响应反馈
using-git-worktrees 并行开发分支
finishing-a-development-branch 合并/PR 决策工作流

#元类

技能 说明
writing-skills 创建新技能，包含最佳实践
using-superpowers 技能系统介绍

#架构

#插件结构

位置: ~/.config/opencode/superpowers/.opencode/plugins/superpowers.js

组件:

  • experimental.chat.system.transform 钩子：注入引导上下文
  • 读取并注入 “using-superpowers” 技能内容

#技能位置

OpenCode 从以下位置发现技能：

  1. 项目技能 (.opencode/skills/) - 最高优先级
  2. 个人技能 (~/.config/opencode/skills/)
  3. Superpowers 技能 (~/.config/opencode/skills/superpowers/) - 通过符号链接

#工具映射

技能中引用的工具会自动映射到 OpenCode 等效工具：

Claude Code 工具 OpenCode 工具
TodoWrite update_plan
Task with subagents @mention 系统
Skill 工具 OpenCode 原生 skill 工具
Read, Write, Edit, Bash 原生工具

#更新

1
2
cd ~/.config/opencode/superpowers
git pull

重启 OpenCode 以加载更新。

#故障排除

#插件未加载

  1. 检查插件存在: ls ~/.config/opencode/superpowers/.opencode/plugins/superpowers.js
  2. 检查符号链接: ls -l ~/.config/opencode/plugins/
  3. 检查日志: opencode run "test" --print-logs --log-level DEBUG

#技能未找到

  1. 验证技能符号链接: ls -l ~/.config/opencode/skills/superpowers
  2. 使用 skill 工具列出可用技能
  3. 检查技能结构: 每个技能需要 SKILL.md 文件

#Windows: 模块未找到错误

  • 原因: Git Bash ln -sf 复制文件而非创建符号链接
  • 解决: 使用 mklink /J 目录连接（见 Windows 安装步骤）

#引导未出现

  1. 验证 using-superpowers 技能存在
  2. 检查 OpenCode 版本支持 experimental.chat.system.transform 钩子
  3. 插件更改后重启 OpenCode

#相关链接

#与 Oh My OpenCode 兼容性分析

#已知问题

Issue #1560 (oh-my-opencode)：

当使用 OpenCode 和 oh-my-opencode 插件时，即使使用 superpowers 导入 planning-with-files 技能，它仍然会忘记技能要求遵循的规则，无法正确更新文件。

状态: Open（未解决）

#冲突原因分析

方面 Superpowers Oh My OpenCode 潜在冲突
钩子机制 experimental.chat.system.transform 自定义插件系统 可能存在钩子优先级问题
System Prompt 注入 using-superpowers 引导内容 注入 Sisyphus 引导内容 内容可能相互覆盖或冲突
Skills 命名 brainstorming, writing-plans 等 自带 skills 系统 命名空间隔离，风险较低
Agent 系统 无原生 agent，依赖 subagent Sisyphus 作为主要编排器 工作流可能冲突

#兼容性结论

场景 兼容性 建议
同时安装 ⚠️ 部分兼容 可能存在 system prompt 冲突
使用 OMO Agents ⚠️ 受限 Sisyphus 可能忽略 superpowers 技能规则
使用原生 Plan/Build ✅ 推荐 与 superpowers 配合更好
仅使用 superpowers ✅ 完全兼容 不安装 OMO 时无冲突

#推荐方案

#方案 A：禁用 OMO 的 Sisyphus，使用原生 + Superpowers