Superpowers — 项目学习指南
Superpowers 是一套为 AI 编码助手（如 Claude Code、Cursor、Codex 等）设计的可组合"技能"（Skills）库，通过预定义的工作流和最佳实践，让 AI 助手在软件开发全流程中表现得更加系统化和可靠。
Superpowers 项目学习指南
1. 项目简介
一句话说明：Superpowers 是一套为 AI 编码助手（如 Claude Code、Cursor、Codex 等）设计的可组合”技能”（Skills）库，通过预定义的工作流和最佳实践，让 AI 助手在软件开发全流程中表现得更加系统化和可靠。
核心功能
- 头脑风暴（Brainstorming）：在编码前通过苏格拉底式对话探索需求、设计方案
- 计划编写（Writing Plans）：将设计拆分为 2-5 分钟粒度的可执行任务
- 子代理驱动开发（Subagent-Driven Development）：为每个任务分派独立子代理，配合两阶段审查（规格合规 + 代码质量）
- 测试驱动开发（TDD）：强制执行 RED-GREEN-REFACTOR 循环
- 系统化调试（Systematic Debugging）：四阶段根因分析流程
- 代码审查（Code Review）：请求和接收代码审查的标准化流程
- Git Worktree 管理：创建隔离的开发分支环境
- 完成验证（Verification Before Completion）：在声称完成前强制运行验证命令
技术栈总览
| 类别 | 技术 | 说明 |
|---|---|---|
| 主要语言 | Markdown | 技能定义、文档、提示模板 |
| 脚本语言 | Shell (Bash) | 会话启动钩子、测试脚本 |
| 编程语言 | JavaScript (ES Module) | OpenCode 插件实现 |
| 配置格式 | JSON | 插件配置、hooks 配置 |
| 版本 | v5.0.4 (package.json) / v5.0.5 (plugin.json) | |
| 运行时 | Node.js | OpenCode 插件、brainstorm 服务器 |
| 支持平台 | Claude Code, Cursor, Codex, OpenCode, Gemini CLI | 多平台 AI 编码助手 |
注意：这不是一个传统的 Web 应用或后端服务，而是一个 AI 编码助手的插件/技能库。它没有数据库、API 端点或用户界面，其”运行”方式是被 AI 助手加载并在对话中执行。
2. 目录结构说明
superpowers/
├── .claude-plugin/ # Claude Code 插件配置
│ ├── plugin.json # 插件元数据（名称、版本、描述）
│ └── marketplace.json # 开发市场配置
├── .cursor-plugin/ # Cursor IDE 插件配置
│ └── plugin.json # Cursor 专用配置（引用 hooks-cursor.json）
├── .codex/ # OpenAI Codex 支持
│ └── INSTALL.md # Codex 安装指南
├── .opencode/ # OpenCode.ai 支持
│ ├── INSTALL.md # OpenCode 安装指南
│ └── plugins/
│ └── superpowers.js # OpenCode 插件实现（ES Module）
├── agents/ # AI 代理定义
│ └── code-reviewer.md # 代码审查代理的角色定义和行为规范
├── commands/ # 用户命令（已废弃）
│ ├── brainstorm.md # → 已废弃，指向 brainstorming skill
│ ├── execute-plan.md # → 已废弃，指向 executing-plans skill
│ └── write-plan.md # → 已废弃，指向 writing-plans skill
├── hooks/ # 会话启动钩子
│ ├── hooks.json # Claude Code 的 hook 配置
│ ├── hooks-cursor.json # Cursor 的 hook 配置
│ ├── session-start # 会话启动脚本（注入引导上下文）
│ └── run-hook.cmd # Windows 跨平台 polyglot 包装器
├── skills/ # ★ 核心：技能定义目录
│ ├── using-superpowers/ # 引导技能（会话启动时自动加载）
│ │ ├── SKILL.md # 技能发现和使用的元规则
│ │ └── references/ # 平台特定工具映射
│ ├── brainstorming/ # 头脑风暴技能
│ │ ├── SKILL.md # 需求探索和设计流程
│ │ ├── visual-companion.md # 浏览器可视化伴侣指南
│ │ ├── spec-document-reviewer-prompt.md # 规格审查子代理提示
│ │ └── scripts/ # 可视化伴侣服务器脚本
│ │ ├── start-server.sh # 启动 brainstorm 可视化服务器
│ │ ├── stop-server.sh # 停止服务器
│ │ ├── frame-template.html # HTML 页面框架模板
│ │ └── helper.js # 客户端交互脚本
│ ├── writing-plans/ # 计划编写技能
│ │ ├── SKILL.md # 任务拆分和计划编写流程
│ │ └── plan-document-reviewer-prompt.md # 计划审查子代理提示
│ ├── executing-plans/ # 计划执行技能
│ │ └── SKILL.md # 逐步执行计划的流程
│ ├── subagent-driven-development/ # 子代理驱动开发技能
│ │ ├── SKILL.md # 子代理调度和审查流程
│ │ ├── implementer-prompt.md # 实现者子代理提示模板
│ │ ├── spec-reviewer-prompt.md # 规格审查子代理提示模板
│ │ └── code-quality-reviewer-prompt.md # 代码质量审查提示模板
│ ├── test-driven-development/ # TDD 技能
│ │ ├── SKILL.md # RED-GREEN-REFACTOR 流程
│ │ └── testing-anti-patterns.md # 测试反模式参考
│ ├── systematic-debugging/ # 系统化调试技能
│ │ ├── SKILL.md # 四阶段调试流程
│ │ ├── root-cause-tracing.md # 根因追踪技术
│ │ ├── defense-in-depth.md # 深度防御验证
│ │ ├── condition-based-waiting.md # 条件等待技术
│ │ └── ... # 测试场景文件
│ ├── dispatching-parallel-agents/ # 并行代理调度技能
│ │ └── SKILL.md
│ ├── using-git-worktrees/ # Git Worktree 管理技能
│ │ └── SKILL.md
│ ├── finishing-a-development-branch/ # 开发分支完成技能
│ │ └── SKILL.md
│ ├── requesting-code-review/ # 请求代码审查技能
│ │ ├── SKILL.md
│ │ └── code-reviewer.md # 审查者提示模板
│ ├── receiving-code-review/ # 接收代码审查技能
│ │ └── SKILL.md
│ ├── verification-before-completion/ # 完成前验证技能
│ │ └── SKILL.md
│ └── writing-skills/ # 编写新技能的元技能
│ ├── SKILL.md # 技能编写最佳实践
│ ├── anthropic-best-practices.md # Anthropic 官方技能编写指南
│ ├── persuasion-principles.md # 说服原则
│ ├── testing-skills-with-subagents.md # 用子代理测试技能
│ └── ...
├── tests/ # 测试套件
│ ├── brainstorm-server/ # Brainstorm 服务器测试
│ ├── claude-code/ # Claude Code 集成测试
│ ├── explicit-skill-requests/ # 显式技能请求测试
│ ├── opencode/ # OpenCode 插件测试
│ ├── skill-triggering/ # 技能触发测试
│ └── subagent-driven-dev/ # 子代理开发测试
├── docs/ # 文档
│ ├── testing.md # 测试指南
│ ├── README.codex.md # Codex 使用文档
│ ├── README.opencode.md # OpenCode 使用文档
│ └── plans/ # 设计和实现计划文档
├── gemini-extension.json # Gemini CLI 扩展配置
├── GEMINI.md # Gemini 入口文件（引用 using-superpowers）
├── package.json # Node.js 包配置（版本 5.0.4）
├── README.md # 项目主文档
├── CHANGELOG.md # 变更日志
└── RELEASE-NOTES.md # 发布说明3. 架构设计
整体架构模式
Superpowers 采用 插件式技能注入架构，核心设计理念是：
将软件开发最佳实践编码为可被 AI 助手自动发现和执行的”技能”（Skills），通过会话启动时的上下文注入，让 AI 助手在每次交互中都遵循这些最佳实践。
这不是传统的 MVC 或微服务架构，而是一种 声明式行为规范系统：
- 技能（Skill） = 一组 Markdown 编写的行为规则 + 工作流程
- 钩子（Hook） = 在 AI 会话启动时自动注入引导上下文的机制
- 子代理提示（Subagent Prompt） = 分派给子 AI 代理的任务模板
核心模块划分与职责
┌─────────────────────────────────────────────────────┐
│ 平台适配层 │
│ .claude-plugin/ .cursor-plugin/ .opencode/ ... │
│ （为不同 AI 平台提供插件配置和安装机制） │
└──────────────────────┬──────────────────────────────┘
│
┌──────────────────────▼──────────────────────────────┐
│ 启动注入层 │
│ hooks/session-start │
│ （会话启动时读取 using-superpowers 并注入上下文） │
└──────────────────────┬──────────────────────────────┘
│
┌──────────────────────▼──────────────────────────────┐
│ 技能发现层 │
│ skills/using-superpowers/SKILL.md │
│ （定义技能发现和使用的元规则：何时加载哪个技能） │
└──────────────────────┬──────────────────────────────┘
│
┌──────────────────────▼──────────────────────────────┐
│ 技能执行层 │
│ brainstorming → writing-plans → subagent-driven │
│ test-driven-development systematic-debugging │
│ requesting-code-review verification-before-... │
│ （14 个具体技能，各自定义工作流和行为规范） │
└──────────────────────┬──────────────────────────────┘
│
┌──────────────────────▼──────────────────────────────┐
│ 子代理提示层 │
│ implementer-prompt spec-reviewer-prompt │
│ code-quality-reviewer-prompt code-reviewer │
│ （为子代理提供角色定义和任务模板） │
└─────────────────────────────────────────────────────┘模块间调用关系与数据流向
主工作流数据流：
用户发起对话
│
▼
hooks/session-start 自动执行
│ 读取 skills/using-superpowers/SKILL.md
│ 注入为 AI 助手的系统上下文
▼
AI 助手收到用户消息
│ 根据 using-superpowers 规则检查适用技能
▼
brainstorming（如果是创造性工作）
│ 探索需求 → 展示设计 → 编写设计文档
│ 调用 spec-document-reviewer 子代理审查
▼
writing-plans
│ 拆分为 bite-sized 任务 → 编写实现计划
│ 调用 plan-document-reviewer 子代理审查
▼
using-git-worktrees
│ 创建隔离的 worktree 环境
▼
subagent-driven-development（推荐）或 executing-plans
│ 对每个任务：
│ 1. 分派 implementer 子代理实现
│ 2. 分派 spec-reviewer 子代理审查规格合规性
│ 3. 分派 code-quality-reviewer 子代理审查代码质量
│ 4. 如有问题，修复后重新审查
▼
finishing-a-development-branch
│ 验证测试 → 呈现选项（合并/PR/保留/丢弃）→ 清理
▼
完成4. 核心流程解析
4.1 启动流程：从会话开始到技能注入
入口文件：hooks/session-start
当用户在支持的 AI 平台（如 Claude Code）中启动新会话时：
- 平台触发 hook：平台根据
hooks/hooks.json配置，在SessionStart事件时执行run-hook.cmd session-start
// hooks/hooks.json
{
"hooks": {
"SessionStart": [{
"matcher": "startup|clear|compact",
"hooks": [{
"type": "command",
"command": "run-hook.cmd session-start"
}]
}]
}
}- session-start 脚本执行：读取
skills/using-superpowers/SKILL.md的内容，转义后封装为 JSON 输出
# hooks/session-start（关键逻辑）
# 定位插件根目录
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
PLUGIN_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
# 检查旧版安装残留并生成警告
legacy_skills_dir="${HOME}/.config/superpowers/skills"
if [ -d "$legacy_skills_dir" ]; then
warning_message="⚠️ WARNING: Move custom skills to ~/.claude/skills..."
fi
# 读取引导技能内容
using_superpowers_content=$(cat "${PLUGIN_ROOT}/skills/using-superpowers/SKILL.md")
# JSON 转义（处理反斜杠、引号、换行等特殊字符）
escape_for_json() {
local s="$1"
s="${s//\\/\\\\}" # 转义反斜杠
s="${s//\"/\\\"}" # 转义引号
s="${s//- AI 助手加载上下文：
using-superpowers的内容成为 AI 助手的行为规范，指导它在后续每次交互中检查并使用适用的技能。
4.2 头脑风暴流程（Brainstorming）
触发条件：用户请求创建功能、构建组件、添加功能或修改行为
调用链路：
用户: "帮我实现一个用户认证系统"
│
▼
AI 检查 using-superpowers 规则
│ 判断：这是创造性工作 → 必须使用 brainstorming
▼
加载 skills/brainstorming/SKILL.md
│
├─ 步骤 1: 探索项目上下文（读取文件、文档、最近提交）
├─ 步骤 2: 一次问一个澄清问题（理解目的/约束/成功标准）
├─ 步骤 3: 提出 2-3 种方法及权衡
├─ 步骤 4: 分章节展示设计，每章后获取用户批准
├─ 步骤 5: 编写设计文档到 docs/superpowers/specs/
├─ 步骤 6: 分派 spec-document-reviewer 子代理审查
│ └─ 使用 skills/brainstorming/spec-document-reviewer-prompt.md
└─ 步骤 7: 用户审查 → 交接给 writing-plans关键约束：在展示设计并获得批准前，禁止任何实现操作。
4.3 子代理驱动开发流程（Subagent-Driven Development）
触发条件：有已批准的实现计划，需要执行
调用链路：
已批准的实现计划
│
▼
加载 skills/subagent-driven-development/SKILL.md
│
├─ 读取计划，提取所有任务，创建 TodoWrite
│
├─ 对每个任务循环：
│ │
│ ├─ 1. 分派 implementer 子代理
│ │ └─ 使用 implementer-prompt.md 模板
│ │ └─ 子代理返回状态：DONE / DONE_WITH_CONCERNS / NEEDS_CONTEXT / BLOCKED
│ │
│ ├─ 2. 分派 spec-reviewer 子代理（规格合规审查）
│ │ └─ 使用 spec-reviewer-prompt.md 模板
│ │ └─ 独立验证实现是否匹配规格（不信任实现者报告）
│ │
│ ├─ 3. 如有问题 → implementer 修复 → 重新审查
│ │
│ ├─ 4. 分派 code-quality-reviewer 子代理（代码质量审查）
│ │ └─ 使用 code-quality-reviewer-prompt.md 模板
│ │ └─ 仅在规格审查通过后执行
│ │
│ └─ 5. 标记任务完成
│
├─ 所有任务完成后，分派最终代码审查子代理
│
└─ 调用 finishing-a-development-branch 完成开发关键设计：每个任务使用 全新的子代理（Fresh subagent），避免上下文污染。审查分两阶段：先验证”做对了没有”（spec compliance），再验证”做好了没有”（code quality）。
4.4 测试驱动开发流程（TDD）
触发条件：实现任何功能或 bugfix 时
调用链路：
需要实现一个功能
│
▼
加载 skills/test-driven-development/SKILL.md
│
├─ RED: 编写一个最小的失败测试
│ └─ 测试名称清晰，测试真实行为
│
├─ Verify RED: 运行测试，确认失败（不是错误）
│ └─ 铁律：NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST
│
├─ GREEN: 编写最简单的代码使测试通过
│ └─ 不添加额外功能，不重构
│
├─ Verify GREEN: 运行测试，确认通过
│ └─ 确认其他测试仍然通过
│
├─ REFACTOR: 清理代码
│ └─ 移除重复、改进命名、提取 helpers
│ └─ 保持测试绿色
│
└─ 重复下一个测试4.5 系统化调试流程（Systematic Debugging）
触发条件：遇到 bug、测试失败或意外行为
调用链路：
发现 bug
│
▼
加载 skills/systematic-debugging/SKILL.md
│
├─ Phase 1: 根本原因调查
│ ├─ 仔细阅读错误消息
│ ├─ 一致重现问题
│ ├─ 检查最近更改
│ └─ 追踪数据流（向后追溯）
│ └─ 参考 root-cause-tracing.md
│
├─ Phase 2: 模式分析
│ ├─ 找到工作示例
│ ├─ 与参考对比
│ └─ 识别差异
│
├─ Phase 3: 假设和测试
│ ├─ 形成单一假设
│ ├─ 最小化测试
│ └─ 验证后再继续
│
└─ Phase 4: 实现修复
├─ 创建失败测试用例
├─ 实现单一修复
├─ 验证修复
└─ 如果 3+ 修复失败：质疑架构铁律：NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST（不经过根因调查就不修复）
5. 关键设计与实现
5.1 设计模式
策略模式（Strategy Pattern）
技能系统本质上是策略模式的应用：每个 Skill 定义了一种处理特定场景的策略，using-superpowers 充当策略选择器，根据用户意图选择并加载对应的策略。
using-superpowers（策略选择器）
├─ 创造性工作 → brainstorming 策略
├─ 有计划要执行 → subagent-driven-development 策略
├─ 遇到 bug → systematic-debugging 策略
└─ 声称完成 → verification-before-completion 策略责任链模式（Chain of Responsibility）
主工作流形成一条责任链：brainstorming → writing-plans → subagent-driven-development → finishing-a-development-branch，每个环节完成后将控制权传递给下一个。
模板方法模式（Template Method）
子代理提示文件（如 implementer-prompt.md、spec-reviewer-prompt.md）定义了标准化的任务模板，具体任务内容通过占位符注入。
观察者模式（Observer Pattern）
Hook 系统是观察者模式的实现：平台事件（如 SessionStart）触发注册的 hook 脚本执行。
5.2 技能定义规范（数据模型）
每个技能遵循统一的结构规范：
---
name: skill-name # 小写 kebab-case，仅字母、数字、连字符
description: "Use when..." # 以 "Use when" 开头的触发条件描述
---
# 概述
简要说明技能的目的和核心原则
# 工作流程
具体的步骤和规则
# 铁律（Iron Rules）
不可违反的核心约束
# 集成
与其他技能的关系（REQUIRED / Complementary）技能类型：
- Technique：具体方法和步骤（如 TDD、系统化调试）
- Pattern：思考问题的方式（如头脑风暴）
- Reference：API 文档、语法指南（如测试反模式）
5.3 子代理通信协议
子代理通过标准化的状态码进行通信：
| 状态码 | 含义 | 后续动作 |
|---|---|---|
DONE | 任务完成 | 进入审查阶段 |
DONE_WITH_CONCERNS | 完成但有顾虑 | 审查并评估顾虑 |
NEEDS_CONTEXT | 需要更多上下文 | 提供上下文后重试 |
BLOCKED | 被阻塞无法继续 | 升级给人类处理 |
5.4 两阶段审查机制
这是 Superpowers 最核心的质量保证设计：
实现完成
│
▼
第一阶段：规格合规审查（Spec Review）
│ 问题："做对了吗？"
│ 审查者：独立验证，不信任实现者报告
│ 通过 → 进入第二阶段
│ 不通过 → 返回修复
▼
第二阶段：代码质量审查（Code Quality Review）
│ 问题："做好了吗？"
│ 审查者：检查代码质量、可维护性、测试覆盖
│ 通过 → 标记完成
│ 不通过 → 返回修复5.5 跨平台适配策略
Superpowers 通过不同的入口文件适配多个 AI 平台：
| 平台 | 入口机制 | 配置文件 |
|---|---|---|
| Claude Code | Plugin marketplace + hooks | .claude-plugin/plugin.json + hooks/hooks.json |
| Cursor | Plugin marketplace + hooks | .cursor-plugin/plugin.json + hooks/hooks-cursor.json |
| Codex | 符号链接到 ~/.agents/skills/ | .codex/INSTALL.md |
| OpenCode | ES Module 插件 | .opencode/plugins/superpowers.js |
| Gemini CLI | Extension + context file | gemini-extension.json + GEMINI.md |
所有平台最终都会加载同一套 skills/ 目录下的技能定义，实现”一次编写，多平台运行”。
5.6 CSO（Claude Search Optimization）
类似于 SEO（搜索引擎优化），Superpowers 定义了 CSO 概念——优化技能的 description 字段，使 AI 助手能更准确地发现和匹配技能：
- Rich Description：仅描述触发条件，不总结工作流
- Keyword Coverage：包含 AI 会搜索的词（错误消息、症状、同义词）
- Descriptive Naming：主动语态，动词优先
- Token Efficiency：控制技能文档长度（频繁加载的 <200 词）
6. 环境搭建与运行
环境依赖
- 必需：一个支持的 AI 编码助手平台（Claude Code / Cursor / Codex / OpenCode / Gemini CLI）
- 可选：Git（用于 worktree 功能）、GitHub CLI
gh（用于创建 PR）、Node.js（用于 OpenCode 插件和 brainstorm 服务器）
安装步骤
Claude Code（推荐）
# 方式一：官方市场
/plugin install superpowers@claude-plugins-official
# 方式二：社区市场
/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplaceCursor
在 Cursor Agent 聊天中：
/add-plugin superpowers或在插件市场搜索 “superpowers”。
Codex
# 克隆仓库
git clone https://github.com/obra/superpowers.git ~/.codex/superpowers
# 创建符号链接
mkdir -p ~/.agents/skills
ln -s ~/.codex/superpowers/skills ~/.agents/skills/superpowersOpenCode
在 opencode.json 中添加：
{
"plugin": [
"superpowers@git+https://github.com/obra/superpowers.git"
]
}Gemini CLI
gemini extensions install https://github.com/obra/superpowers验证安装
启动新会话，尝试触发技能：
"帮我规划一个新功能" → 应触发 brainstorming 技能
"帮我调试这个问题" → 应触发 systematic-debugging 技能更新
# Claude Code
/plugin update superpowers
# Gemini CLI
gemini extensions update superpowers关键环境变量
| 变量 | 说明 |
|---|---|
SUPERPOWERS_SKILLS_ROOT | 技能目录路径（历史版本使用，当前版本已内置） |
CLAUDE_PLUGIN_ROOT | Claude Code 插件根目录（由平台自动设置） |
CURSOR_PLUGIN_ROOT | Cursor 插件根目录（由平台自动设置） |
BRAINSTORM_OWNER_PID | Brainstorm 服务器的父进程 PID（Windows 上跳过） |
7. 推荐学习路线
阶段一：入门（理解核心概念）
目标：理解 Superpowers 是什么、如何工作
阅读顺序：
README.md— 了解项目定位、核心工作流、安装方式skills/using-superpowers/SKILL.md— 理解技能发现和使用的元规则，这是整个系统的”大脑”hooks/session-start— 理解技能是如何被注入到 AI 助手上下文中的.claude-plugin/plugin.json— 理解插件的元数据结构
需要理解的概念：
- Skill（技能）：一组 Markdown 编写的行为规则和工作流程
- Hook（钩子）：在特定事件（如会话启动）时自动执行的脚本
- Subagent（子代理）：被主 AI 助手分派去执行特定任务的独立 AI 实例
- Frontmatter：Markdown 文件顶部
---包裹的 YAML 元数据
阶段二：进阶（深入核心技能）
目标：理解主工作流的每个环节
阅读顺序：
skills/brainstorming/SKILL.md— 理解需求探索和设计流程skills/writing-plans/SKILL.md— 理解任务拆分策略skills/subagent-driven-development/SKILL.md— 理解子代理调度和两阶段审查skills/subagent-driven-development/implementer-prompt.md— 理解子代理提示模板设计skills/test-driven-development/SKILL.md— 理解 TDD 的强制执行机制skills/systematic-debugging/SKILL.md— 理解系统化调试方法论skills/verification-before-completion/SKILL.md— 理解完成验证的”门函数”设计
需要掌握的机制：
- 技能之间的 REQUIRED 和 Complementary 关系
- 子代理的 状态码通信协议（DONE / BLOCKED / NEEDS_CONTEXT）
- 两阶段审查（spec compliance → code quality）
- 铁律（Iron Rules） 的设计意图
阶段三：实践（动手验证理解）
建议尝试的任务：
- 使用 Superpowers 完成一个小功能：安装插件后，让 AI 助手帮你实现一个简单功能（如一个 CLI 工具），观察完整的 brainstorming → planning → implementation 流程
- 编写一个自定义技能：阅读
skills/writing-skills/SKILL.md，按照 RED-GREEN-REFACTOR for Skills 方法论，创建一个解决你特定问题的技能 - 分析子代理提示模板：对比
implementer-prompt.md、spec-reviewer-prompt.md、code-quality-reviewer-prompt.md，理解不同角色的提示设计差异 - 为新平台添加支持：参考现有的平台适配文件（如
.opencode/plugins/superpowers.js），尝试为一个新的 AI 平台编写适配层
8. 常见问题与注意事项
容易踩的坑
-
commands/目录已废弃：不要使用/brainstorm、/write-plan、/execute-plan命令，它们已被对应的 skill 替代。正确方式是让 AI 助手自动触发技能，或明确要求使用某个技能。 -
版本号不一致：
package.json中版本为5.0.4，.claude-plugin/plugin.json中为5.0.5，gemini-extension.json中为5.0.0。三个配置文件的版本号不同步，以.claude-plugin/plugin.json为最新版本。Gemini 扩展版本滞后是因为 Gemini CLI 支持较新且更新频率较低。 -
Windows 上的 PID 问题：Brainstorm 服务器在 Windows/MSYS2 上会跳过
BRAINSTORM_OWNER_PID生命周期监控，因为 PID 命名空间对 Node.js 不可见。30 分钟空闲超时仍然有效。 -
Node.js ESM 兼容性：
package.json中"type": "module"导致require()在 Node.js 22+ 上失败。brainstorm 服务器已重命名为.cjs后缀解决此问题。 -
旧版安装残留：如果之前使用过 v2.x 版本，
~/.config/superpowers/skills目录可能残留。session-start脚本会检测并警告。
代码中的特殊约定
-
技能命名规范：必须使用小写 kebab-case（如
test-driven-development），仅允许字母、数字、连字符。 -
技能引用命名空间：内部引用使用
superpowers:前缀（如superpowers:test-driven-development），这是 Claude Code 插件系统的命名空间机制。 -
SKILL.md 是唯一入口：每个技能目录下的
SKILL.md是 AI 助手加载的入口文件，其他.md文件是被SKILL.md引用的辅助文件。 -
Description 字段的 CSO 规范：
- 必须以
"Use when..."开头 - 仅描述触发条件，不总结工作流
- 使用第三人称
- 最大 1024 字符
- 必须以
-
铁律（Iron Rules）不可违反：每个技能中标记为 “Iron Rule” 的规则是绝对约束，AI 助手不应在任何情况下绕过。例如：
- TDD：
NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST - 调试：
NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST - 验证：
NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE
- TDD：
技术债务与注意事项
-
commands/目录待移除：三个命令文件已标记为废弃，将在下一个主版本中移除。 -
Gemini 扩展版本滞后：
gemini-extension.json中版本号为5.0.0，与.claude-plugin/plugin.json的5.0.5不同步。Gemini CLI 支持是较晚添加的功能，更新频率低于主平台。 -
Brainstorm 可视化伴侣：
skills/brainstorming/visual-companion.md引用的脚本文件位于skills/brainstorming/scripts/目录下（包括start-server.sh、stop-server.sh、frame-template.html、helper.js），用于启动基于浏览器的可视化头脑风暴伴侣。服务器在 30 分钟无活动后自动退出。 -
测试覆盖不均匀：
tests/目录下的测试主要是 Shell 脚本形式的集成测试，依赖 Claude Code 的 headless 模式运行，无法在普通 CI 环境中自动执行。 -
多平台配置同步：五个平台的配置文件需要手动保持同步（版本号、描述等），当前已存在版本号不一致的情况（
plugin.json为 5.0.5，gemini-extension.json为 5.0.0）。
# 根据平台输出不同的 JSON 结构
if [ -n "${CURSOR_PLUGIN_ROOT:-}" ]; then
# Cursor 使用 additional_context 字段
printf '{"additional_context": "%s"}\n' "$session_context"
elif [ -n "${CLAUDE_PLUGIN_ROOT:-}" ]; then
# Claude Code 使用 hookSpecificOutput.additionalContext 字段
printf '{"hookSpecificOutput": {"hookEventName": "SessionStart", "additionalContext": "%s"}}\n' "$session_context"
else
# 其他平台使用 additional_context 作为回退
printf '{"additional_context": "%s"}\n' "$session_context"
fi- AI 助手加载上下文：
using-superpowers的内容成为 AI 助手的行为规范，指导它在后续每次交互中检查并使用适用的技能。
4.2 头脑风暴流程（Brainstorming）
触发条件：用户请求创建功能、构建组件、添加功能或修改行为
调用链路：
用户: "帮我实现一个用户认证系统"
│
▼
AI 检查 using-superpowers 规则
│ 判断：这是创造性工作 → 必须使用 brainstorming
▼
加载 skills/brainstorming/SKILL.md
│
├─ 步骤 1: 探索项目上下文（读取文件、文档、最近提交）
├─ 步骤 2: 一次问一个澄清问题（理解目的/约束/成功标准）
├─ 步骤 3: 提出 2-3 种方法及权衡
├─ 步骤 4: 分章节展示设计，每章后获取用户批准
├─ 步骤 5: 编写设计文档到 docs/superpowers/specs/
├─ 步骤 6: 分派 spec-document-reviewer 子代理审查
│ └─ 使用 skills/brainstorming/spec-document-reviewer-prompt.md
└─ 步骤 7: 用户审查 → 交接给 writing-plans关键约束：在展示设计并获得批准前，禁止任何实现操作。
4.3 子代理驱动开发流程（Subagent-Driven Development）
触发条件：有已批准的实现计划，需要执行
调用链路：
已批准的实现计划
│
▼
加载 skills/subagent-driven-development/SKILL.md
│
├─ 读取计划，提取所有任务，创建 TodoWrite
│
├─ 对每个任务循环：
│ │
│ ├─ 1. 分派 implementer 子代理
│ │ └─ 使用 implementer-prompt.md 模板
│ │ └─ 子代理返回状态：DONE / DONE_WITH_CONCERNS / NEEDS_CONTEXT / BLOCKED
│ │
│ ├─ 2. 分派 spec-reviewer 子代理（规格合规审查）
│ │ └─ 使用 spec-reviewer-prompt.md 模板
│ │ └─ 独立验证实现是否匹配规格（不信任实现者报告）
│ │
│ ├─ 3. 如有问题 → implementer 修复 → 重新审查
│ │
│ ├─ 4. 分派 code-quality-reviewer 子代理（代码质量审查）
│ │ └─ 使用 code-quality-reviewer-prompt.md 模板
│ │ └─ 仅在规格审查通过后执行
│ │
│ └─ 5. 标记任务完成
│
├─ 所有任务完成后，分派最终代码审查子代理
│
└─ 调用 finishing-a-development-branch 完成开发关键设计：每个任务使用 全新的子代理（Fresh subagent），避免上下文污染。审查分两阶段：先验证”做对了没有”（spec compliance），再验证”做好了没有”（code quality）。
4.4 测试驱动开发流程（TDD）
触发条件：实现任何功能或 bugfix 时
调用链路：
需要实现一个功能
│
▼
加载 skills/test-driven-development/SKILL.md
│
├─ RED: 编写一个最小的失败测试
│ └─ 测试名称清晰，测试真实行为
│
├─ Verify RED: 运行测试，确认失败（不是错误）
│ └─ 铁律：NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST
│
├─ GREEN: 编写最简单的代码使测试通过
│ └─ 不添加额外功能，不重构
│
├─ Verify GREEN: 运行测试，确认通过
│ └─ 确认其他测试仍然通过
│
├─ REFACTOR: 清理代码
│ └─ 移除重复、改进命名、提取 helpers
│ └─ 保持测试绿色
│
└─ 重复下一个测试4.5 系统化调试流程（Systematic Debugging）
触发条件：遇到 bug、测试失败或意外行为
调用链路：
发现 bug
│
▼
加载 skills/systematic-debugging/SKILL.md
│
├─ Phase 1: 根本原因调查
│ ├─ 仔细阅读错误消息
│ ├─ 一致重现问题
│ ├─ 检查最近更改
│ └─ 追踪数据流（向后追溯）
│ └─ 参考 root-cause-tracing.md
│
├─ Phase 2: 模式分析
│ ├─ 找到工作示例
│ ├─ 与参考对比
│ └─ 识别差异
│
├─ Phase 3: 假设和测试
│ ├─ 形成单一假设
│ ├─ 最小化测试
│ └─ 验证后再继续
│
└─ Phase 4: 实现修复
├─ 创建失败测试用例
├─ 实现单一修复
├─ 验证修复
└─ 如果 3+ 修复失败：质疑架构铁律：NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST（不经过根因调查就不修复）
5. 关键设计与实现
5.1 设计模式
策略模式（Strategy Pattern）
技能系统本质上是策略模式的应用：每个 Skill 定义了一种处理特定场景的策略，using-superpowers 充当策略选择器，根据用户意图选择并加载对应的策略。
using-superpowers（策略选择器）
├─ 创造性工作 → brainstorming 策略
├─ 有计划要执行 → subagent-driven-development 策略
├─ 遇到 bug → systematic-debugging 策略
└─ 声称完成 → verification-before-completion 策略责任链模式（Chain of Responsibility）
主工作流形成一条责任链：brainstorming → writing-plans → subagent-driven-development → finishing-a-development-branch，每个环节完成后将控制权传递给下一个。
模板方法模式（Template Method）
子代理提示文件（如 implementer-prompt.md、spec-reviewer-prompt.md）定义了标准化的任务模板，具体任务内容通过占位符注入。
观察者模式（Observer Pattern）
Hook 系统是观察者模式的实现：平台事件（如 SessionStart）触发注册的 hook 脚本执行。
5.2 技能定义规范（数据模型）
每个技能遵循统一的结构规范：
---
name: skill-name # 小写 kebab-case，仅字母、数字、连字符
description: "Use when..." # 以 "Use when" 开头的触发条件描述
---
# 概述
简要说明技能的目的和核心原则
# 工作流程
具体的步骤和规则
# 铁律（Iron Rules）
不可违反的核心约束
# 集成
与其他技能的关系（REQUIRED / Complementary）技能类型：
- Technique：具体方法和步骤（如 TDD、系统化调试）
- Pattern：思考问题的方式（如头脑风暴）
- Reference：API 文档、语法指南（如测试反模式）
5.3 子代理通信协议
子代理通过标准化的状态码进行通信：
| 状态码 | 含义 | 后续动作 |
|---|---|---|
DONE | 任务完成 | 进入审查阶段 |
DONE_WITH_CONCERNS | 完成但有顾虑 | 审查并评估顾虑 |
NEEDS_CONTEXT | 需要更多上下文 | 提供上下文后重试 |
BLOCKED | 被阻塞无法继续 | 升级给人类处理 |
5.4 两阶段审查机制
这是 Superpowers 最核心的质量保证设计：
实现完成
│
▼
第一阶段：规格合规审查（Spec Review）
│ 问题："做对了吗？"
│ 审查者：独立验证，不信任实现者报告
│ 通过 → 进入第二阶段
│ 不通过 → 返回修复
▼
第二阶段：代码质量审查（Code Quality Review）
│ 问题："做好了吗？"
│ 审查者：检查代码质量、可维护性、测试覆盖
│ 通过 → 标记完成
│ 不通过 → 返回修复5.5 跨平台适配策略
Superpowers 通过不同的入口文件适配多个 AI 平台：
| 平台 | 入口机制 | 配置文件 |
|---|---|---|
| Claude Code | Plugin marketplace + hooks | .claude-plugin/plugin.json + hooks/hooks.json |
| Cursor | Plugin marketplace + hooks | .cursor-plugin/plugin.json + hooks/hooks-cursor.json |
| Codex | 符号链接到 ~/.agents/skills/ | .codex/INSTALL.md |
| OpenCode | ES Module 插件 | .opencode/plugins/superpowers.js |
| Gemini CLI | Extension + context file | gemini-extension.json + GEMINI.md |
所有平台最终都会加载同一套 skills/ 目录下的技能定义，实现”一次编写，多平台运行”。
5.6 CSO（Claude Search Optimization）
类似于 SEO（搜索引擎优化），Superpowers 定义了 CSO 概念——优化技能的 description 字段，使 AI 助手能更准确地发现和匹配技能：
- Rich Description：仅描述触发条件，不总结工作流
- Keyword Coverage：包含 AI 会搜索的词（错误消息、症状、同义词）
- Descriptive Naming：主动语态，动词优先
- Token Efficiency：控制技能文档长度（频繁加载的 <200 词）
6. 环境搭建与运行
环境依赖
- 必需：一个支持的 AI 编码助手平台（Claude Code / Cursor / Codex / OpenCode / Gemini CLI）
- 可选：Git（用于 worktree 功能）、GitHub CLI
gh（用于创建 PR）、Node.js（用于 OpenCode 插件和 brainstorm 服务器）
安装步骤
Claude Code（推荐）
# 方式一：官方市场
/plugin install superpowers@claude-plugins-official
# 方式二：社区市场
/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplaceCursor
在 Cursor Agent 聊天中：
/add-plugin superpowers或在插件市场搜索 “superpowers”。
Codex
# 克隆仓库
git clone https://github.com/obra/superpowers.git ~/.codex/superpowers
# 创建符号链接
mkdir -p ~/.agents/skills
ln -s ~/.codex/superpowers/skills ~/.agents/skills/superpowersOpenCode
在 opencode.json 中添加：
{
"plugin": [
"superpowers@git+https://github.com/obra/superpowers.git"
]
}Gemini CLI
gemini extensions install https://github.com/obra/superpowers验证安装
启动新会话，尝试触发技能：
"帮我规划一个新功能" → 应触发 brainstorming 技能
"帮我调试这个问题" → 应触发 systematic-debugging 技能更新
# Claude Code
/plugin update superpowers
# Gemini CLI
gemini extensions update superpowers关键环境变量
| 变量 | 说明 |
|---|---|
SUPERPOWERS_SKILLS_ROOT | 技能目录路径（历史版本使用，当前版本已内置） |
CLAUDE_PLUGIN_ROOT | Claude Code 插件根目录（由平台自动设置） |
CURSOR_PLUGIN_ROOT | Cursor 插件根目录（由平台自动设置） |
BRAINSTORM_OWNER_PID | Brainstorm 服务器的父进程 PID（Windows 上跳过） |
7. 推荐学习路线
阶段一：入门（理解核心概念）
目标：理解 Superpowers 是什么、如何工作
阅读顺序：
README.md— 了解项目定位、核心工作流、安装方式skills/using-superpowers/SKILL.md— 理解技能发现和使用的元规则，这是整个系统的”大脑”hooks/session-start— 理解技能是如何被注入到 AI 助手上下文中的.claude-plugin/plugin.json— 理解插件的元数据结构
需要理解的概念：
- Skill（技能）：一组 Markdown 编写的行为规则和工作流程
- Hook（钩子）：在特定事件（如会话启动）时自动执行的脚本
- Subagent（子代理）：被主 AI 助手分派去执行特定任务的独立 AI 实例
- Frontmatter：Markdown 文件顶部
---包裹的 YAML 元数据
阶段二：进阶（深入核心技能）
目标：理解主工作流的每个环节
阅读顺序：
skills/brainstorming/SKILL.md— 理解需求探索和设计流程skills/writing-plans/SKILL.md— 理解任务拆分策略skills/subagent-driven-development/SKILL.md— 理解子代理调度和两阶段审查skills/subagent-driven-development/implementer-prompt.md— 理解子代理提示模板设计skills/test-driven-development/SKILL.md— 理解 TDD 的强制执行机制skills/systematic-debugging/SKILL.md— 理解系统化调试方法论skills/verification-before-completion/SKILL.md— 理解完成验证的”门函数”设计
需要掌握的机制：
- 技能之间的 REQUIRED 和 Complementary 关系
- 子代理的 状态码通信协议（DONE / BLOCKED / NEEDS_CONTEXT）
- 两阶段审查（spec compliance → code quality）
- 铁律（Iron Rules） 的设计意图
阶段三：实践（动手验证理解）
建议尝试的任务：
- 使用 Superpowers 完成一个小功能：安装插件后，让 AI 助手帮你实现一个简单功能（如一个 CLI 工具），观察完整的 brainstorming → planning → implementation 流程
- 编写一个自定义技能：阅读
skills/writing-skills/SKILL.md，按照 RED-GREEN-REFACTOR for Skills 方法论，创建一个解决你特定问题的技能 - 分析子代理提示模板：对比
implementer-prompt.md、spec-reviewer-prompt.md、code-quality-reviewer-prompt.md，理解不同角色的提示设计差异 - 为新平台添加支持：参考现有的平台适配文件（如
.opencode/plugins/superpowers.js），尝试为一个新的 AI 平台编写适配层
8. 常见问题与注意事项
容易踩的坑
-
commands/目录已废弃：不要使用/brainstorm、/write-plan、/execute-plan命令，它们已被对应的 skill 替代。正确方式是让 AI 助手自动触发技能，或明确要求使用某个技能。 -
版本号不一致：
package.json中版本为5.0.4，.claude-plugin/plugin.json中为5.0.5，gemini-extension.json中为5.0.0。三个配置文件的版本号不同步，以.claude-plugin/plugin.json为最新版本。Gemini 扩展版本滞后是因为 Gemini CLI 支持较新且更新频率较低。 -
Windows 上的 PID 问题：Brainstorm 服务器在 Windows/MSYS2 上会跳过
BRAINSTORM_OWNER_PID生命周期监控，因为 PID 命名空间对 Node.js 不可见。30 分钟空闲超时仍然有效。 -
Node.js ESM 兼容性：
package.json中"type": "module"导致require()在 Node.js 22+ 上失败。brainstorm 服务器已重命名为.cjs后缀解决此问题。 -
旧版安装残留：如果之前使用过 v2.x 版本，
~/.config/superpowers/skills目录可能残留。session-start脚本会检测并警告。
代码中的特殊约定
-
技能命名规范：必须使用小写 kebab-case（如
test-driven-development），仅允许字母、数字、连字符。 -
技能引用命名空间：内部引用使用
superpowers:前缀（如superpowers:test-driven-development），这是 Claude Code 插件系统的命名空间机制。 -
SKILL.md 是唯一入口：每个技能目录下的
SKILL.md是 AI 助手加载的入口文件，其他.md文件是被SKILL.md引用的辅助文件。 -
Description 字段的 CSO 规范：
- 必须以
"Use when..."开头 - 仅描述触发条件，不总结工作流
- 使用第三人称
- 最大 1024 字符
- 必须以
-
铁律（Iron Rules）不可违反：每个技能中标记为 “Iron Rule” 的规则是绝对约束，AI 助手不应在任何情况下绕过。例如：
- TDD：
NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST - 调试：
NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST - 验证：
NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE
- TDD：
技术债务与注意事项
-
commands/目录待移除：三个命令文件已标记为废弃，将在下一个主版本中移除。 -
Gemini 扩展版本滞后：
gemini-extension.json中版本号为5.0.0，与.claude-plugin/plugin.json的5.0.5不同步。Gemini CLI 支持是较晚添加的功能，更新频率低于主平台。 -
Brainstorm 可视化伴侣：
skills/brainstorming/visual-companion.md引用的脚本文件位于skills/brainstorming/scripts/目录下（包括start-server.sh、stop-server.sh、frame-template.html、helper.js），用于启动基于浏览器的可视化头脑风暴伴侣。服务器在 30 分钟无活动后自动退出。 -
测试覆盖不均匀：
tests/目录下的测试主要是 Shell 脚本形式的集成测试，依赖 Claude Code 的 headless 模式运行，无法在普通 CI 环境中自动执行。 -
多平台配置同步：五个平台的配置文件需要手动保持同步（版本号、描述等），当前已存在版本号不一致的情况（
plugin.json为 5.0.5，gemini-extension.json为 5.0.0）。