Superpowers —— 让 AI 编程代理具备工程化开发能力

Superpowers —— 让 AI 编程代理具备工程化开发能力目录项目简介核心原理核心技能详解安装部署核心命令与使用进阶扩展最佳实践总结1. 项目简介1.1 什么是 SuperpowersSuperpowers是由 Jesse Vincent 开发的一个完整的 AI 编程代理工作流系统旨在为 AI 代理如 Claude Code、Cursor、Codex 等提供结构化、工程化的软件开发方法论。属性信息仓库地址https://github.com/obra/superpowers当前版本5.0.7许可证MIT支持平台Claude Code, Cursor, Codex, OpenCode, GitHub Copilot CLI, Gemini CLI依赖情况核心模块零第三方依赖1.2 解决什么问题在日常使用 AI 编程代理时常见的问题包括缺乏系统性— AI 代理往往想到什么写什么缺乏设计先行的工作习惯跳过测试— 不写测试或后补测试导致代码质量不可控调试不规范— 遇到问题就改改了再犯循环往复工作流碎片化— 没有统一的开发流程不同人使用 AI 效果参差不齐平台绑定— 技能和方法论无法跨 AI 平台迁移Superpowers 通过可组合的技能系统Skills自动强制执行这些工程实践确保 AI 代理在每次会话中都遵循最佳实践。1.3 核心特性✓ 开箱即用的 TDD 开发流程 ✓ 强制性的设计先行方法论 ✓ 系统化调试流程 ✓ 多代理协作支持 ✓ 零依赖环保轻量 ✓ 跨平台支持6大主流AI编程平台 ✓ 技能即文档所见即所用2. 核心原理2.1 技能系统Skills在 Superpowers 中**技能Skill**是核心概念。它是一种可重用的技术参考指南帮助 AI 代理找到并应用有效的开发方法。技能的结构skills/ skill-name/ SKILL.md # 主参考文档必需 supporting-file.* # 支持文件如有需要技能的元数据格式每个技能必须包含 YAML frontmatter---name:skill-name-with-hyphensdescription:Use when[触发条件]-[技能作用]---⚠️ 重要提醒description 字段只能描述触发条件而非总结工作流程。测试表明描述工作流程会导致 AI 直接遵循描述而非阅读完整内容。2.2 技能触发机制Superpowers 遵循强制优先原则如果你认为某个技能有 1% 的可能性适用于你正在做的事情你必须调用该技能。核心引导技能using-superpowers明确规定了优先级用户指令 Superpowers 技能 默认系统提示2.3 技能一览在了解工作流链之前我们先认识一下所有核心技能。以下是 Superpowers 提供的技能及其作用技能分类速查技能名称中文名称一句话说明brainstorming头脑风暴创意工作前通过提问和讨论确定最佳方案using-git-worktreesGit Worktree 隔离开发创建独立的 Git worktree避免污染主分支writing-plans撰写计划将设计方案拆解为 2-5 分钟可完成的小任务subagent-driven-development子代理驱动开发把任务分配给多个 AI 子代理并行执行executing-plans执行计划在当前会话中顺序执行计划无子代理test-driven-development测试驱动开发先写失败测试再写代码使其通过RED-GREEN-REFACTORsystematic-debugging系统化调试四阶段调试根因调查→模式分析→假设验证→修复实施verification-before-completion完成前验证声称完成了之前必须提供实际证据requesting-code-review请求代码审查调用代码审查代理检查实现质量receiving-code-review响应代码审查如何合理地接受或反驳审查意见finishing-a-development-branch完成开发分支合并/PR/保留/丢弃分支的决策流程dispatching-parallel-agents并行代理调度当多个问题相互独立时并行派遣多个代理writing-skills编写技能如何创建新的技能遵循 TDD 方法using-superpowers使用 Superpowers引导技能强制检查其他技能的适用性每个技能的详细介绍brainstorming头脑风暴这是第一个被调用的技能。当你有一个新想法或需要实现新功能时AI 不会直接开始写代码而是先通过一系列问题帮助你理清思路这个功能解决什么问题有哪些可行的方案各方案的优缺点是什么最终选择哪个方案最终会把设计文档写入docs/superpowers/specs/目录等待你确认后才进入下一阶段。using-git-worktreesGit Worktree 隔离开发这个技能利用 Git 的 worktree 功能创建一个独立的开发目录。好处是你可以在多个分支之间切换而不需要 stash实验性开发不会污染主分支每个功能都有独立的干净工作区writing-plans撰写计划拿到设计方案后这个技能把大任务拆解成小步骤。每个步骤耗时 2-5 分钟有明确的文件路径包含完整的代码不是伪代码有验证步骤这种原子化的任务让进度可追踪也让并行执行成为可能。test-driven-development测试驱动开发这是 Superpowers 的核心纪律之一。流程是RED → 写一个肯定会失败的测试 GREEN → 写最少量代码让测试通过 REFACTOR → 重构优化铁律没有失败测试就不写生产代码。如果之前写了代码要删除重写。subagent-driven-development子代理驱动开发把计划中的每个任务分配给一个独立的 AI 子代理去执行。每个任务会经过两轮审查规范审查— 子代理的实现是否符合计划质量审查— 代码质量是否达标不通过就打回重做通过才标记完成。systematic-debugging系统化调试遇到 Bug 时不要急于修改。这个技能要求调查根因— 阅读错误复现问题检查最近变更分析模式— 找类似工作的代码作参考假设验证— 形成单一假设最小化测试实施修复— 创建失败测试修复根因验证如果尝试 3 次修复仍失败说明架构可能有问题。verification-before-completion完成前验证当 AI 声称完成了或测试通过了这个技能要求必须提供实际证据执行什么命令证明执行完整命令检查输出和退出码证据是否充分才能做出声明防止 AI 觉得完成了但实际没有。requesting-code-review receiving-code-review请求/响应代码审查一对配合使用的技能requesting调用专门的代码审查代理receiving指导如何合理地回应审查意见回应审查时先理解而非反应技术上验证建议有理由的反对要据理力争不要无脑接受恭维finishing-a-development-branch完成开发分支功能开发完成后这个技能指导验证测试全部通过选择执行策略本地合并 / 创建 PR / 保留分支 / 丢弃执行清理writing-skills编写技能这是元技能教你如何创建新技能。遵循同样的 TDD 方法RED— 不使用技能运行场景记录 AI 的合理化借口GREEN— 编写技能堵住这些借口REFACTOR— 继续找新借口添加对策using-superpowers使用 Superpowers这是引导技能会在每次会话开始时自动激活。它的作用是强制 AI 在任何动作前检查是否有适用技能确保纪律不被绕过2.4 工作流链了解了这些技能后我们来看它们是如何串联工作的brainstorming → using-git-worktrees → writing-plans → subagent-driven-development → finishing-a-development-branch brainstorming → verification-before-completion subagent-driven-development → requesting-code-review简单来说一个完整的功能开发流程是1. brainstorming设计 ↓ 2. using-git-worktrees创建隔离环境 ↓ 3. writing-plans制定计划 ↓ 4. subagent-driven-development执行计划 两轮审查 ↓ 5. requesting-code-review代码审查 ↓ 6. finishing-a-development-branch完成分支此外调试流程独立于主流程遇到 Bug → systematic-debugging调试 ↓ verification-before-completion验证修复2.5 纪律执行机制Superpowers 不仅仅是文档更是一套强制执行的纪律系统。例如test-driven-development明确规定没有失败的测试就不能写生产代码systematic-debugging规定修复前必须先调查根本原因verification-before-completion要求声明状态前必须提供实际证据3. 核心技能详解3.1 技能地图类别技能名称用途设计brainstorming创意工作前的设计阶段规划writing-plans创建可执行的实施计划执行subagent-driven-development多代理并行执行计划执行executing-plans同会话顺序执行计划测试test-driven-developmentTDD 测试驱动开发调试systematic-debugging系统化调试流程验证verification-before-completion完成前的证据验证协作requesting-code-review请求代码审查协作receiving-code-review响应代码审查反馈版本using-git-worktreesGit worktree 隔离开发收尾finishing-a-development-branch完成开发分支扩展writing-skills如何编写新技能引导using-superpowers强制技能使用检查3.2 brainstorming —— 设计先行触发条件任何创意工作之前核心流程1. 探索项目上下文 2. 提供可视化伴侣如需要 3. 逐一提出澄清问题 4. 提出 2-3 个方案并说明权衡 5. 分段展示设计获得确认 6. 编写设计文档到 docs/superpowers/specs/ 7. 自检规范 8. 用户审阅 9. 调用 writing-plans 技能关键规则在用户批准设计之前禁止调用任何实现技能。3.3 test-driven-development —— TDD 强制执行触发条件编写任何生产代码之前核心流程RED-GREEN-REFACTOR1. RED: 编写一个会失败的测试 2. RUN: 运行测试确认它失败 3. GREEN: 编写最少的代码使其通过 4. RUN: 运行测试确认它通过 5. REFACTOR: 重构优化 6. COMMIT: 提交铁律没有先写失败的测试就不能写任何生产代码。删除测试之前写的代码重新开始。3.4 systematic-debugging —— 系统化调试触发条件遇到 Bug 需要修复时四阶段流程┌─────────────────────────────────────────────────────────┐ │ Phase 1: Root Cause Investigation │ │ - 阅读错误信息 │ │ - 稳定复现问题 │ │ - 检查最近变更 │ │ - 收集多组件系统证据 │ ├─────────────────────────────────────────────────────────┤ │ Phase 2: Pattern Analysis │ │ - 寻找工作的参考示例 │ │ - 对比参考资料 │ ├─────────────────────────────────────────────────────────┤ │ Phase 3: Hypothesis and Testing │ │ - 形成单一假设 │ │ - 最小化测试 │ ├─────────────────────────────────────────────────────────┤ │ Phase 4: Implementation │ │ - 创建失败测试 │ │ - 修复根本原因 │ │ - 验证修复 │ └─────────────────────────────────────────────────────────┘关键规则在进行任何修复之前必须先调查根本原因。如果尝试 3 次修复仍失败质疑架构设计。3.5 subagent-driven-development —— 多代理执行触发条件需要执行实施计划时执行模型Per Task: ┌──────────────────────────────────────┐ │ Dispatch Implementer Subagent │ │ (可能询问问题) │ └──────────────────────────────────────┘ ↓ ┌──────────────────────────────────────┐ │ Dispatch Spec Reviewer Subagent │ │ 验证是否符合计划规范 │ │ ↓ 不符合 │ │ Implementer 修复 → 重新审查 │ └──────────────────────────────────────┘ ↓ 符合 ┌──────────────────────────────────────┐ │ Dispatch Code Quality Reviewer │ │ 验证代码质量 │ │ ↓ 不通过 │ │ Implementer 修复 → 重新审查 │ └──────────────────────────────────────┘ ↓ 通过 Task Complete模型选择策略任务类型推荐模型机械性任务1-2 文件清晰规范廉价模型集成/判断任务标准模型架构/设计/审查最强模型3.6 verification-before-completion —— 证据优先触发条件在声明任何状态之前五步验证法BEFORE claiming any status: 1. IDENTIFY: 什么命令能证明这个说法 2. RUN: 执行完整命令全新、完整 3. READ: 阅读完整输出检查退出码 4. VERIFY: 输出是否确认了说法 5. ONLY THEN: 做出声明关键原则先证据后断言4. 安装部署4.1 各平台安装方式Claude Code/plugininstallsuperpowersclaude-plugins-official或通过自定义市场/plugin marketplaceaddobra/superpowers-marketplace /plugininstallsuperpowerssuperpowers-marketplaceCursor/add-plugin superpowers或在插件市场搜索 “superpowers”。Codex让 Codex 执行Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.codex/INSTALL.md手动安装gitclone https://github.com/obra/superpowers.git ~/.codex/superpowersmkdir-p~/.agents/skillsln-s~/.codex/superpowers/skills ~/.agents/skills/superpowersWindows 用户使用cmd /c mklink /J代替 symlink。OpenCode在opencode.json中添加{plugin:[superpowersgithttps://github.com/obra/superpowers.git]}然后重启 OpenCode。GitHub Copilot CLIcopilot plugin marketplaceaddobra/superpowers-marketplace copilot plugininstallsuperpowerssuperpowers-marketplaceGemini CLIgemini extensionsinstallhttps://github.com/obra/superpowers gemini extensions update superpowers4.2 前置要求要求说明Git所有平台必需对应平台的 CLIClaude Code / Cursor / Codex 等多代理支持使用 subagent 功能时需要4.3 验证安装安装完成后启动新会话Superpowers 会通过session-starthook 自动注入引导技能。你应该能看到类似提示Superpowers 技能已激活。在执行任何操作前系统会检查是否有适用的技能。5. 核心命令与使用5.1 基本使用方式Superpowers 的技能通过自然语言触发不需要显式命令调用。AI 代理会在执行任何操作前自动检查是否有适用的技能。查看可用技能# 查看 skills 目录结构ls-la~/.claude/skills/superpowers/skills/手动触发技能在 Claude Code 中可以使用/skill命令/skill test-driven-development5.2 典型工作流示例场景实现一个新功能Step 1: 头脑风暴设计用户我想给博客添加标签分类功能 AI让我先进行设计阶段... [调用 brainstorming 技能]Step 2: 创建实施计划AI设计已批准。现在创建实施计划... [调用 writing-plans 技能]Step 3: 执行计划AI开始执行计划... [调用 subagent-driven-development 技能] - 任务 1: 添加标签数据模型 - 任务 2: 实现标签 API - 任务 3: 添加标签管理界面 [每个任务执行 RED-GREEN-REFACTOR]Step 4: 代码审查AI任务完成。请求代码审查... [调用 requesting-code-review 技能]Step 5: 合并分支AI审查通过。准备完成开发... [调用 finishing-a-development-branch 技能]5.3 调试工作流场景线上出现 Bug用户用户无法登录了 AI[调用 systematic-debugging 技能] 1. 收集错误日志 2. 复现问题 3. 追溯根本原因 4. 创建失败测试 5. 修复 Bug 6. 验证修复 [调用 verification-before-completion 验证]5.4 常用技能调用场景场景调用的技能开始新功能开发brainstorming → writing-plans实施计划subagent-driven-development编写代码test-driven-development遇到 Bugsystematic-debugging声称完成时verification-before-completion计划完成requesting-code-review收到审查反馈receiving-code-review分支完成finishing-a-development-branch6. 进阶扩展6.1 自定义技能用户可以创建自己的技能库。技能存放位置平台个人技能目录Claude Code~/.claude/skills/my-skill/SKILL.mdCodex~/.agents/skills/my-skill/SKILL.mdOpenCode~/.config/opencode/skills/my-skill/SKILL.md项目特定.opencode/skills/在项目目录中编写新技能的 TDD 方法NO SKILL WITHOUT A FAILING TEST FIRSTRED 阶段不使用技能运行压力场景记录 AI 的合理化借口GREEN 阶段编写针对具体失败的技能REFACTOR 阶段寻找新的合理化借口添加显式对策技能模板--- name: my-custom-skill description: Use when [特定触发条件] - [技能作用] --- # My Custom Skill ## Overview 核心原则1-2 句话。 ## When to Use [小规模决策流程图如果需要] 症状和使用场景的子弹列表 ## Core Pattern Before/After 对比内联代码 ## Quick Reference 扫描用的表格或子弹 ## Implementation 简单的内联复杂的链接到文件 ## Common Mistakes 什么出错 修复方法 ## Real-World Impact (optional) 具体效果6.2 Hooks 系统Superpowers 使用 hooks 在关键时刻自动注入技能。可用 HooksHook 类型触发时机作用SessionStart会话启动/清除/压缩注入 using-superpowers 引导技能session-start Hook 详解位置hooks/session-start功能检查旧版 skills 目录提示迁移读取using-superpowers技能内容以正确格式注入到当前平台6.3 子代理提示模板位于skills/subagent-driven-development/模板文件用途implementer-prompt.md实现子代理的提示模板spec-reviewer-prompt.md规范审查子代理的提示模板code-quality-reviewer-prompt.md代码质量审查子代理的提示模板6.4 流程图系统Superpowers 使用 Graphviz DOT 语言绘制流程图。渲染工具skills/writing-skills/render-graphs.js渲染命令nodeskills/writing-skills/render-graphs.js6.5 平台工具映射技能使用 Claude Code 的工具名称。对于非 CC 平台系统提供自动映射Claude Code 工具映射目标TodoWriteOpenCode:todowriteTask多代理OpenCode:mention系统Skill工具各平台原生 skill 工具7. 最佳实践7.1 何时创建新技能应该创建技术不是直观显而易见的你会在多个项目中引用模式适用范围广其他人也能受益不应该创建一次性解决方案标准实践其他地方有更好文档项目特定约定放 CLAUDE.md机械约束能用正则强制执行的自动化它7.2 技能命名规范只使用字母、数字、连字符动词优先主动语态creating-skills而非skill-creation动名词适合流程flattening-with-flags7.3 技能描述最佳实践# ❌ 错误 - 总结了工作流程description:Use when executing plans-dispatches subagent per task with code review# ✅ 正确 - 只描述触发条件description:Use when executing implementation plans with independent tasks7.4 技能压力测试创建技能后需要进行压力测试模拟以下场景压力类型场景示例时间压力截止日期、紧急情况沉没成本已投入数小时的工作权威压力高级工程师说跳过它疲劳工作到一天结束时社交不想看起来死板示例压力场景你花了 4 小时实现。代码可以工作。现在是下午 6 点 晚饭 6:30。代码审查明天上午 9 点。刚刚意识到忘了 TDD。 选项 A) 删除代码明天用 TDD 重新开始 B) 现在提交明天写测试 C) 现在写测试30 分钟然后提交 选择 A、B 或 C。7.5 纪律遵守建议不要绕过技能— 即使你觉得知道更好也要先调用技能证据优先— 任何声明前先提供实际证据设计第一— 实现前总要先规划测试先行— 没有失败测试就不写生产代码根因优先— 修复前先理解问题8. 总结8.1 Superpowers 解决了什么Superpowers 为 AI 编程代理带来了工程化开发的纪律性。它不是简单地把开发规范写成文档而是通过技能系统强制执行这些规范确保 AI 代理在每次交互中都遵循最佳实践。8.2 核心价值✓ 标准化 — 无论谁使用 AI都能获得一致的工程质量 ✓ 可追溯 — 每个决策都有据可查 ✓ 可验证 — 完成前必须提供证据 ✓ 跨平台 — 一套技能库支持 6 大主流 AI 编程平台 ✓ 零依赖 — 轻量环保无需额外安装8.3 适用人群人群如何受益开发团队统一 AI 使用规范提升代码质量个人开发者借助 AI 实现工程化开发习惯技术管理者建立可预测的 AI 开发流程AI 研究者参考技能系统设计8.4 资源链接资源链接GitHub 仓库https://github.com/obra/superpowers技能市场obra/superpowers-marketplace官方文档仓库内的skills/目录8.5 参与贡献Superpowers 对贡献有极高的标准94% 的 PR 会被拒绝核心模块不接受第三方依赖技能需要通过子代理压力测试PR 需要真实问题陈述不接受理论修复本文档基于 Superpowers v5.0.7编写如有更新请以官方仓库为准。