superpowers 详细介绍：开源项目架构、功能与实践指南

项目速览（TL;DR）

superpowers 是一个面向编码代理（coding agent）的技能框架（skills framework）与软件开发方法论。根据 README，它通过可组合技能和初始指令约束代理的工作流程，使代理在编写代码前先澄清需求、形成设计、制定实施计划，再进入测试驱动开发（Test-Driven Development，TDD）和子代理驱动开发（subagent-driven development）。

仓库默认分支为 main，主要语言标注为 Shell，许可证为 MIT。GitHub 元信息显示该项目有 271613 个 Star 和 24285 个 Fork；仓库内 package.json 的版本为 6.3.0。这些数据属于所给仓库资料中的快照，文章不对其后续变化作推断。

定位与目标用户

Superpowers 的定位不是独立的代码编辑器、模型服务或持续集成平台，而是叠加在编码代理运行载体之上的流程层。它要求代理在需求理解、设计确认、任务拆解、实现、测试和审查之间建立明确的阶段关系。

目标用户需要已经使用 README 所列出的某一种代理运行载体（harness），例如 Claude Code、Codex CLI、Cursor、Gemini CLI、OpenCode、Pi 或 Hermes Agent。由于不同 harness 的安装方式不同，README 明确要求：如果同时使用多个 harness，需要分别安装 Superpowers。

它解决的问题

传统的编码代理交互容易从自然语言需求直接跳到代码生成，导致需求边界、设计取舍和验证方式没有经过显式确认。Superpowers 将这些步骤编排为技能触发流程：先通过提问提炼规格，再分段展示设计，获得确认后生成实施计划。

根据 README，计划面向“缺少项目上下文、缺乏判断且不愿测试的初级工程师”也能执行的粒度，任务通常被拆成较小的步骤，并要求给出文件路径、完整代码和验证步骤。这里的“通常”仅出现在 README 的英文描述语境中；本文不将其扩展为性能或质量保证。

核心功能

核心能力由若干可组合技能组成，触发点与前置条件比单独的提示词更重要。每项技能都承担流程中的一个阶段，并通过设计文档、实施计划、测试结果或审查结果衔接下一阶段。

需求澄清与设计确认

brainstorming 技能在写代码前激活。它通过问题细化用户的初始想法，探索替代方案，并按段落呈现设计内容供用户验证；设计结果会被保存为设计文档。

其输入是用户对功能或改动的初步描述，输出是经过确认的设计内容。README 没有提供设计文档的固定路径、文件格式、字段定义或持久化实现，因此这些细节不能从资料中进一步确定。

隔离工作区与基线检查

using-git-worktrees 在设计获得批准后激活。该技能会创建位于新分支上的隔离工作区，执行项目设置，并验证测试基线是否干净。

它的前置条件是设计已获批准，输入包括当前代码仓库和项目设置要求，输出是隔离的 Git 工作区及测试基线结果。README 没有说明 worktree 的命名规则、分支命名规则，也没有列出项目设置命令，因此不能给出更细的命令模板。

实施计划拆解

writing-plans 在设计批准后、实际实现前激活。它将工作拆成每项约 2 至 5 分钟的细粒度任务，并为每项任务给出准确文件路径、完整代码和验证步骤。

这种输出将“要做什么”转换为“在哪个文件以什么内容完成，以及如何确认完成”。资料没有提供计划文档示例，所以不能虚构计划文件的目录、YAML 字段或 JSON 结构。

子代理执行与两阶段审查

subagent-driven-development 或 executing-plans 在计划形成后激活。前者为每项任务派发新的子代理，并进行两阶段审查：第一阶段检查规格符合性，第二阶段检查代码质量；后者则按批次执行，并保留人工检查点。

选择哪一种取决于运行载体和实际工作方式，但 README 没有给出自动选择规则。子代理的模型、并发数、资源限制、超时设置和任务队列协议均未在资料中提供，不能据此推导出并发规模或运行性能。

测试驱动开发与调试

test-driven-development 在实现阶段激活，并要求遵循 RED-GREEN-REFACTOR：先编写失败测试并观察其失败，再写出最小实现并观察测试通过，最后进行重构。README 同时明确提到 YAGNI（You Aren’t Gonna Need It）和 DRY（Don’t Repeat Yourself）。

该流程的输入是已拆解的工程任务和现有代码，输出是测试结果、实现代码和重构后的代码。资料没有指定测试框架、测试命令、覆盖率阈值或语言级别，因此不能把 TDD 描述成对某个具体测试工具的封装。

系统架构与关键模块

从仓库资料可以确认的架构是“技能目录＋运行时引导＋按 harness 接入”的组合，而不是一个带独立服务端口的常驻服务。不同运行载体通过各自的插件、扩展或包机制加载相同仓库中的技能。

仓库包元数据

package.json 声明包名为 superpowers，版本为 6.3.0，包类型为 ES 模块（ES Module），主入口指向 .opencode/plugins/superpowers.js。它还声明了与 Pi 相关的扩展和技能路径。

{
  "name": "superpowers",
  "version": "6.3.0",
  "description": "Superpowers skills and runtime bootstrap for coding agents",
  "type": "module",
  "main": ".opencode/plugins/superpowers.js"
}

技能目录与启动引导

根据 package.json 的 pi 配置，Pi 包会加载 ./skills 目录中的技能，并加载 ./.pi/extensions/superpowers.ts 扩展。README 进一步说明，该 Pi 扩展会在会话启动时，以及上下文压缩（compaction）后再次注入 using-superpowers 引导。

OpenCode 的主入口则是 .opencode/plugins/superpowers.js。对于其他 harness，README 只提供了各自的安装入口，没有给出统一运行时 API，因此不能把 Pi 或 OpenCode 的目录结构直接套用于 Claude Code、Cursor 或 Gemini CLI。

多 harness 接入模型

Claude Code 和 GitHub Copilot CLI 使用 marketplace 注册与插件安装；Codex App 和 Codex CLI 使用 Codex 插件市场；Antigravity、Devin CLI、Gemini CLI、Pi 和 Hermes Agent 则提供从该 GitHub 仓库直接安装的方式。Cursor 使用 Agent chat 命令或插件市场，Factory Droid 使用自己的 marketplace 命令。

这种接入方式意味着安装动作由具体 harness 负责，Superpowers 本身没有在资料中声明统一的服务端、监听端口、远程 API 或数据库。运行时是否需要额外模型、凭据和项目级设置，应以所选 harness 的文档及当前 README 为准。

依赖与运行环境

资料能够确认的运行前提是：用户需要一个 README 支持的编码代理运行载体，并按照该载体的安装方式加载插件、扩展或包。仓库元信息将主要语言标为 Shell，但 package.json 同时包含 ES 模块入口和 Pi 的 TypeScript 扩展声明。

• Claude Code：通过官方 Claude 插件市场或 Superpowers marketplace 安装。
• Codex App、Codex CLI：通过 OpenAI 插件市场安装。
• Antigravity、Devin CLI、Gemini CLI、Pi、Hermes Agent：资料提供了从仓库安装的命令。
• Cursor、Factory Droid、GitHub Copilot CLI、Grok Build CLI、Kimi Code、OpenCode：使用各自的插件或扩展安装流程。

仓库资料没有提供操作系统版本、Shell 版本、Node.js 版本、Python 版本、模型供应商、网络要求、CPU、内存、端口或容器镜像信息。官方仓库未提供该信息，建议以最新 README 和所选 harness 的运行要求为准。

快速开始

最小闭环包括选择一个 harness、安装 Superpowers、启动该 harness 的编码代理会话，并用一个本地项目需求验证技能是否触发。下面示例采用 README 明确给出的 Antigravity 安装命令，以避免引入资料之外的安装步骤。

安装

agy plugin install https://github.com/obra/superpowers

该命令来自 README 的 Antigravity 安装章节。README 说明 Antigravity 会运行插件的会话启动钩子，因此 Superpowers 从会话第一条消息开始生效；使用相同命令可以重新安装以更新。

运行

安装完成后，启动 Antigravity 会话，在本地测试项目中提出一个明确但尚未实现的需求，例如“为当前项目增加一个本地文件解析功能，并先给出设计”。资料没有提供 Antigravity 的会话启动命令，因此不补写不存在于 README 的 CLI 参数。

验证

验证重点不是检查某个端口，而是观察代理是否按技能流程工作：它应先通过问题澄清需求，分段展示设计并等待确认，而不是立即生成实现代码。确认设计后，再检查它是否生成包含文件路径、代码内容和验证步骤的计划。

1. 确认安装命令执行成功，并确保当前使用的是安装该插件的 Antigravity 环境。
2. 输入一个需要编码的本地项目需求，观察首轮响应是否进入需求澄清和设计阶段。
3. 批准设计后，检查是否出现可执行的细粒度计划。
4. 允许进入实现阶段，检查是否先编写失败测试，再实现最小代码并执行验证。

上述验证依据 README 对触发顺序和工作流的描述，不代表项目提供了自动化验收脚本。若技能未触发，优先检查当前 harness 是否已重启、插件是否安装到当前使用的实例，以及该 harness 的专用安装说明。

其他安装方式

安装方式必须与运行载体匹配；同一个仓库不会自动覆盖其他 harness。下面命令均来自 README，使用前应确认相应 CLI 已经存在并处于本地测试环境。

直接从仓库安装的载体

devin plugins install obra/superpowers
gemini extensions install https://github.com/obra/superpowers
pi install git:github.com/obra/superpowers
hermes plugins install obra/superpowers --enable

Devin CLI 通过 devin plugins update superpowers 更新；Gemini CLI 通过 gemini extensions update superpowers 更新。Pi 还支持用 pi -e /path/to/superpowers 将本地检出目录作为临时包加载；Hermes Agent 安装后需要重启活动会话。

市场或插件管理器安装

Claude Code 的官方市场安装命令是 /plugin install superpowers@claude-plugins-official，也可以先执行 /plugin marketplace add obra/superpowers-marketplace，再安装 superpowers@superpowers-marketplace。Codex CLI 使用 /plugins 搜索 superpowers 并选择 Install Plugin。

Cursor 使用 /add-plugin superpowers 或插件市场搜索；Factory Droid 先注册 https://github.com/obra/superpowers marketplace，再安装 superpowers@superpowers。Grok Build CLI 可执行 grok plugin install superpowers@xai-official --trust，或者在其 TUI 中使用 /marketplace。

配置说明

仓库资料中没有提供 .env.example、服务端配置文件、端口配置或模型参数表。可核查的配置来源主要是 package.json 的包元数据和 Pi 包声明，下面的“默认值”只记录文件中明确出现的值；未声明的运行时默认值统一标注为“未提供”。

表中字段是包描述和接入声明，不等同于代理运行时的全部设置。README 没有定义环境变量、配置覆盖顺序、日志级别、模型选择、并发参数或网络代理配置；这些内容应查阅对应 harness 的文档。

进阶用法

进阶用法的重点是利用阶段边界控制代理行为，而不是向单次提示中塞入更多指令。README 给出的流程允许在设计确认、计划执行和人工检查点分别介入。

在设计阶段设置边界

对涉及多个文件或行为变化的需求，可以先要求代理只进行设计澄清，不批准实现。这样能够在代码生成前检查目标、替代方案和范围，避免把未经确认的假设直接固化到代码中。

根据 README，设计会以足够短的分段形式展示，便于用户阅读和消化。资料没有规定用户确认的命令或协议，因此确认动作应使用当前 harness 支持的自然语言交互方式。

按计划选择执行方式

如果希望每个任务都由新的子代理处理并接受规格符合性、代码质量两阶段审查，可以采用 subagent-driven-development 流程。如果需要按批次推进并在批次之间保留人工检查点，则使用 executing-plans 流程。

这一选择属于工作流决策，不应被解释为两种模式在速度、成本或正确率上的比较。仓库资料没有提供基准测试、资源消耗或成功率数据。

本地开发与 Pi 临时加载

Pi 支持将本地仓库作为临时包加载，适合检查本地修改而不覆盖已安装版本。命令中的路径必须替换为实际检出目录；资料没有规定该目录必须位于某个固定位置。

pi -e /path/to/superpowers

README 说明 Pi 包会加载技能，并在会话启动和上下文压缩后注入引导。Pi 原生支持技能，因此不需要兼容性的 Skill 工具；子代理和任务列表工具仍属于可选的 Pi companion packages，仓库资料没有给出这些包的名称或安装命令。

可观测性与运维

Superpowers 的可观察对象主要是代理会话中的阶段转换、设计文档、实施计划、测试结果和审查过程，而不是一个提供 HTTP 指标的服务。资料没有声明日志格式、指标名称、追踪系统、健康检查接口或告警机制。

• 会话级观察：确认首轮需求是否触发 brainstorming。
• 工作区级观察：确认设计批准后是否创建隔离工作区并检查测试基线。
• 计划级观察：确认任务是否包含文件路径、代码内容和验证步骤。
• 实现级观察：确认是否遵循 RED-GREEN-REFACTOR 顺序。
• 审查级观察：在子代理模式下分别记录规格符合性和代码质量审查结果。

对于长期运行会话，需要注意运行载体的上下文压缩行为。README 特别说明 Hermes Agent 没有 post-compaction hook，如果技能在首次回合之后发生压缩并停止触发，应启动新会话；这属于 Hermes 的接入限制，不是通用的 Superpowers 配置项。

安全与合规边界

资料将项目描述为编码代理的方法论和技能框架，没有声明其提供渗透、爬虫、账号自动化、支付处理或模型越狱功能。安全边界应放在代理所操作的代码、文件、凭据和外部工具权限上，而不是把流程技能视为权限控制系统。

• 仅在获得授权的本地仓库、测试仓库或组织明确允许的项目中运行编码代理。
• 不要把 API 密钥、访问令牌、生产数据库凭据或个人隐私数据直接放入提示、设计文档或测试输出。
• 在允许代理执行命令前，确认其工作目录、Git 分支和文件修改范围。
• 对生成的代码、依赖变更、文件删除和外部网络访问进行人工审查。
• 涉及生产系统、受监管数据或第三方系统时，遵守组织内部审批、审计和数据处理要求。

Superpowers 的 README 和 LICENSE 没有提供企业级隔离、审计留痕、数据保留、漏洞响应、服务等级协议（SLA）或合规认证承诺。根据本文作者的经验判断，若组织要求这些能力，应在 harness、执行环境和外围治理系统中单独补齐，不能仅凭安装该仓库满足要求。

许可证与商用条款

仓库 LICENSE 声明项目采用 MIT License，版权归属为 Jesse Vincent，年份为 2025。MIT 条款允许获得软件及相关文档的人员使用、复制、修改、合并、发布、分发、再许可和销售软件，但分发时必须保留版权声明和许可声明。

LICENSE 同时声明软件按“现状”提供，不提供适销性、特定用途适用性和不侵权保证，并排除了作者对相关损害的责任。是否将其纳入具体商业产品，还需要结合依赖项、组织政策、分发方式和适用法律审查；本文不提供法律意见。

README 还提到，企业用户可以通过 sales@primeradiant.com 联系商业支持、额外工具或托管支出服务。资料没有给出价格、服务范围、SLA、数据处理条款或支持响应时间，相关商业条件以双方书面约定和仓库 LICENSE 为准。

局限性与已知限制

项目资料重点描述方法论、技能触发和安装入口，没有给出完整的运行时规范。使用前需要把“仓库已经声明的能力”和“所选 harness 负责的能力”分开评估。

• 未提供统一的跨 harness 配置文件格式。
• 未提供统一的启动命令、模型接口或认证接口。
• 未提供端口、资源需求、性能基准、并发上限或任务吞吐数据。
• 未提供测试框架、覆盖率要求和通用 CI 配置。
• 不同 harness 的安装、更新和会话生命周期并不相同，需要分别处理。
• Hermes Agent 缺少 post-compaction hook，长会话在特定压缩情形下需要重新启动。
• Pi 的子代理和任务列表工具是可选 companion packages，资料未提供其具体包信息。

此外，所给 README 内容在 test-driven-development 描述处截断，后续“What's Inside”“Philosophy”“Contributing”“Updating”等章节的完整内容没有出现在资料中。对于这些未提供部分，官方仓库未提供该信息，建议以最新 README 为准。

适合谁

是否采用该项目，首先取决于团队是否愿意把编码代理纳入一个可审查的工程流程。以下信号表明它与使用场景较匹配：

• 团队已经使用 README 列出的一个或多个编码代理，并希望统一需求澄清、设计确认和实施计划步骤。
• 项目需要在动手编码前保留设计文档和人工确认点，而不是接受代理直接修改代码。
• 团队愿意执行测试驱动开发，并要求任务包含明确的文件路径和验证步骤。
• 代码仓库适合通过 Git 分支和 worktree 隔离变更，能够在实现前检查测试基线。
• 团队希望将复杂任务拆分给子代理，并对规格符合性与代码质量分别审查。

这些判断标准都对应 README 描述的流程阶段，不代表项目对团队规模、代码规模或交付周期有硬性要求。仓库未提供这些维度的限制数据。

不适合谁

以下情况并不一定意味着项目不能使用，但说明引入前需要先解决流程或治理缺口：

• 团队使用的代理运行载体不在 README 列出的支持范围内，且没有能力自行适配插件、扩展或技能加载方式。
• 项目要求代理绕过设计确认、代码审查和测试步骤，直接修改生产代码。
• 运行环境禁止创建 Git 分支或 worktree，无法满足隔离工作区流程。
• 组织不能接受代理接触源代码、测试数据、凭据或外部工具，且没有额外的隔离执行环境。
• 团队需要仓库资料没有声明的 SLA、性能指标、审计接口、合规认证或集中式运维能力。

在这类场景中，应先评估当前 harness 的权限模型和组织治理要求。若不能接受人工检查点或无法提供受控运行环境，仅安装技能框架不会自动消除这些风险。

常见问题与排查（FAQ / Troubleshooting）

排查应先确认接入载体和会话状态，再检查技能触发。由于仓库没有统一诊断命令，下面方法只采用 README 已明确的安装和生命周期信息。

为什么安装后没有触发技能

先确认插件是否安装到了当前正在使用的 harness，而不是另一个代理客户端。README 要求多 harness 分别安装；安装完成后，重新启动对应会话，再用一个明确的编码需求检查是否进入需求澄清阶段。

为什么设计完成后没有进入计划阶段

检查设计是否已明确获得批准。根据 README，writing-plans 的激活条件是“approved design”；如果仍处于方案讨论阶段，代理继续提问或展示设计并不表示安装失败。

Hermes Agent 长会话中技能停止触发怎么办

README 明确指出 Hermes Agent 没有 post-compaction hook。若会话在首次回合后发生上下文压缩并丢失引导，应结束当前会话并启动新会话；不要把该现象归因于端口、环境变量或版本兼容性，资料没有提供这些诊断依据。

如何在 Pi 中验证本地修改

使用仓库检出目录作为临时包运行：

pi -e /path/to/superpowers

将 /path/to/superpowers 替换为实际路径。启动后检查技能是否被加载，以及会话启动时是否注入 using-superpowers；Pi 的具体日志查看命令没有在资料中提供。

是否需要多个安装命令

如果只使用一个 harness，只需执行该 harness 对应的安装流程。如果同时使用 Claude Code、Pi 或其他载体，需要分别安装，因为 README 明确说明不同 harness 之间不会自动共享安装状态。

仓库是否提供端口或 HTTP 健康检查

资料没有提供端口、HTTP 服务、健康检查路径或守护进程启动方式。Superpowers 在所给资料中的形态是插件、扩展或技能包，因此不能用一个未经资料证实的 URL 作为通用验证方式。

项目地址与资源

以下链接均来自项目资料或 README 中列出的官方站点。安装命令和支持范围可能随仓库更新变化，使用前应以当前仓库内容为准。

• superpowers GitHub 仓库
• Claude 官方插件市场中的 Superpowers
• Codex 官方插件市场仓库
• Grok 官方插件市场仓库
• OpenCode 安装说明
• Kimi Code 详细文档
• OpenCode 详细文档