Superpowers 快速入门：安装、工作流与实战指南

使用大语言模型（LLM）进行软件工程正在经历快速的转变。我们正在脱离 “氛围感编程”（Vibe Coding，即向 LLM 输入无结构提示词并寄希望于代码能正常运行），转向规范驱动开发（Spec-Driven Development, 简称 SDD）。然而，SDD 面临的最大挑战往往不是工具本身，而是开发人员的自律性。当面临紧急期限时，开发者很容易放弃结构化的步骤，重新回到随意的提示词对话中。

由 Jesse Vincent 和 Prime Radiant 团队开发的 Superpowers 解决了这一自律性难题。Superpowers 将完整的、规范驱动的方法论打包成可安装的 Claude Skills（技能），而不是将软件开发生命周期的控制权完全交给智能体或开发者的耐心。它将头脑风暴、规划、子智能体审查以及红绿重构的测试驱动开发（TDD）视为强制性检查点，智能体在进行任何更改之前必须验证这些步骤。为了支持这些高要求的智能体工作流，开发者需要稳定、高速地连接到 Claude 3.5 Sonnet 和 DeepSeek-V3 等前沿模型。像 n1n.ai 这样的 API 聚合器提供了坚实的 API 基础设施，能够轻松处理这些智能体工作流产生的大量并发请求。

为什么 Claude 3.5 Sonnet 与 Superpowers 是解决 Vibe Coding 的终极方案

大多数自定义的 Claude Code 配置之所以失败，是因为它们依赖于开发者手动调用规划或测试步骤。Superpowers 通过引入引导指令（Bootstrap Instruction）改变了这一点，该指令强制智能体在开始任何任务之前检查相关技能。这确保了无论您输入什么提示词，工作流都会自动激活。

Superpowers 运作的核心原则包括：

1. 测试驱动开发 (TDD)： 始终先写测试。在没有编写失败测试的情况下编写的代码将被删除。
2. 系统化优于随机性： 依靠结构化的流程，而不是猜测。
3. 降低复杂度： 将简单性作为首要的设计目标。
4. 证据优于断言： 在声明成功之前，必须运行并验证代码。

与局限于本地仓库的技能不同，Superpowers 作为一个插件包分发，兼容多种智能体环境。这意味着无论您是在 Claude Code、Cursor 还是基于 CLI 的智能体中工作，您的开发方法论都能保持完全一致。

多智能体安装与配置

Superpowers 必须针对您使用的每个智能体环境进行单独安装。它没有全局的单一安装命令。请根据您使用的工具选择相应的命令进行安装：

关键环境细节说明

• Antigravity: 自动运行插件的会话启动钩子（Session-Start Hook）。使用相同命令重新安装即可完成更新。
• Pi: 通过一个小扩展加载技能，该扩展在启动和上下文压缩后注入 using-superpowers 引导指令。由于 Pi 具有原生技能支持，因此不需要 Pi 的兼容性 Skill 工具。
• Hermes Agent: 缺乏上下文压缩后的钩子。如果超长会话触发了上下文压缩，引导指令可能会丢失。如果技能停止触发，请启动一个全新的会话。
• OpenCode: 将此安装视为与同一台机器上其他环境完全独立的路径。请按照仓库中 .opencode/INSTALL.md 的说明进行操作。

要验证安装是否成功，请启动您的智能体并运行以下发现命令：

What skills are available?

如果配置正确，智能体将列出 brainstorming、writing-plans、test-driven-development 和 subagent-driven-development 等技能。

七步核心工作流

Superpowers 将开发流程结构化为一个线性的七步管道，每个技能会自动将控制权移交给下一个：

[brainstorming]
       │
       ▼
[using-git-worktrees]
       │
       ▼
[writing-plans]
       │
       ▼
[subagent-driven-development] 或 [executing-plans]
       │
       ▼
[test-driven-development]
       │
       ▼
[requesting-code-review]
       │
       ▼
[finishing-a-development-branch]

1. Brainstorming (头脑风暴)

在编写任何代码之前激活。它通过提出澄清性问题、探索架构替代方案以及将设计拆分为简短、可评审的模块来细化您的需求。输出结果将保存为设计构想文件。

2. Using Git Worktrees (使用 Git 工作区)

在您批准设计后，此技能会在一个新的 Git 分支上创建一个隔离的工作空间。它会运行项目的初始化命令，并验证现有的测试套件是否全部通过，从而建立一个干净的基线。

3. Writing Plans (编写计划)

将设计构想文件拆分为微小的任务。Superpowers 的设计目标是让每个任务的工作量控制在 2 到 5 分钟之间。每个任务都必须指定具体的文件路径、代码更改以及明确的验证步骤。

4. Subagent-Driven Development / Executing Plans (子智能体驱动开发 / 执行计划)

为每个任务分配一个独立的子智能体。子智能体在隔离的上下文中运行以防止上下文漂移。它采用两阶段评审机制：首先验证规范合规性，然后评估代码质量。

5. Test-Driven Development (测试驱动开发 - TDD)

强制执行严格的“红-绿-重构”循环。智能体必须先编写一个失败的测试，验证其失败，然后编写最简实现代码使测试通过，最后提交更改。如果在编写失败测试之前就写了实现代码，Superpowers 会提示智能体删除该代码并重新开始。

6. Requesting Code Review (申请代码评审)

在任务之间运行。它对照计划分析 Git Diff 差异，并按严重程度对问题进行分类。严重的问题会阻止工作流继续进行，必须在解决后才能进入下一个任务。

7. Finishing a Development Branch (完成开发分支)

在所有任务完成后运行。它验证整个测试套件是否通过，提供合并或开 PR 的选项，并清理临时 Git 工作区。

实战演练：添加 API 限流功能

为了展示 Superpowers 的实际效果，我们将演示如何为一个 Python FastAPI 应用实现一个限流中间件。我们将使用基于 n1n.ai API 网关的配置来调用 Claude 3.5 Sonnet。

步骤 1：发起任务

启动智能体对话并输入初始提示词：

I want to add rate limiting to our public API endpoints.

Superpowers 的 brainstorming 技能会拦截该请求，并主动提问：

1. 限流的阈值是多少（例如每分钟 100 次请求）？
2. 我们应该通过 IP 地址、API Key 还是 JWT Token 来识别用户？
3. 当超出限流时，应该返回什么状态码和响应体？

提供您的回答：

每个 IP 每分钟限制 60 次请求。超出限制时返回 HTTP 429 Too Many Requests，JSON 响应体为：{"error": "Rate limit exceeded"}。

步骤 2：生成计划

writing-plans 技能会生成一个计划文件（.plans/rate_limiting.md）：

# Plan: API Rate Limiting

- [ ] Task 1: Create a rate limiting utility class using an in-memory dictionary.
  - Verification: Run pytest on tests/test_rate_limiter.py
- [ ] Task 2: Implement FastAPI middleware that applies the rate limiter to all routes.
  - Verification: Run integration tests simulating rate limit breaches.

步骤 3：执行 TDD (任务 1)

子智能体被派去首先编写测试。它创建了 tests/test_rate_limiter.py：

import pytest
import time
from utils.rate_limiter import InMemoryRateLimiter

def test_rate_limiter_allows_under_limit():
    limiter = InMemoryRateLimiter(limit=5, window=60)
    ip = "192.168.1.1"
    for _ in range(5):
        assert limiter.is_allowed(ip) is True

def test_rate_limiter_blocks_over_limit():
    limiter = InMemoryRateLimiter(limit=5, window=60)
    ip = "192.168.1.1"
    for _ in range(5):
        limiter.is_allowed(ip)
    assert limiter.is_allowed(ip) is False

智能体运行测试套件。由于 utils/rate_limiter 尚未创建，测试运行失败（红色阶段）。

接着，智能体在 utils/rate_limiter.py 中编写最简实现代码：

import time
from collections import defaultdict

class InMemoryRateLimiter:
    def __init__(self, limit: int, window: int):
        self.limit = limit
        self.window = window
        self.requests = defaultdict(list)

    def is_allowed(self, ip: str) -> bool:
        now = time.time()
        # 过滤掉当前时间窗口之外的请求记录
        self.requests[ip] = [t for t in self.requests[ip] if now - t < self.window]

        if len(self.requests[ip]) < self.limit:
            self.requests[ip].append(now)
            return True
        return False

智能体重新运行测试，测试顺利通过（绿色阶段）。智能体提交当前进度。

步骤 4：中间件集成 (任务 2)

智能体为 FastAPI 中间件编写集成测试，验证其失败，然后实现中间件，并验证测试通过。最后，finishing-a-development-branch 技能清理工作区，并准备好分支以供合并。

辅助技能参考

除了核心开发流程外，Superpowers 还包含一些专业领域的辅助技能：

• systematic-debugging: 包含四个阶段的根因分析流程，具体由 root-cause-tracing、defense-in-depth 和 condition-based-waiting 组成。
• dispatching-parallel-agents: 管理并发子智能体的执行。每个子智能体在隔离的上下文中运行，并将摘要报告给父会话，从而节省上下文窗口空间。
• writing-skills: 一个元技能（Meta-Skill），允许开发人员使用 Superpowers 的测试和验证框架编写新的自定义技能。

工具对比

什么时候该使用 Superpowers

在以下情况下，强烈建议使用 Superpowers：

• 您经常遇到“提示词漂移”，并希望智能体能够自动遵循严格的规划和测试方法。
• 您在多个开发环境中工作（例如在家里用 Cursor，在终端用 Claude Code），并希望拥有一致的技能集合。
• 您希望自动强制执行 TDD，而无需自己编写复杂的 pre-commit 钩子或智能体指令。
• 您正在管理大型的多会话任务，这些任务中架构偏离的风险非常高。

在以下情况下，您可以选择跳过 Superpowers：

• 您正在编写快速的、一次性的脚本或单文件原型，规划的开销反而会降低您的效率。
• 您的团队已经拥有成熟且高度定制的 SDD 工作流，这与 Superpowers 严格的 2 到 5 分钟任务划分相冲突。

常见故障排除与优化

如果在会话期间技能未能触发，请执行以下排查步骤：

1. 验证技能存在： 运行 What skills are available?。如果未列出相关技能，说明安装失败，或者当前的智能体环境未能正确加载插件目录。
2. 检查上下文压缩： 在长会话中，某些智能体（如 Hermes）会压缩历史记录，这可能会丢弃引导指令。启动一个新会话即可恢复引导。
3. 关闭遥测数据： 默认情况下，头脑风暴技能会从 Prime Radiant 的服务器加载视觉资源 logo，这会发送您的 Superpowers 版本号。如果需要禁用，请设置环境变量：

   export SUPERPOWERS_DISABLE_TELEMETRY=true
   

   Superpowers 同样支持标准的 DISABLE_TELEMETRY 和 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC 环境变量。

实施结构化的智能体工作流需要稳定且高吞吐量的 LLM API。通过使用像 n1n.ai 这样的聚合器，开发者可以在单个 API Key 下无缝调用 Claude 3.5 Sonnet、DeepSeek-V3 等多种模型，确保并发的子智能体始终能够获得所需的算力支持。

Get a free API key at n1n.ai