Superpowers 架构说明文档Superpowers是一套面向编码代理的软件开发方法论，以14个可组合Skill为

1. 项目概述

Superpowers 是一套面向编码代理（Coding Agent）的完整软件开发方法论系统，以可组合的 Skills（技能） 为核心，通过 Hooks（钩子） 在会话启动时自动注入上下文，使编码代理自觉遵循 TDD、系统化调试、协作式设计等最佳实践。

版本: 5.0.7
作者: Jesse Vincent / Prime Radiant
许可: MIT
设计原则: 零外部依赖、跨平台（Claude Code / Cursor / Codex / OpenCode / Gemini / Copilot CLI）

2. 顶层目录结构

superpowers-main/
├── .claude-plugin/          # Claude Code 插件定义
│   ├── plugin.json          # 插件元数据（名称、版本、作者）
│   └── marketplace.json     # 开发市场配置
├── .codex/                  # OpenAI Codex CLI 安装指南
│   └── INSTALL.md
├── .cursor-plugin/          # Cursor 插件定义
│   └── plugin.json          # 含 skills/agents/commands/hooks 路径声明
├── .opencode/               # OpenCode 插件
│   └── plugins/
│       └── superpowers.js   # OpenCode 系统提示注入 + 技能目录注册
├── .github/                 # GitHub 模板（PR、Issue）
├── agents/                  # Agent 角色定义
│   └── code-reviewer.md     # 代码审查员角色
├── commands/                # 快捷命令（均已弃用，重定向到技能）
│   ├── brainstorm.md
│   ├── write-plan.md
│   └── execute-plan.md
├── docs/                    # 文档
│   ├── plans/               # 历史设计计划
│   ├── superpowers/
│   │   ├── plans/           # 功能实现计划文档
│   │   └── specs/           # 功能设计规格文档
│   ├── windows/             # Windows 平台相关文档
│   ├── testing.md           # 测试指南
│   ├── README.codex.md
│   └── README.opencode.md
├── hooks/                   # 会话钩子
│   ├── hooks.json           # Claude Code 钩子配置
│   ├── hooks-cursor.json    # Cursor 钩子配置
│   ├── run-hook.cmd         # 跨平台 polyglot 包装器
│   └── session-start        # 会话启动脚本（bash）
├── scripts/                 # 构建脚本
│   ├── bump-version.sh      # 多文件版本号同步工具
│   └── sync-to-codex-plugin.sh
├── skills/                  # ★ 核心技能库（14 个技能）
│   ├── brainstorming/
│   ├── dispatching-parallel-agents/
│   ├── executing-plans/
│   ├── finishing-a-development-branch/
│   ├── receiving-code-review/
│   ├── requesting-code-review/
│   ├── subagent-driven-development/
│   ├── systematic-debugging/
│   ├── test-driven-development/
│   ├── using-git-worktrees/
│   ├── using-superpowers/   # ★ 引导技能（会话启动时自动加载）
│   ├── verification-before-completion/
│   ├── writing-plans/
│   └── writing-skills/
├── tests/                   # 集成测试
│   ├── brainstorm-server/
│   ├── claude-code/
│   ├── explicit-skill-requests/
│   ├── opencode/
│   ├── skill-triggering/
│   └── subagent-driven-dev/
├── AGENTS.md                # 贡献者指南（AI Agent 行为约束）
├── CLAUDE.md                # Claude Code 贡献指南（同 AGENTS.md）
├── GEMINI.md                # Gemini 引导文件
├── gemini-extension.json    # Gemini 扩展定义
├── package.json             # NPM 包定义（入口：.opencode/plugins/superpowers.js）
└── .version-bump.json       # 版本号同步配置

3. 核心架构

3.1 架构总览

┌──────────────────────────────────────────────────────────────────┐
│                        Coding Agent 平台                          │
│  (Claude Code / Cursor / Codex / OpenCode / Gemini / Copilot)   │
└────────────┬─────────────────────────────────────┬───────────────┘
             │ 会话启动                              │ Skill Tool
             ▼                                      ▼
┌────────────────────────┐             ┌─────────────────────────┐
│      Hooks 系统         │             │     Skills 技能库        │
│  (session-start 钩子)   │             │  (14 个可组合技能)       │
│                        │             │                         │
│  自动注入 using-        │             │  brainstorming →        │
│  superpowers 技能内容   │             │  writing-plans →        │
│  作为上下文             │             │  subagent-driven-dev →  │
│                        │             │  finishing-branch       │
└────────────────────────┘             └─────────────────────────┘
             │                                      │
             ▼                                      ▼
┌────────────────────────┐             ┌─────────────────────────┐
│   Agent 角色定义        │             │   Commands 快捷命令     │
│   (code-reviewer)      │             │   (已弃用，重定向到技能) │
└────────────────────────┘             └─────────────────────────┘

3.2 会话启动流程

Agent 平台启动会话
       │
       ▼
  触发 SessionStart Hook
       │
       ▼
  hooks/session-start 脚本执行
       │
       ├── 读取 skills/using-superpowers/SKILL.md 内容
       ├── 检测遗留目录 (~/.config/superpowers/skills) 生成警告
       ├── JSON 转义处理
       │
       ▼
  根据平台输出不同格式:
       │
       ├── Cursor → additional_context (snake_case)
       ├── Claude Code → hookSpecificOutput.additionalContext (嵌套)
       └── Copilot CLI / 其他 → additionalContext (顶层)
       │
       ▼
  Agent 收到 <EXTREMELY_IMPORTANT> 标签包裹的引导上下文
       │
       ▼
  Agent 了解到: 必须在任何操作前检查并调用相关技能

3.3 跨平台适配层

Superpowers 通过不同的适配层支持 6 个编码代理平台：

平台	适配方式	配置文件
Claude Code	Plugin 系统 + hooks.json + Skill Tool	`.claude-plugin/plugin.json`
Cursor	Plugin 系统 + hooks-cursor.json + Skill Tool	`.cursor-plugin/plugin.json`
OpenAI Codex CLI	原生 skill 发现（符号链接）	`.codex/INSTALL.md`
OpenCode	JS 插件（system prompt transform + config hook）	`.opencode/plugins/superpowers.js`
Gemini CLI	Extension 系统 + GEMINI.md 引导	`gemini-extension.json` + `GEMINI.md`
Copilot CLI	Plugin marketplace + Skill Tool	复用 Claude Code 风格

OpenCode 适配细节：

superpowers.js 通过 config 钩子将技能目录注入 OpenCode 配置
通过 experimental.chat.messages.transform 将引导内容注入首条用户消息（避免系统消息 token 膨胀）
自动映射工具名（TodoWrite → todowrite，Task → @mention 等）

4. Skills 技能系统

4.1 技能通用结构

每个技能遵循统一的目录结构：

skills/skill-name/
├── SKILL.md              # 主文档（必需），含 YAML frontmatter
└── supporting-file.*     # 可选辅助文件（大型参考、工具脚本等）

SKILL.md frontmatter 规范：

---
name: skill-name-with-hyphens    # 仅字母、数字、连字符
description: Use when [触发条件]   # 第三人称，描述何时使用，不含流程摘要
---

关键设计约束：

description 只描述触发条件，不摘要技能流程（防止 Agent 走捷径跳过完整技能内容）
技能内容是行为塑造代码而非普通文档，修改需经过对抗性压力测试

4.2 技能分类与职责

协作类技能（核心工作流）

技能	触发条件	核心职责
brainstorming	任何创造性工作之前	苏格拉底式提问 → 探索方案 → 分段呈现设计 → 写设计文档 → 转入 writing-plans
writing-plans	有规格/需求的多步骤任务	将设计分解为 2-5 分钟粒度的任务，每步含完整代码、命令、预期输出
subagent-driven-development	执行含独立任务的实现计划	每任务分派新子代理 → 规格合规审查 → 代码质量审查 → 循环直到通过
executing-plans	在独立会话中执行实现计划	批量执行 + 人工检查点（无子代理时的替代方案）
dispatching-parallel-agents	2+ 个无依赖的独立任务	每问题域一个 Agent 并行调查
requesting-code-review	完成任务/功能/合并前	分派 code-reviewer 子代理审查
receiving-code-review	收到代码审查反馈时	技术评估优先，禁止表演性赞同，支持有理据的反驳
using-git-worktrees	开始需要隔离的功能开发	创建隔离工作区 + 安全验证 + 测试基线确认
finishing-a-development-branch	实现完成，所有测试通过	验证测试 → 提供 4 个选项（合并/PR/保留/丢弃）→ 清理 worktree

测试与调试类技能

技能	触发条件	核心职责
test-driven-development	实现任何功能或修复之前	RED（写失败测试）→ GREEN（最小编码通过）→ REFACTOR（重构）
systematic-debugging	遇到 bug/测试失败/异常行为	四阶段：根因调查 → 模式分析 → 假设验证 → 实现（3 次修复失败则质疑架构）
verification-before-completion	声称完成/修复/通过之前	铁律：无新鲜验证证据 = 不可声称完成

元技能

技能	触发条件	核心职责
using-superpowers	任何对话开始时	引导 Agent 如何发现和调用技能（会话启动时自动注入）
writing-skills	创建/编辑/验证技能	将 TDD 应用于文档：先测失败基线 → 写技能 → 验证合规 → 重构堵漏

4.3 核心工作流（End-to-End）

用户提出需求
     │
     ▼
① brainstorming（头脑风暴）
  · 探索项目上下文
  · 逐个提问澄清需求
  · 提出 2-3 种方案及权衡
  · 分段呈现设计，获取用户批准
  · 写设计文档 → docs/superpowers/specs/
     │
     ▼
② using-git-worktrees（创建隔离工作区）
  · 选择目录（.worktrees/ 优先）
  · 创建 worktree + 新分支
  · 运行项目设置 + 验证测试基线
     │
     ▼
③ writing-plans（编写实现计划）
  · 将设计分解为 2-5 分钟粒度的任务
  · 每步含完整代码、命令、预期输出
  · 保存计划 → docs/superpowers/plans/
     │
     ▼
④ subagent-driven-development（子代理驱动开发）
  · 每任务分派新实现子代理
  · 实现子代理：实现 → 测试 → 自审 → 提交
  · 规格审查子代理：确认代码符合规格
  · 代码质量审查子代理：确认代码质量达标
  · 审查不通过 → 修复 → 重新审查
     │
     ▼
⑤ test-driven-development（贯穿全过程）
  · RED → GREEN → REFACTOR 循环
  · 子代理在每个任务中遵循 TDD
     │
     ▼
⑥ finishing-a-development-branch（完成开发分支）
  · 验证全部测试通过
  · 提供选项：合并 / PR / 保留 / 丢弃
  · 清理 worktree

4.4 技能优先级与触发机制

优先级规则：

用户显式指令（CLAUDE.md / GEMINI.md / AGENTS.md）> 技能 > 系统默认
流程类技能优先（brainstorming、debugging）→ 实现类技能其次
即使只有 1% 的可能性，也必须调用技能检查

反合理化表（核心防护机制）：

思维	现实
"这只是一个简单问题"	问题是任务，检查技能
"我先收集信息"	技能告诉你如何收集
"这不需要正式技能"	技能存在就必须使用
"我记得这个技能"	技能会演进，读取当前版本
"技能大材小用了"	简单事变复杂，用技能预防

5. Hooks 系统

5.1 架构

hooks/
├── hooks.json           # Claude Code: SessionStart → run-hook.cmd session-start
├── hooks-cursor.json    # Cursor: sessionStart → ./hooks/session-start
├── run-hook.cmd         # Polyglot 包装器（Windows CMD + Unix bash 双语法）
└── session-start        # 实际启动逻辑（bash 脚本）

5.2 session-start 脚本职责

读取 skills/using-superpowers/SKILL.md 内容
检查遗留目录 ~/.config/superpowers/skills，生成迁移警告
对内容进行 JSON 转义（纯 bash 实现，无外部依赖）
根据平台环境变量输出对应 JSON 格式：
- CURSOR_PLUGIN_ROOT 存在 → Cursor 格式
- CLAUDE_PLUGIN_ROOT 存在且无 COPILOT_CLI → Claude Code 格式
- 其他 → SDK 标准格式

5.3 跨平台 Polyglot 包装器

run-hook.cmd 同时是合法的 Windows 批处理和 Unix shell 脚本：

Windows：CMD 解释 : << 'CMDBLOCK' 为标签（忽略），执行 @echo off 后调用 Git Bash
Unix：: 是空操作，<< 'CMDBLOCK' 开启 heredoc 消费 CMD 代码块，然后执行 bash 脚本

6. 测试体系

6.1 测试结构

tests/
├── brainstorm-server/          # Brainstorm 可视化服务器测试
│   ├── server.test.js          # WebSocket 协议测试
│   └── ws-protocol.test.js
├── claude-code/                # Claude Code 集成测试
│   ├── run-skill-tests.sh      # 测试运行器
│   ├── test-helpers.sh         # 共享工具函数
│   ├── test-subagent-driven-development.sh
│   ├── test-subagent-driven-development-integration.sh
│   └── analyze-token-usage.py  # Token 用量分析
├── explicit-skill-requests/    # 显式技能请求测试
│   ├── run-all.sh
│   └── prompts/                # 各种测试提示词
├── opencode/                   # OpenCode 平台测试
│   ├── test-plugin-loading.sh
│   ├── test-priority.sh
│   └── test-tools.sh
├── skill-triggering/           # 技能自动触发测试
│   └── prompts/
└── subagent-driven-dev/        # SDD 端到端测试
    ├── go-fractals/            # Go 分形项目测试
    └── svelte-todo/            # Svelte TODO 项目测试

6.2 测试方法论

集成测试：在真实 Claude Code 会话中运行，解析 .jsonl 会话日志验证行为
压力测试：对纪律型技能施加时间、沉没成本、权威等多重压力
对抗测试：识别 Agent 合理化借口，在技能中添加显式反驳
基线对比：RED（无技能时记录 Agent 行为）→ GREEN（有技能时验证合规）

7. 构建与发布

7.1 版本管理

package.json 中定义版本号（当前 5.0.7）
.version-bump.json 声明所有需要同步版本号的文件和 JSON 字段路径
scripts/bump-version.sh 支持：
- bump-version.sh <version> — 同步所有声明文件
- bump-version.sh --check — 检测版本漂移
- bump-version.sh --audit — 全仓库审计遗漏的旧版本字符串

7.2 多平台发布

版本号需在以下文件中保持同步：

package.json
.claude-plugin/plugin.json
.claude-plugin/marketplace.json
.cursor-plugin/plugin.json
gemini-extension.json

8. 设计哲学

原则	体现
零外部依赖	所有逻辑用纯 bash/JS 实现，不引入第三方库
TDD 优先	技能本身用 TDD 方法创建：先测失败 → 写技能 → 验证合规
系统化 > 即兴	流程驱动而非猜测驱动
证据 > 断言	verification-before-completion 铁律：无证据不声称成功
行为塑造	技能是塑造 Agent 行为的代码，修改需对抗性压力测试
反合理化	每个纪律型技能都含合理化反驳表和红旗列表
用户控制	用户指令 > 技能规则 > 系统默认

9. 关键技术决策

技能自动触发而非手动调用：通过 using-superpowers 引导技能 + EXTREMELY_IMPORTANT 标签确保 Agent 在任何操作前检查技能
description 只写触发条件：测试发现，如果 description 包含流程摘要，Agent 会走捷径只读摘要而跳过完整技能内容
子代理隔离上下文：每个任务分派全新子代理，不继承会话历史，防止上下文污染
两阶段审查：先审查规格合规性（是否做了对的事），再审查代码质量（是否把事做对了），顺序不可颠倒
Polyglot 钩子脚本：同一文件同时是合法的 Windows 批处理和 Unix shell，解决跨平台钩子执行问题
OpenCode 注入到用户消息：避免系统消息每轮重复导致 token 膨胀，也避免多系统消息破坏 Qwen 等模型
3 次修复失败 → 质疑架构：系统性调试中的关键阈值，防止在错误架构上持续打补丁