Superpowers：开源AI编码代理工作流框架，强制工程规范的技能化开发体系

一、Superpowers是什么

Superpowers是一款专为AI编码代理打造的完整软件开发工作流增强框架，其核心并非提供新的代码生成算法或模型能力，而是将人类软件工程中的经典最佳实践转化为AI可理解、可执行的强制性标准化协议，通过模块化的“技能（Skills）”体系，让Claude Code、Codex、OpenCode等AI编码工具摆脱“凭感觉写代码”的弊端，严格遵循规范的开发流程完成软件构建。

简单来说，如果把AI编码代理比作一个具备编程能力的开发者，那么Superpowers就是这个开发者的“工程化行为准则”和“自动化工作助手”：它会强制AI在编码前做需求澄清、写设计文档，编码中遵循测试驱动开发，编码后完成严格的代码评审和版本管理，从根本上解决当前AI编程存在的需求理解模糊、跳过测试环节、代码可维护性差、违反工程原则等问题。该项目面向依赖AI代理进行中大型或生产级项目开发的软件工程师、技术团队领导者，旨在让开发者既能享受AI带来的开发效率提升，又能保证产出代码的质量、规范性和工程价值，避免AI生成的代码成为难以维护的“技术债务”。

二、功能特色

Superpowers的核心功能围绕“强制工程规范”和“自动化开发流程”展开，通过可插拔的技能体系和闭环的开发流水线，让AI编码代理的行为从“无约束生成”转变为“标准化执行”，其核心功能特色可分为七大核心维度，同时具备跨平台、易扩展等附加优势，具体如下：

（一）需求深度澄清，拒绝模糊开发

Superpowers摒弃了AI编码代理直接响应开发指令的传统模式，通过brainstorming（头脑风暴）技能触发苏格拉底式多轮对话，针对开发者提出的模糊需求进行层层追问，比如“该功能的异常场景如何处理？”“API的调用权限如何设计？”等，将需求拆解到原子级别，最终形成清晰的分段设计文档并保存至指定目录，确保AI与开发者的开发目标完全一致，从源头避免因需求理解偏差导致的代码返工。

（二）隔离式开发环境，保障版本安全

通过using-git-worktrees技能实现Git工作树的自动化管理，在需求设计确认后，AI会自动创建隔离的工作区和新的开发分支，同时验证主分支的干净测试基线，彻底避免开发过程中对主分支代码的污染，解决了传统AI编程中直接在主分支修改代码、易引发版本冲突的问题，让每一次开发任务都在独立的“沙盒”环境中进行。

（三）精细化任务分解，实现原子化执行

借助writing-plans技能将宏观的开发目标拆解为2-5分钟可完成的原子任务，并为每个任务生成包含精确文件路径、完整代码实现要求、详细验证步骤的Markdown格式实施计划，甚至会给出时间估算。这种精细化的任务分解让AI的开发行为有明确的蓝图，避免出现“一次性生成大量无结构代码”的情况，也让开发者能够清晰把控AI的开发进度和内容。

（四）子代理驱动开发，分工提升专业性

通过subagent-driven-development技能实现分布式的子代理执行机制，主AI代理会将拆解后的原子任务分配给独立的子代理完成，不同子代理承担不同的开发职责，比如专门的编码子代理、测试子代理、审查子代理等。同时每个任务执行后会触发两阶段强制审查——规格合规性审查确保代码“不多做、不少做”，严格匹配设计要求；代码质量审查检查测试覆盖率、变量命名、边界条件处理等，只有两阶段审查全部通过，代码才能进入下一环节，从过程上保障代码质量。

（五）强制TDD开发，实现测试先行

将测试驱动开发（TDD）作为核心开发原则，通过test-driven-development技能严格强制执行“RED-GREEN-REFACTOR”循环：AI必须先编写失败的测试代码→验证测试失败→编写满足需求的最小化业务代码→验证测试通过→对代码进行重构优化，且会删除所有在测试前编写的无效代码。这种“测试即真理”的模式让AI生成的每一行代码都为了通过具体的测试用例而存在，确保代码100%覆盖需求，大幅提升代码的健壮性和可测试性。

（六）全流程代码评审，分级管控问题

在开发任务的各个节点嵌入自动化代码评审机制，通过requesting-code-review和receiving-code-review技能实现评审的触发和反馈处理，AI会按问题严重程度对评审发现的问题进行分级标记，其中关键问题会直接阻塞开发流程，必须修复后才能继续，一般问题则会记录并提醒优化，让代码评审不再是开发后的“可选环节”，而是贯穿开发全流程的“硬性管控点”。

（七）标准化分支收尾，简化版本集成

开发任务全部完成后，finishing-a-development-branch技能会自动触发分支收尾流程：AI先验证当前分支的所有测试用例是否全部通过，随后为开发者提供合并分支、创建PR、保留分支、丢弃分支等多种操作选项，开发者选择后，AI会自动完成对应的操作并清理隔离的工作树，标准化的分支收尾流程让AI开发的代码能够无缝集成到项目的主版本中，简化了开发者的版本管理工作。

（八）附加优势：跨平台、易扩展、轻量无依赖

1. 多平台原生适配：完美支持Claude Code、Codex、OpenCode三大主流AI编码代理，其中Claude Code可通过插件市场一键安装，Codex和OpenCode仅需执行简单脚本即可完成配置；

2. 技能体系易扩展：开发者可按照规范创建自定义技能，仅需在指定目录提交相关文件并继承核心模块，新技能即可被所有平台识别，满足不同项目的个性化开发需求；

3. 轻量无外部依赖：项目核心脚本零外部依赖，安装配置过程最快2分钟完成，首次运行会自动生成本地配置目录，无需复杂的环境搭建；

4. 配套工具集成：内置tmux实时监控功能，可一键打开4窗格的开发环境，同时所有技能均通过DOT流程图描述执行规范，避免AI“自由发挥”。

三、技术细节

Superpowers在技术架构上采用“共享核心模块+平台适配层+可插拔技能层”的三层设计，整体架构解耦性强、扩展性高，同时通过一系列独特的技术设计实现了“强制流程执行”和“代码质量管控”，其核心技术细节可分为架构设计、技能设计、核心机制、测试防护四个部分，其中核心技能与触发时机的对应关系如下表所示：

表1 Superpowers核心技能与触发时机、核心价值对应表

（一）三层核心架构设计

1. 共享核心模块（lib/skills-core.js）
   这是Superpowers的技术核心，采用JavaScript开发，提取了所有平台通用的核心逻辑，为多平台适配提供基础支撑，无需为不同平台重复开发相同功能。该模块的核心功能包括：解析技能文件的YAML前置元数据、递归发现目录中的SKILL.md技能文件、解析技能路径（支持个人技能覆盖核心技能）、检查Git仓库更新、剥离技能文件的前置元数据等，是整个技能体系的“运行引擎”。

2. 平台适配层
   为不同AI编码代理打造的专属适配层，充分结合各平台的原生特性，实现“无感集成”，无需修改核心模块即可适配不同平台：

• Claude Code：基于平台原生插件体系开发，可直接在插件市场安装使用；

• Codex：基于CLI脚本（.codex/superpowers-codex）适配，通过简单的指令即可引导配置；

• OpenCode：基于JavaScript/TypeScript插件（.opencode/plugin/superpowers.js）适配，支持平台的事件钩子和自定义工具API。

3. 可插拔技能层
   技能是Superpowers的最小功能单元，所有开发流程的管控均通过技能实现，技能层分为核心技能和个人技能：核心技能位于项目安装目录的skills/目录，覆盖开发全流程的基础能力；个人技能位于用户本地的~/.config/opencode/skills/目录，优先级高于核心技能，支持“影子覆盖”，即开发者可通过个人技能替换核心技能的逻辑，满足个性化需求。每个技能对应一个独立目录，内含SKILL.md文件，该文件通过YAML Frontmatter声明技能名称、描述等元数据，主体部分为AI需遵循的详细执行指令。

（二）技能的强制执行设计

Superpowers能实现“强制AI遵循开发流程”的关键，在于技能文件中的强制触发条件设计。在每个技能的SKILL.md文件中，都会明确写入类似“You MUST use this before any creative work”的强制指令，定义技能的触发场景和执行要求，AI编码代理在检测到对应的开发意图时，必须优先触发相关技能，而非直接执行编码操作。同时，所有技能均通过DOT流程图描述执行步骤，AI必须严格按照流程图的逻辑执行，拒绝任何“自由发挥”，从技术层面确保了开发流程的标准化执行。

（三）三大核心技术机制

1. 子代理双审机制
   子代理驱动开发中的核心质量管控机制，设置规格审查员和质量审查员两个独立的子代理角色：规格审查员会亲自读取代码，与设计文档逐一核对，确保代码的功能实现与需求完全一致，既没有遗漏功能，也没有增加不必要的功能（遵循YAGNI原则）；质量审查员则专注于代码本身的质量，检查测试覆盖率是否达标、变量和函数命名是否规范、边界条件和异常场景是否处理、是否存在代码重复（违反DRY原则）等问题，只有两个审查员均通过审核，代码才能进入下一环节。

2. 技能加载与解析机制
   由共享核心模块提供的技能管理机制，核心通过findSkillsInDir和resolveSkillPath两个函数实现：findSkillsInDir会递归扫描指定目录，自动发现所有包含SKILL.md的技能文件，并提取其元数据，实现技能的自动加载；resolveSkillPath会优先解析个人技能目录中的技能，若未找到则解析核心技能目录，实现个人技能对核心技能的灵活覆盖，让开发者的自定义配置更便捷。

3. 闭环反馈机制
   实现“零报错交付”的核心技术机制，在编码和测试过程中，Superpowers会实时捕获编译器的错误日志和测试结果，若发现代码报错或测试未通过，会自动将错误信息反馈给AI编码代理，引导AI进行代码修正，这个过程会在后台自动循环，直到所有测试用例通过、代码无报错为止，形成“编码-测试-反馈-修正”的闭环，确保最终交付的代码能够直接运行。

（四）四重测试防护体系

为了确保Superpowers自身的稳定性和技能的有效性，项目设计了四重测试防护体系，保障框架的可靠运行：

1. 技能触发测试：验证普通的“朴素提示”是否能成功激活对应的技能，确保技能的触发逻辑无问题；

2. Claude Code集成测试：通过无头运行claude -p的方式，测试技能在Claude Code平台的集成效果；

3. 跨平台兼容性测试：针对Codex、OpenCode等平台，分别测试技能的执行逻辑和适配效果，确保跨平台功能的一致性；

4. 端到端示例项目测试：提供Go + Svelte的真实代码库作为示例项目，CI（持续集成）会每日自动运行该项目的全流程开发测试，验证Superpowers在实际项目中的使用效果。

四、应用场景

Superpowers的核心价值是让AI编码代理能够胜任生产级的软件项目开发，其标准化的开发流程和严格的工程规范约束，使其适用于所有需要遵循软件工程最佳实践的AI辅助开发场景，尤其针对中大型项目、团队协作项目和生产环境项目，优势更为明显，具体核心应用场景如下：

（一）生产级功能模块开发

在企业级项目的生产环境开发中，对代码质量、可维护性和可测试性的要求极高，传统AI编码代理生成的代码往往难以满足要求。Superpowers可应用于生产级功能模块的开发，比如电商系统的订单模块、支付模块，管理系统的用户权限模块、数据统计模块等，通过强制TDD开发、自动化代码评审和隔离式开发环境，确保AI生成的代码符合企业的工程规范，能够直接集成到生产环境中，避免因代码质量问题引发生产事故。

（二）遗留系统修改与重构

遗留系统的修改和重构是软件开发中的难点，需要充分考虑代码的兼容性和可维护性，稍不注意就可能引入新的Bug。Superpowers可应用于遗留系统的代码修改和模块重构，通过brainstorming技能梳理重构需求，systematic-debugging技能进行根因分析，refactor技能在保持测试通过的前提下进行最小化重构，同时借助隔离式开发环境，避免修改过程中对遗留系统的正常功能造成影响，让AI成为遗留系统重构的高效助手。

（三）团队协作式AI开发

在多人团队协作的开发场景中，统一的开发流程和代码规范是保障协作效率的关键。Superpowers可为团队提供标准化的AI辅助开发流程，让团队内所有开发者使用的AI编码代理都遵循相同的需求梳理、编码、测试、评审流程，生成的代码风格和质量保持一致，同时通过Git工作树的自动化管理，让团队成员的AI开发任务互不干扰，大幅降低团队协作中的沟通成本和版本冲突问题。

（四）AI驱动的项目原型迭代

在项目原型的快速迭代中，开发者需要兼顾开发效率和原型的可扩展性，避免原型成为“一次性代码”。Superpowers可应用于AI驱动的项目原型开发，通过精细化的任务分解和自动化的测试流程，让AI快速生成符合工程规范的原型代码，同时由于原型代码遵循TDD开发原则，拥有完善的测试用例，后续开发者可基于原型代码轻松进行功能扩展和迭代，无需重新编写代码，提升原型迭代的效率。

（五）大型项目的分模块开发

对于大型软件项目，通常会采用分模块的开发模式，每个模块由专人负责，最终进行集成。Superpowers可应用于大型项目的AI辅助分模块开发，主AI代理可将整个项目拆解为多个独立的模块，每个模块再拆解为原子任务并分配给不同的子代理，通过子代理驱动开发实现模块的并行开发，同时通过统一的代码评审和测试标准，确保各个模块的代码质量和接口一致性，让AI能够高效参与大型项目的开发过程。

（六）AI编程的工程化培训

对于刚接触AI编程的开发者，往往难以掌握“如何让AI生成高质量的工程化代码”的方法，Superpowers也可作为AI编程的工程化培训工具。开发者通过使用Superpowers，能够直观地学习到软件工程中的TDD开发、Git工作流、代码评审等最佳实践，同时了解如何将模糊的需求拆解为可执行的开发任务，逐步建立工程化的编程思维，提升自身的AI编程能力。

五、使用方法

Superpowers的安装和使用高度适配不同AI编码代理的原生特性，整体上手门槛低，无需复杂的环境搭建，核心分为Claude Code、Codex、OpenCode三个平台的使用方法，其中Claude Code支持插件市场一键安装，Codex和OpenCode支持脚本自动配置，具体操作步骤如下：

（一）Claude Code 平台使用方法（插件化安装）

Claude Code是Superpowers适配最完善的平台，通过平台原生的插件市场即可完成安装，全程仅需3条命令，具体步骤：

1. 注册Superpowers插件市场：在Claude Code的会话中输入以下命令，完成插件市场的添加：

  /plugin marketplace add obra/superpowers-marketplace

2. 安装Superpowers插件：输入以下命令，从插件市场安装Superpowers核心插件：

  /plugin install superpowers@superpowers-marketplace

3. 验证安装结果：输入/help命令，若在命令列表中看到/superpowers:brainstorm、/superpowers:write-plan、/superpowers:execute-plan等Superpowers相关命令，说明安装成功；

4. 开始使用：直接输入/brainstorm命令，即可触发头脑风暴技能，开始基于Superpowers的AI开发流程。

（二）Codex 平台使用方法（脚本自动配置）

Codex平台通过远程脚本实现自动安装和配置，无需手动修改文件，具体步骤：

1. 执行安装脚本：在终端中输入以下命令，拉取并执行Codex专属的安装脚本：

  Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.codex/INSTALL.md

也可使用简化的一键安装命令：

  curl -fsSL https://raw.githubusercontent.com/obra/superpowers/main/install-codex.sh | bash

2. 初始化配置：首次运行会在当前Git仓库中自动生成.superpowers/本地配置目录，完成零配置初始化；

3. 开始使用：在Codex中提出开发需求，Superpowers会自动触发对应的技能，引导开发者完成全流程开发。

（三）OpenCode 平台使用方法（插件适配配置）

OpenCode平台基于JavaScript/TypeScript插件适配，通过远程指令完成配置，具体步骤：

1. 执行配置指令：向OpenCode发送以下指令，平台会自动获取并执行专属的安装配置文档：

  Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.opencode/INSTALL.md

2. 完成插件加载：OpenCode会自动下载并加载Superpowers插件，同时完成与平台事件钩子、自定义工具API的对接；

3. 开始使用：直接在OpenCode中输入开发需求，即可触发Superpowers的标准化开发流程。

（四）通用使用注意事项

1. Superpowers首次运行时会自动检测当前目录是否为Git仓库，若不是则会提示开发者初始化Git仓库，因为框架的所有开发流程均基于Git进行版本管理；

2. 使用过程中，开发者无需手动触发所有技能，Superpowers会根据开发阶段自动触发对应的技能，比如需求提出后自动触发brainstorming，设计确认后自动触发using-git-worktrees；

3. 若需要使用自定义技能，只需将编写好的技能目录放入~/.config/opencode/skills/目录，Superpowers会自动加载并优先执行；

4. 开发过程中，所有的设计文档、实施计划都会自动保存至项目的docs/plans/目录，开发者可随时查看和修改。

六、常见问题解答

Q1：Superpowers需要付费使用吗？

Superpowers是完全开源的项目，核心的工作流框架和技能体系基于开源协议免费使用，开发者无需支付任何费用。使用过程中仅需承担背后AI编码代理的API调用费用（如Claude Code、Codex的API费用），项目本身无任何收费项。同时项目也有潜在的Pro版SaaS服务（云端托管、高级上下文管理），采用订阅制，开发者可根据自身需求选择。

Q2：Superpowers支持哪些编程语言和项目类型？

Superpowers本身是跨编程语言的工作流框架，不限制具体的开发语言，支持Python、Java、Go、JavaScript、TypeScript等主流编程语言，同时适用于Web开发、后端开发、桌面应用开发等各类项目类型。框架的核心是管控开发流程，而非参与代码生成，因此只要AI编码代理支持的编程语言和项目类型，Superpowers均能适配。

Q3：使用Superpowers会降低AI编程的效率吗？

从表面上看，Superpowers增加了需求澄清、编写测试、代码评审等环节，会让前期开发的时间增加约20%，但从整体开发周期来看，其能将后期的Debug调试和代码返工时间减少90%以上，综合交付效率能提升2-3倍。同时自动化的流程管控让开发者从繁琐的手动操作中解放出来，大幅提升了整体的开发效率。

Q4：开发者可以自定义Superpowers的技能吗？

可以。Superpowers采用可插拔的技能体系，开发者可按照项目的开发规范编写自定义技能，仅需在技能目录中创建SKILL.md文件，声明元数据和执行指令，并继承lib/skills-core.js核心模块，即可被所有平台识别。同时支持个人技能覆盖核心技能，满足不同项目的个性化开发需求。

Q5：Superpowers可以在团队中部署和使用吗？

完全可以。Superpowers非常适合团队协作使用，团队可基于项目的团队规范，开发专属的团队技能库，让团队内所有开发者使用的AI编码代理都遵循统一的开发流程和代码规范。同时框架的隔离式开发环境和Git工作流管理，能有效避免团队协作中的版本冲突问题，提升团队的AI协作开发效率。

Q6：如果AI不遵循Superpowers的强制流程怎么办？

Superpowers在技能文件中通过明确的强制触发指令（如“You MUST use this”）约束AI的行为，同时所有技能的执行步骤通过DOT流程图描述，AI必须严格按照流程图执行。对于主流的AI编码代理（Claude Code、Codex、OpenCode），均能完美识别并遵循这些约束指令，若出现个别不遵循的情况，可通过更新Superpowers插件或技能文件解决。

Q7：Superpowers需要搭建本地环境吗？

不需要。Superpowers是轻量级的框架，核心脚本零外部依赖，无需搭建专门的本地环境。Claude Code平台为插件化运行，Codex和OpenCode平台通过脚本自动生成本地配置目录，全程无需开发者手动配置环境变量、安装依赖包等，2分钟即可完成全部配置。

Q8：Superpowers与其他AI编程辅助工具的区别是什么？

市面上的多数AI编程辅助工具（如代码补全、智能提示工具）的核心是提升代码生成的速度，而Superpowers的核心是提升代码生成的质量和工程化程度。其并非简单的代码辅助工具，而是一套完整的AI开发工作流框架，通过强制工程规范让AI生成的代码能够满足生产级的要求，这是其他AI编程辅助工具无法实现的。

七、相关链接

1. 项目GitHub仓库：https://github.com/obra/superpowers

2. Claude Code插件市场：obra/superpowers-marketplace（Claude Code平台专属插件安装地址）

八、总结

Superpowers是一款将人类软件工程最佳实践与AI编码代理深度结合的开源工作流框架，由obra开发维护，核心通过可组合的技能体系和标准化的执行指令，为Claude Code、Codex、OpenCode等主流AI编码工具提供从需求梳理、设计文档编写、隔离环境创建，到原子任务分解、子代理执行、TDD开发、代码评审，再到分支收尾、版本集成的全流程开发约束，其本质是将TDD、YAGNI、DRY等经典工程原则转化为AI可理解的强制性协议，从源头解决了当前AI编程存在的需求理解模糊、代码质量低、工程规范缺失、版本管理混乱等问题。该框架采用解耦的三层架构设计，支持跨平台适配和自定义技能扩展，安装使用轻量便捷，无需复杂的环境搭建，同时适用于生产级功能开发、遗留系统重构、团队协作开发、大型项目分模块开发等多种AI辅助开发场景，既能让开发者享受AI带来的开发效率提升，又能保证产出代码的可维护性、可靠性和工程价值，为AI编码代理从“玩具级工具”向“生产级助手”的转变提供了一套完整的解决方案，是依赖AI进行项目开发的软件工程师和技术团队的重要工具。