superpowers 开源项目解读
项目信息
项目名称：superpowers
项目描述：Superpowers 是一套让 AI 编码 Agent 学会"软件工程纪律"的插件系统。通过 14 个可组合的 Markdown 技能，它强制 Agent 遵循：先设计 → 再计划 → 再实现 → 测试 → 审查 → 合并 的完整流程。支持 7 个编码平台，零外部依赖。
superpowers-zh项目 (汉化版) 文档：https://github.com/jnMetaCode/superpowers-zh
解决的核心痛点：
- AI 编码 Agent 缺乏工程纪律 — 跳过设计、测试、架构考虑
- 跨平台 Agent 行为不一致 — 各编码平台缺乏统一工作流标准
- 开发流程碎片化 — 从需求到合并的全流程缺乏自动化编排
核心工作流 (5 步)
用户说"帮我做X" → ① brainstorming (需求澄清)
→ ② writing-plans (任务拆分)
→ ③ subagent-driven-dev (自动执行)
→ ④ TDD + Code Review (质量保证)
→ ⑤ finishing (合并交付)1. 项目概览
1.1 项目定位与核心价值
Superpowers 是一套面向编码 Agent 的完整软件开发方法论，通过可组合的技能 (Skills) 和引导指令，将 AI 编码助手从"代码补全工具"升级为能自主遵循工程纪律的"全流程开发伙伴"。
- 一句话定位：面向 AI 编码 Agent 的零依赖、跨平台软件开发方法论插件
- 版本: v5.1.0
- 许可证: MIT
- 作者: Jesse Vincent (Prime Radiant)
- GitHub: obra/superpowers
解决的核心痛点：
- AI 编码 Agent 缺乏工程纪律 — 跳过设计、测试、架构考虑
- 跨平台 Agent 行为不一致 — 各编码平台缺乏统一工作流标准
- 开发流程碎片化 — 从需求到合并的全流程缺乏自动化编排
1.2 目标用户与使用场景
- 主要用户：使用 AI 编码 Agent 的软件开发者
- 贡献者：改进 Agent 工作流质量的工具开发者
- 平台适配者：为新编码平台适配 Superpowers 的开发者
1.3 核心技术亮点
- Hook 驱动的自动引导：SessionStart 时自动注入技能系统，无需用户手动操作
- HARD-GATE 阶段门：通过语言约束（非代码）强制 Agent 遵循设计→计划→实现→测试→审查流程
- 子Agent驱动开发：每个任务分派给独立上下文的子Agent，经两阶段审查（规格+质量）
- Red Flags 反合理化系统：预先识别 Agent 的 12+ 种常见借口并逐条反制
- 零依赖设计：纯 Markdown + Shell，无需任何 npm/PyPI 依赖
- 跨平台适配：7 个编码平台，单一引导脚本通过环境变量自适应
1.4 技术栈与选型对比
| 维度 | Superpowers 的选择 | 替代方案 | 选择理由 |
|---|---|---|---|
| 技能载体 | Markdown | 代码 SDK / YAML 规则 | LLM 最易理解，无需解析 |
| 引导机制 | Hook SessionStart 注入 | 用户手动加载 | 自动化 = 可靠性 |
| 依赖策略 | 零依赖 | npm/PyPI 包 | 跨平台兼容，避免供应链风险 |
| 行为约束 | 自然语言指令 (HARD-GATE等) | 程序级约束 | 灵活且跨模型通用 |
| 图表语言 | Graphviz DOT + ASCII | Mermaid 独占 | DOT 在纯文本环境更稳定 |
2. 整体架构设计
2.1 架构概述
Superpowers 采用 Hook 驱动 + 技能组合 (Hook-Driven + Composable Skills) 的分层架构。系统由四层组成：
- 平台适配层 (Harness Layer)：各编码平台 (Claude Code, Codex, Cursor 等) 的插件清单，定义插件元数据和 Hook 触发规则。
- 引导注入层 (Bootstrap Layer)：
SessionStartHook 在每次会话启动时自动将using-superpowers技能内容注入 Agent 的上下文窗口，教会 Agent 如何使用技能系统。 - 技能编排层 (Skill Orchestration Layer)：14 个技能按工作流形成严格的有向无环图 (DAG)，通过 frontmatter 元数据和技能内容中的
<HARD-GATE>标签控制流转。 - 执行支撑层 (Execution Support Layer)：SubAgent 定义、自定义命令、测试套件、构建脚本等辅助设施。
2.2 整体架构图
text
+=====================================================================+
| 平台适配层 (Harness Layer) |
| |
| +------------------+ +------------------+ +------------------+ |
| | .claude-plugin/ | | .codex-plugin/ | | .cursor-plugin/ | |
| | plugin.json | | plugin.json | | plugin.json | |
| | hooks.json | | | | hooks-cursor.json| |
| +--------+---------+ +--------+---------+ +--------+---------+ |
| | | | |
| +--------v---------+ +--------v---------+ +--------v---------+ |
| | .opencode/ | | gemini-extension | | package.json | |
| | plugins/*.js | | .json | | (Factory Droid) | |
| +------------------+ +------------------+ +------------------+ |
+==================================+==================================+
|
| SessionStart Hook 触发
v
+=====================================================================+
| 引导注入层 (Bootstrap Layer) |
| |
| +-------------------------------------------------------------+ |
| | hooks/session-start (bash) | |
| | - 读取 skills/using-superpowers/SKILL.md | |
| | - JSON 转义后注入到 Agent 上下文 | |
| | - 按平台输出不同 JSON 格式 | |
| | (hookSpecificOutput vs additionalContext vs additional_context)| |
| +-------------------------------------------------------------+ |
| |
| +-------------------------------------------------------------+ |
| | skills/using-superpowers/SKILL.md | |
| | - 教会 Agent 如何使用 Skill 工具 | |
| | - 定义技能优先级规则 (Process > Implementation) | |
| | - Red Flags 表格 (防止 Agent 跳过技能) | |
| | - 跨平台工具映射指引 | |
| +-------------------------------------------------------------+ |
+==================================+==================================+
|
| Agent 学习后自主触发
v
+=====================================================================+
| 技能编排层 (Skill Orchestration Layer) |
| |
| 主工作流 (Linear DAG): |
| |
| +----------------+ +----------------+ +----------------+ |
| | brainstorming |--->| writing-plans |--->| subagent- | |
| | (需求→设计) | | (设计→任务) | | driven-dev | |
| +----------------+ +----------------+ | (执行任务) | |
| +-------+--------+ |
| | |
| +---------------------------+ |
| | |
| +------------v-----------+ |
| | test-driven-development| (内嵌，每次实现时触发) |
| +------------+-----------+ |
| | |
| +------------v-----------+ |
| | requesting-code-review | (任务间审查) |
| +------------+-----------+ |
| | |
| +------------v-----------+ |
| | finishing-a-dev-branch | (合并/PR/清理) |
| +------------------------+ |
| |
| 辅助技能 (On-Demand): |
| +------------------------+ +---------------------------+ |
| | systematic-debugging | | using-git-worktrees | |
| | (4 阶段根因分析) | | (隔离工作区管理) | |
| +------------------------+ +---------------------------+ |
| +------------------------+ +---------------------------+ |
| | verification-before- | | dispatching-parallel- | |
| | completion | | agents | |
| | (完成前验证) | | (并行Agent调度) | |
| +------------------------+ +---------------------------+ |
| +------------------------+ +---------------------------+ |
| | receiving-code-review | | executing-plans | |
| | (响应审查反馈) | | (批量执行替代方案) | |
| +------------------------+ +---------------------------+ |
| |
| 元技能: |
| +-------------------------------------------------------------+ |
| | writing-skills (编写和测试新技能的完整方法论) | |
| +-------------------------------------------------------------+ |
+=====================================================================+
|
v
+=====================================================================+
| 执行支撑层 (Execution Support Layer) |
| |
| +-------------------+ +-------------------+ +------------------+ |
| | agents/ | | commands/ | | tests/ | |
| | code-reviewer | | (自定义斜杠命令) | | 多平台测试套件 | |
| +-------------------+ +-------------------+ +------------------+ |
| +-------------------+ +-------------------+ +------------------+ |
| | scripts/ | | docs/ | | assets/ | |
| | bump-version.sh | | 设计文档与归档 | | 静态资源 | |
| | sync-to-codex.sh | | | | | |
| +-------------------+ +-------------------+ +------------------+ |
+=====================================================================+2.3 目录结构
text
superpowers/
├── skills/ # 【核心基建】AI 技能定义库（14个可组合技能）
│ ├── using-superpowers/ # 【核心基建】系统引导技能 — 教会Agent如何使用技能系统
│ │ ├── SKILL.md # 【核心基建】主技能文件（SessionStart时强制注入）
│ │ └── references/ # 【工具集】跨平台工具名称映射
│ │ ├── codex-tools.md # 【工具集】Codex CLI 工具与 CC 工具对照表
│ │ ├── copilot-tools.md # 【工具集】Copilot CLI 工具与 CC 工具对照表
│ │ └── gemini-tools.md # 【工具集】Gemini CLI 工具与 CC 工具对照表
│ ├── brainstorming/ # 【业务模块】工作流第1步 — 需求澄清与设计生成
│ │ ├── SKILL.md # 【核心基建】9步工作流 + HARD-GATE 强制设计先行
│ │ ├── visual-companion.md # 【业务模块】可视化伴侣触发条件与行为规范
│ │ ├── spec-document-reviewer-prompt.md # 【业务模块】规格文档自我审查提示词
│ │ ├── ANNOTATIONS.md # 【配置】技能设计注解（人类可读的设计意图说明）
│ │ └── scripts/ # 【工具集】零依赖头脑风暴可视化服务器
│ │ ├── server.cjs # 【核心基建】WebSocket 服务器（Node.js 内置模块）
│ │ ├── helper.js # 【工具集】浏览器端渲染辅助脚本
│ │ ├── start-server.sh # 【工具集】服务器启动（含端口检测与清理）
│ │ ├── stop-server.sh # 【工具集】服务器停止与资源回收
│ │ └── frame-template.html # 【UI 视图】设计预览框架 HTML 模板
│ ├── writing-plans/ # 【业务模块】工作流第2步 — 设计→细粒度任务计划
│ │ ├── SKILL.md # 【核心基建】计划编写规范（2-5分钟级任务粒度）
│ │ ├── plan-document-reviewer-prompt.md # 【业务模块】计划文档审查提示词
│ │ └── ANNOTATIONS.md # 【配置】技能设计注解
│ ├── subagent-driven-development/ # 【业务模块】工作流第3步-A — 子Agent驱动任务执行
│ │ ├── SKILL.md # 【核心基建】每任务一个子Agent + 两阶段审查流程
│ │ ├── implementer-prompt.md # 【业务模块】实现者子Agent的系统提示词
│ │ ├── spec-reviewer-prompt.md # 【业务模块】规格合规审查子Agent提示词
│ │ ├── code-quality-reviewer-prompt.md # 【业务模块】代码质量审查子Agent提示词
│ │ └── ANNOTATIONS.md # 【配置】技能设计注解
│ ├── executing-plans/ # 【业务模块】工作流第3步-B — 批量执行（替代方案）
│ │ └── SKILL.md # 【核心基建】带人工检查点的批量任务执行
│ ├── test-driven-development/ # 【业务模块】TDD 纪律 — RED-GREEN-REFACTOR 循环
│ │ ├── SKILL.md # 【核心基建】铁律：无失败测试=无产品代码
│ │ ├── testing-anti-patterns.md # 【工具集】测试反模式参考手册
│ │ └── ANNOTATIONS.md # 【配置】技能设计注解
│ ├── systematic-debugging/ # 【业务模块】4阶段系统化调试方法论
│ │ ├── SKILL.md # 【核心基建】根因分析→修复设计→实施→验证
│ │ ├── root-cause-tracing.md # 【业务模块】根因追溯技术详解
│ │ ├── defense-in-depth.md # 【业务模块】纵深防御修复策略
│ │ ├── condition-based-waiting.md # 【业务模块】条件等待技术（替代盲目sleep）
│ │ ├── condition-based-waiting-example.ts # 【工具集】条件等待 TypeScript 示例代码
│ │ ├── find-polluter.sh # 【工具集】Git bisect 辅助脚本
│ │ ├── ANNOTATIONS.md # 【配置】技能设计注解
│ │ ├── CREATION-LOG.md # 【配置】技能创建过程的技术日志
│ │ ├── test-academic.md # 【质量保证】学术场景压力测试用例
│ │ ├── test-pressure-1.md # 【质量保证】压力测试用例 1
│ │ ├── test-pressure-2.md # 【质量保证】压力测试用例 2
│ │ └── test-pressure-3.md # 【质量保证】压力测试用例 3
│ ├── requesting-code-review/ # 【业务模块】任务间代码审查请求
│ │ ├── SKILL.md # 【核心基建】审查请求流程与模板
│ │ └── code-reviewer.md # 【业务模块】代码审查器角色定义
│ ├── receiving-code-review/ # 【业务模块】审查反馈的接收与响应
│ │ └── SKILL.md # 【核心基建】响应审查反馈的规范流程
│ ├── using-git-worktrees/ # 【业务模块】Git Worktree 并行开发与隔离
│ │ └── SKILL.md # 【核心基建】Worktree 创建/管理/清理流程
│ ├── finishing-a-development-branch/ # 【业务模块】功能完结 — 合并/PR/清理
│ │ └── SKILL.md # 【核心基建】检测环境→呈现选项→执行清理
│ ├── dispatching-parallel-agents/ # 【业务模块】并行子Agent协调调度
│ │ └── SKILL.md # 【核心基建】并发Agent调度模式
│ ├── verification-before-completion/ # 【业务模块】完成前验证 — 确保修复有效
│ │ └── SKILL.md # 【核心基建】验证清单与检查流程
│ └── writing-skills/ # 【业务模块】元技能 — 编写与测试新技能
│ ├── SKILL.md # 【核心基建】技能开发方法论与测试框架
│ ├── anthropic-best-practices.md # 【工具集】Anthropic 官方技能编写最佳实践
│ ├── persuasion-principles.md # 【工具集】说服心理学原则（用于技能措辞设计）
│ ├── testing-skills-with-subagents.md # 【工具集】子Agent测试技能的方法
│ ├── graphviz-conventions.dot # 【工具集】DOT 图绘制规范（用于技能流程图）
│ ├── render-graphs.js # 【工具集】Graphviz 图表渲染成 SVG
│ └── examples/ # 【工具集】技能编写参考示例
│ └── CLAUDE_MD_TESTING.md # 【工具集】CLAUDE.md 测试策略示例
├── hooks/ # 【核心基建】多平台 Hook 触发系统
│ ├── hooks.json # 【配置】Claude Code Hook 配置（SessionStart 触发）
│ ├── hooks-cursor.json # 【配置】Cursor Hook 配置（SessionStart 触发）
│ ├── session-start # 【核心基建】平台自适应 SessionStart 引导脚本
│ ├── run-hook.cmd # 【工具集】Windows 兼容 Hook 启动器
│ └── MODULE.md # 【配置】hooks 模块功能说明文档
├── agents/ # 【核心基建】自定义 SubAgent 定义目录
│ ├── code-reviewer/ # 【业务模块】代码审查 SubAgent 行为定义
│ │ └── ANNOTATIONS.md # 【配置】审查 Agent 的设计意图说明
│ └── MODULE.md # 【配置】agents 模块功能说明文档
├── commands/ # 【业务模块】自定义斜杠命令
│ └── MODULE.md # 【配置】commands 模块功能说明文档
├── tests/ # 【质量保证】多平台集成测试套件
│ ├── brainstorm-server/ # 【质量保证】头脑风暴 WebSocket 服务器测试
│ │ ├── server.test.js # 【质量保证】服务器功能单元测试（427行）
│ │ ├── ws-protocol.test.js # 【质量保证】WebSocket 协议测试（392行）
│ │ ├── windows-lifecycle.test.sh # 【质量保证】Windows 生命周期测试
│ │ └── package.json # 【配置】测试依赖配置
│ ├── claude-code/ # 【质量保证】Claude Code 平台集成测试
│ │ ├── run-skill-tests.sh # 【工具集】全量技能测试执行器
│ │ ├── test-helpers.sh # 【工具集】测试通用辅助函数库
│ │ ├── test-subagent-driven-development.sh # 【质量保证】SDD 功能测试
│ │ ├── test-subagent-driven-development-integration.sh # 【质量保证】SDD 集成测试
│ │ ├── test-requesting-code-review.sh # 【质量保证】Code Review 流程测试
│ │ ├── test-document-review-system.sh # 【质量保证】文档审查系统测试
│ │ ├── test-worktree-native-preference.sh # 【质量保证】Worktree 原生偏好测试
│ │ └── analyze-token-usage.py # 【工具集】Token 使用量分析工具
│ ├── explicit-skill-requests/ # 【质量保证】显式技能请求测试
│ │ ├── run-all.sh # 【工具集】全量多模型测试执行器
│ │ ├── run-test.sh # 【工具集】基础测试执行器
│ │ ├── run-haiku-test.sh # 【工具集】Haiku 模型专用测试
│ │ ├── run-multiturn-test.sh # 【工具集】多轮对话测试
│ │ ├── run-extended-multiturn-test.sh # 【工具集】扩展多轮对话测试
│ │ ├── run-claude-describes-sdd.sh # 【工具集】Claude SDD 描述测试
│ │ └── prompts/ # 【质量保证】测试提示词集合
│ ├── opencode/ # 【质量保证】OpenCode 平台集成测试
│ │ ├── run-tests.sh # 【工具集】OpenCode 测试执行器
│ │ ├── setup.sh # 【工具集】OpenCode 环境配置
│ │ ├── test-bootstrap-caching.mjs # 【质量保证】引导缓存机制测试
│ │ ├── test-bootstrap-caching.sh # 【质量保证】引导缓存 Shell 测试
│ │ ├── test-plugin-loading.sh # 【质量保证】插件加载机制测试
│ │ ├── test-priority.sh # 【质量保证】技能优先级测试
│ │ └── test-tools.sh # 【质量保证】工具映射测试
│ ├── skill-triggering/ # 【质量保证】技能自动触发机制测试
│ │ ├── run-all.sh # 【工具集】全量触发场景测试
│ │ ├── run-test.sh # 【工具集】单项触发测试
│ │ └── prompts/ # 【质量保证】触发测试提示词
│ ├── subagent-driven-dev/ # 【质量保证】SDD 端到端测试
│ │ ├── run-test.sh # 【工具集】SDD 功能测试执行器
│ │ ├── go-fractals/ # 【质量保证】Go 分形项目测试用例
│ │ └── svelte-todo/ # 【质量保证】Svelte Todo 测试用例
│ └── codex-plugin-sync/ # 【质量保证】Codex 插件同步机制测试
│ └── test-sync-to-codex-plugin.sh # 【工具集】同步功能测试
├── docs/ # 【配置】项目文档与设计决策归档
│ ├── plans/ # 【配置】历史开发计划（2025-2026）
│ ├── superpowers/ # 【配置】内部设计文档
│ │ ├── plans/ # 【配置】功能开发计划（5个已实现功能）
│ │ └── specs/ # 【配置】详细技术设计规格（5个设计文档）
│ ├── README.opencode.md # 【配置】OpenCode 平台详细安装文档
│ ├── testing.md # 【配置】测试策略与方法指南
│ └── windows/ # 【配置】Windows 平台适配文档
│ └── polyglot-hooks.md # 【配置】跨平台 Hook 兼容性说明
├── .claude-plugin/ # 【核心基建】Claude Code 平台插件清单
│ ├── plugin.json # 【配置】插件注册元数据
│ └── marketplace.json # 【配置】Marketplace 列表信息
├── .codex-plugin/ # 【核心基建】Codex CLI 平台插件清单
│ └── plugin.json # 【配置】插件注册元数据
├── .cursor-plugin/ # 【核心基建】Cursor 平台插件清单
│ └── plugin.json # 【配置】插件注册元数据
├── .opencode/ # 【核心基建】OpenCode 平台插件实现
│ ├── INSTALL.md # 【配置】OpenCode 安装指引
│ └── plugins/ # 【核心基建】插件运行时代码
│ └── superpowers.js # 【核心基建】OpenCode 插件主入口（技能加载与注册）
├── .github/ # 【配置】GitHub 社区与 CI 配置
│ ├── ISSUE_TEMPLATE/ # 【配置】Issue 提交模板
│ └── PULL_REQUEST_TEMPLATE.md # 【配置】PR 提交模板（强制完整填写）
├── scripts/ # 【工具集】维护与发布自动化脚本
│ ├── bump-version.sh # 【工具集】语义化版本号更新
│ └── sync-to-codex-plugin.sh # 【工具集】技能文件同步到 Codex 插件
├── assets/ # 【UI 视图】项目静态资源（logo等）
├── CLAUDE.md # 【配置】Claude Code 项目指引（贡献者行为守则）
├── GEMINI.md # 【配置】Gemini CLI 项目指引（文件引用模式）
├── CODE_OF_CONDUCT.md # 【配置】社区行为准则
├── RELEASE-NOTES.md # 【配置】发布版本说明
├── LICENSE # 【配置】MIT 开源许可证
├── README.md # 【配置】项目主页文档
├── package.json # 【配置】NPM 包配置（name: superpowers, v5.1.0）
├── pnpm-lock.yaml # 【配置】pnpm 包管理器依赖锁定
├── gemini-extension.json # 【配置】Gemini CLI 扩展注册清单
├── .version-bump.json # 【配置】版本号管理工具配置
├── .gitignore # 【配置】Git 忽略规则
└── .gitattributes # 【配置】Git 行尾等属性配置3. 模块依赖与调用关系
3.1 全局入口与核心路由
逻辑说明：整个系统的入口是
hooks/session-start脚本。当编码平台的 SessionStart 事件触发时，该脚本读取skills/using-superpowers/SKILL.md并将其注入到 Agent 上下文。Agent 获得技能使用能力后，每次收到用户请求都会先检查是否有适用技能（通过Skill工具），然后按技能定义的流程执行。对于 Claude Code 平台，入口还包括CLAUDE.md和GEMINI.md作为项目级指引。调用拓扑 (plainText)：
text
[平台 SessionStart 事件]
|
+--> hooks/session-start (bash 脚本)
|
+--> skills/using-superpowers/SKILL.md (注入上下文)
|
+-- (Agent 学习后自主调用) ---+
|
+--------------------------------------+
|
+--> [用户消息: "我要做 X"]
|
+--> using-superpowers (检查适用技能)
|
+-- 如果是"构建/创建"类任务:
| +--> brainstorming/SKILL.md
| +--> writing-plans/SKILL.md
| +--> subagent-driven-development/SKILL.md
| |
| +--> test-driven-development/SKILL.md
| +--> requesting-code-review/SKILL.md
| +--> finishing-a-development-branch/SKILL.md
|
+-- 如果是"修复 bug"类任务:
| +--> systematic-debugging/SKILL.md
| +--> test-driven-development/SKILL.md (修复后)
| +--> verification-before-completion/SKILL.md
|
+-- 如果是"审查代码"类任务:
| +--> requesting-code-review/SKILL.md
| +--> receiving-code-review/SKILL.md (响应端)
|
+-- 如需并行开发:
| +--> using-git-worktrees/SKILL.md
| +--> dispatching-parallel-agents/SKILL.md
|
+-- 元任务:
+--> writing-skills/SKILL.md (编写/修改技能时)3.2 核心业务实体与关联
实体定义：
- Skill：技能，一个 Markdown 文件定义的行为指令集，包含 frontmatter (name, description) 和正文内容
- Hook：钩子，定义在 JSON 中的事件触发器，在特定生命周期事件 (如 SessionStart) 时执行命令
- Session：会话，Agent 与用户的一次交互周期，SessionStart 时注入技能引导
- Plan：计划，writing-plans 技能输出的细粒度任务列表 (2-5 分钟/任务)
- Spec：规格，brainstorming 技能输出的设计文档
- Task：任务，计划中的单个执行单元，由子Agent独立完成
- SubAgent：子Agent，在隔离上下文中执行单一任务的独立 Agent 实例
- Harness：编码平台适配器，如 Claude Code, Codex, Cursor, OpenCode
实体引用拓扑 (plainText)：
text
[Harness] 1 ----> N [Hook]
|
[Hook] 1 -----> 1 [Session] (SessionStart 时触发)
|
[Session] 1 -----> 1 [using-superpowers Skill] (首次注入)
|
[using-superpowers] 1 ----> N [Skill] (教会Agent查找)
|
[Skill: brainstorming] 1 ----> 1 [Spec] (输出设计文档)
|
[Spec] 1 ----> 1 [Skill: writing-plans] (输入设计，输出任务列表)
|
[Skill: writing-plans] 1 ----> N [Task] (输出细粒度任务)
|
[Task] 1 ----> 1 [SubAgent] (每个任务分派给一个子Agent)
|
[SubAgent] 1 ----> 1 [Skill: test-driven-development] (内嵌)
[SubAgent] 1 ----> 1 [Skill: requesting-code-review] (两阶段审查)
[Skill: writing-skills] 1 ----> N [Skill] (元技能，产出新技能)
[Task] N ----> 1 [Skill: finishing-a-development-branch] (所有任务完成后)4. 核心模块详解
模块一：Hook 引导系统 (Hook Bootstrap System)
模块名称：Hook 引导系统
设计说明：这是整个 Superpowers 系统的"心脏起搏器"。
session-start脚本采用策略模式 (Strategy Pattern) —— 通过检测环境变量 (CURSOR_PLUGIN_ROOT,CLAUDE_PLUGIN_ROOT,COPILOT_CLI) 来判断当前运行的平台，并输出对应格式的 JSON。这种设计避免了为每个平台维护单独的引导脚本，实现了"一次编写，多平台运行"的目标。内部结构图 (plainText)：
text
+-----------------------------+
| hooks/hooks.json |
| hooks/hooks-cursor.json |
| - SessionStart 事件定义 |
| - matcher: startup|clear |
| - command: run-hook.cmd |
+------------+----------------+
|
v
+-----------------------------+
| hooks/session-start (bash) |
| +-------------------------+ |
| | Platform Detection | |
| | [CURSOR_PLUGIN_ROOT?] | |
| | [CLAUDE_PLUGIN_ROOT?] | |
| | [COPILOT_CLI?] | |
| +----------+--------------+ |
| | |
| +--------v-----------+ |
| | JSON Format Router | |
| | - Cursor: | |
| | additional_context| |
| | - Claude Code: | |
| | hookSpecificOutput| |
| | - Others (SDK std): | |
| | additionalContext | |
| +--------+------------+ |
| | |
| +--------v------------+ |
| | Content Injection | |
| | - 读取 SKILL.md | |
| | - JSON 转义 | |
| | - 嵌入 <IMPORTANT> | |
| +----------------------+ |
+-----------------------------+模块二：using-superpowers 引导技能
模块名称：using-superpowers 技能 (系统自举)
设计说明：这是唯一在 SessionStart 时强制注入的技能。它的职责不是执行任何业务逻辑，而是"教会 Agent 如何使用技能系统"。通过流程图 (DOT graph)、Red Flags 表格、技能优先级规则等内容，塑造 Agent 的行为模式。设计上采用"教导而非编程"的范式 —— 不是通过 API 强制调用，而是通过上下文说服 Agent 主动使用技能。
内部结构图 (plainText)：
text
+------------------------------------------------------+
| using-superpowers/SKILL.md |
| |
| +--------------------------------------------------+ |
| | <SUBAGENT-STOP> Gate | |
| | 子Agent不应加载此技能，防止嵌套注入 | |
| +--------------------------------------------------+ |
| |
| +--------------------------------------------------+ |
| | 行为强制层 (Behavior Enforcement) | |
| | - <EXTREMELY-IMPORTANT> 标签 | |
| | - "Even 1% chance" 规则 | |
| | - "Not negotiable, not optional" 声明 | |
| +-----------------------+--------------------------+ |
| | |
| +-----------------------v--------------------------+ |
| | 指令优先级 (Instruction Priority) | |
| | 1. 用户显式指令 (最高) | |
| | 2. Superpowers 技能 | |
| | 3. 默认系统提示 (最低) | |
| +-----------------------+--------------------------+ |
| | |
| +-----------------------v--------------------------+ |
| | 技能引擎 (Skill Engine - DOT graph) | |
| | - UserMessage → CheckSkills → InvokeSkill | |
| | - EnterPlanMode → 检查是否 brainstormed | |
| | - SkillFound → CreateTodo → FollowSkill | |
| +-----------------------+--------------------------+ |
| | |
| +-----------------------v--------------------------+ |
| | Red Flags 表格 (13 种常见借口) | |
| | "This is just a simple question" → Questions | |
| | are tasks. Check for skills. | |
| | ... (共 12 条反制规则) | |
| +-----------------------+--------------------------+ |
| | |
| +-----------------------v--------------------------+ |
| | 跨平台适配 | |
| | - Claude Code: Skill 工具 | |
| | - Copilot CLI: skill 工具 | |
| | - Gemini CLI: activate_skill 工具 | |
| | - 工具映射参考: references/*.md | |
| +--------------------------------------------------+ |
+------------------------------------------------------+模块三：brainstorming 头脑风暴技能
模块名称：brainstorming - 从模糊需求到明确设计
设计说明：这是 Superpowers 工作流的第一道"质量门"。通过
<HARD-GATE>标签阻止 Agent 在设计获批前编写任何代码。采用 Socratic 方法 (苏格拉底式提问) —— Agent 每次只问一个问题，逐步澄清需求。包含可视化伴侣 (Visual Companion) 功能，通过 WebSocket 服务器在浏览器中实时渲染设计概念。内部结构图 (plainText)：
text
+------------------------------------------------------+
| brainstorming/SKILL.md |
| |
| +--------------------------------------------------+ |
| | <HARD-GATE> | |
| | 设计未获批 → 禁止任何实现动作 | |
| | 设计获批 → 只能调用 writing-plans | |
| +--------------------------------------------------+ |
| |
| +--------------------------------------------------+ |
| | 9 步工作流 | |
| | 1. 探索项目上下文 | |
| | 2. 提供可视化伴侣 (如涉及 UI) | |
| | 3. 澄清问题 (一次一个) | |
| | 4. 提出 2-3 种方案 + 推荐 | |
| | 5. 分段呈现设计 | |
| | 6. 写入设计文档 | |
| | 7. 规格自我审查 | |
| | 8. 用户审查规格 | |
| | 9. 转换到 writing-plans | |
| +--------------------------------------------------+ |
| |
| +--------------------------------------------------+ |
| | 可视化伴侣 | |
| | scripts/server.cjs (WebSocket 零依赖服务器) | |
| | scripts/start-server.sh (启动脚本) | |
| | scripts/stop-server.sh (停止脚本) | |
| | scripts/helper.js (浏览器辅助) | |
| | scripts/frame-template.html (UI 框架) | |
| +--------------------------------------------------+ |
+------------------------------------------------------+模块四：subagent-driven-development 子Agent驱动开发
模块名称：subagent-driven-development - 隔离上下文的任务执行
设计说明：采用"每个任务一个子Agent"的策略模式。每个子Agent获得精确裁剪的上下文（不继承父会话的状态），执行单一任务后经两阶段审查（规格合规 → 代码质量）。三个提示词文件 (implementer-prompt, spec-reviewer-prompt, code-quality-reviewer-prompt) 分别定义了子Agent的角色边界。
内部结构图 (plainText)：
text
+------------------------------------------------------+
| subagent-driven-development/SKILL.md |
| |
| +-------------------+ +---------------------------+ |
| | implementer- | | spec-reviewer- | |
| | prompt.md | | prompt.md | |
| | - 接收任务规格 | | - 审查代码是否匹配规格 | |
| | - 实现代码 | | - 检查是否遗漏需求 | |
| | - 编写测试 | | - 关注完整性和正确性 | |
| | - 提交 commit | +---------------------------+ |
| +--------+----------+ |
| | +---------------------------+ |
| | | code-quality-reviewer- | |
| | | prompt.md | |
| | | - 审查代码质量 | |
| | | - DRY/YAGNI/可读性 | |
| | | - 性能/安全性 | |
| +----------->+---------------------------+ |
| |
| +--------------------------------------------------+ |
| | 每个任务的循环: | |
| | 1. 分派实现者子Agent | |
| | 2. 子Agent实现 + 自我审查 | |
| | 3. 分派规格审查者子Agent | |
| | 4. 修复规格差异 → 重回第 3 步 | |
| | 5. 分派代码质量审查者子Agent | |
| | 6. 修复质量问题 → 重回第 5 步 | |
| | 7. 标记任务完成 | |
| +--------------------------------------------------+ |
| |
| +--------------------------------------------------+ |
| | 持续执行原则: | |
| | - 不在任务间暂停询问用户 | |
| | - 仅在 BLOCKED/模糊/全部完成时停止 | |
| | - 避免 "Should I continue?" 提示 | |
| +--------------------------------------------------+ |
+------------------------------------------------------+模块五：test-driven-development TDD 技能
模块名称：test-driven-development - RED-GREEN-REFACTOR 循环
设计说明：定义严格的 TDD 纪律。包含"铁律" (THE IRON LAW) —— 没有失败测试就没有产品代码。如果 Agent 写了代码再补测试，必须删除代码重来。包含测试反模式参考文档 (testing-anti-patterns.md) 作为补充材料。
内部结构图 (plainText)：
text
+------------------------------------------------------+
| test-driven-development/SKILL.md |
| |
| +--------------------------------------------------+ |
| | THE IRON LAW | |
| | NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST | |
| +--------------------------------------------------+ |
| |
| +--------------------------------------------------+ |
| | RED-GREEN-REFACTOR 循环: | |
| | | |
| | [RED] 编写失败测试 | |
| | → [VERIFY] 确认测试因正确原因失败 | |
| | → [GREEN] 编写最小代码使测试通过 | |
| | → [VERIFY] 确认所有测试通过 | |
| | → [REFACTOR] 清理代码 | |
| | → [COMMIT] | |
| | → [NEXT] 下一个测试 | |
| +--------------------------------------------------+ |
| |
| +--------------------------------------------------+ |
| | 违规惩罚: | |
| | - 先写代码 → 删除 → 从测试开始 | |
| | - 不要保留作 "参考" | |
| | - 不要 "改编" | |
| | - 删除意味着删除 | |
| +--------------------------------------------------+ |
| |
| +--------------------------------------------------+ |
| | testing-anti-patterns.md | |
| | - 常见测试错误清单 | |
| | - Mock 过度使用 | |
| | - 测试实现细节而非行为 | |
| +--------------------------------------------------+ |
+------------------------------------------------------+5. 关键数据流程
场景一：完整开发工作流 (从需求到合并)
场景说明：用户向 Agent 提出一个新的开发需求 (如 "帮我做一个 React Todo List")，Agent 从 SessionStart 开始，经历完整的 brainstorming → writing-plans → subagent-driven-dev → TDD → code-review → finishing 流程。
流转时序图 (Mermaid)：
场景二：Bug 修复调试流程
场景说明：用户报告一个 bug，Agent 触发 systematic-debugging 技能，经过 4 阶段根因分析 → TDD 修复 → 验证的完整流程。
流转时序图 (Mermaid)：
6. 接口与契约规范
6.1 核心内部模块契约 (TypeScript)
typescript
/**
* Skill 元数据 — 定义技能的基本信息
* 来源：每个 SKILL.md 的 YAML frontmatter
*/
export interface SkillMetadata {
/** 技能唯一标识（用于 Skill 工具调用） */
name: string;
/** 技能描述（用于匹配用户意图） */
description: string;
}
/**
* Skill 主体 — 完整的技能定义
*/
export interface Skill {
/** YAML frontmatter 提取的元数据 */
metadata: SkillMetadata;
/** Markdown 正文（行为指令、流程图、检查清单等） */
body: string;
}
/**
* Hook 配置 — 定义钩子触发规则
* 来源：hooks/hooks.json, hooks/hooks-cursor.json
*/
export interface HookConfig {
hooks: {
[eventName: string]: HookEvent[];
};
}
export interface HookEvent {
/** 匹配触发条件（如 "startup|clear|compact"） */
matcher: string;
/** 事件触发时执行的操作列表 */
hooks: HookAction[];
}
export interface HookAction {
/** 操作类型（当前仅支持 "command"） */
type: 'command';
/** 要执行的命令（支持环境变量替换如 ${CLAUDE_PLUGIN_ROOT}） */
command: string;
/** 是否异步执行 */
async: boolean;
}
/**
* SessionStart 输出 — Hook 脚本返回的 JSON
* 多平台适配：通过环境变量判断使用哪种格式
*/
export type SessionStartOutput =
| ClaudeCodeSessionStartOutput
| CursorSessionStartOutput
| StandardSessionStartOutput;
export interface ClaudeCodeSessionStartOutput {
hookSpecificOutput: {
hookEventName: 'SessionStart';
/** 注入到 Agent 上下文的额外内容 */
additionalContext: string;
};
}
export interface CursorSessionStartOutput {
/** Cursor 使用 snake_case */
additional_context: string;
}
export interface StandardSessionStartOutput {
/** Copilot CLI 等平台的 SDK 标准格式 */
additionalContext: string;
}
/**
* 计划 — writing-plans 输出的数据结构
* 来源：writing-plans/SKILL.md 定义的模板
*/
export interface ImplementationPlan {
/** 计划标题 */
title: string;
/** 目标描述 */
goal: string;
/** 架构简述 */
architecture: string;
/** 技术栈 */
techStack: string[];
/** 细粒度任务列表 */
tasks: PlanTask[];
/** 关联的设计文档路径 */
specPath: string;
}
export interface PlanTask {
/** 任务序号 */
id: number;
/** 任务描述 (2-5 分钟可完成) */
description: string;
/** 涉及的文件路径 */
filePaths: string[];
/** 验证步骤 */
verification: string[];
/** 状态 */
status: 'pending' | 'in_progress' | 'completed';
}
/**
* 设计规格 — brainstorming 输出的数据结构
*/
export interface DesignSpec {
/** 文档标题 */
title: string;
/** 创建日期 */
date: string;
/** 问题陈述 */
problemStatement: string;
/** 选定的方案 */
selectedApproach: string;
/** 备选方案及其权衡 */
alternatives: Alternative[];
/** 设计详情 */
designDetails: DesignSection[];
}
export interface Alternative {
name: string;
pros: string[];
cons: string[];
/** 是否被推荐 */
recommended: boolean;
}
export interface DesignSection {
title: string;
content: string;
}6.2 技能间调用契约
typescript
/**
* 技能间转换规则
* 定义了技能之间的合法转换路径
*/
export const SKILL_TRANSITIONS: Record<string, string[]> = {
'using-superpowers': [
'brainstorming',
'systematic-debugging',
'requesting-code-review',
'using-git-worktrees',
'writing-skills'
],
'brainstorming': [
'writing-plans' // 唯一合法出口
],
'writing-plans': [
'subagent-driven-development',
'executing-plans'
],
'subagent-driven-development': [
'finishing-a-development-branch' // 所有任务完成后
],
'executing-plans': [
'finishing-a-development-branch'
],
'systematic-debugging': [
'test-driven-development',
'verification-before-completion'
],
'test-driven-development': [
'requesting-code-review'
]
};7. 快速开始
7.1 环境要求
- 支持的编码平台之一：Claude Code, Codex CLI, Codex App, Cursor, Gemini CLI, OpenCode, Factory Droid
- Git
- Bash (Unix) 或 Windows (通过 run-hook.cmd)
7.2 安装
Claude Code:
bash
/plugin install superpowers@claude-plugins-officialCodex CLI:
bash
/plugins → 搜索 "superpowers" → Install PluginCursor:
text
/add-plugin superpowersGemini CLI:
bash
gemini extensions install https://github.com/obra/superpowers7.3 典型工作流
- 在编码平台中启动会话 → 技能自动激活
- 描述要做的事情 → brainstorming 自动触发
- 回答澄清问题 → 批准设计
- writing-plans 生成任务清单 → 批准执行
- subagent-driven-development 自动执行 → 两阶段审查
- 所有任务完成 → finishing 呈现合并选项