Superpowers 深度实战：123K Star 的 AI 编程工作流框架——从 Process over Prompt 到工程化 Agent 闭环系统

前言：AI 编程的"野蛮生长"困局

2026年，AI 编程工具已经渗透到每一个开发者的日常工作流。Claude Code、Cursor、Copilot、OpenCode……这些工具让"写代码"这件事变得前所未有的高效。但与此同时，一个诡异的现象开始浮现：

AI 写的代码越来越快，但质量却越来越难把控。

你有没有遇到过这样的场景：

• 让 AI "加个登录功能"，它立刻开始写代码，不问清是 OAuth、JWT 还是 Session
• 代码跑通了，但测试覆盖率几乎为零，边界情况全靠人工补
• AI 热衷于"炫技"，引入了十个你根本不需要的依赖
• 修复一个 bug，AI 顺便重构了半个项目，引入了三个新 bug
• PR 提上去，同事看完直摇头："这代码我 Review 不动"

问题的本质不是 AI 不够聪明，而是 AI 缺乏工程纪律。它像一个急于表现的实习生，只想着"写出能跑的代码"，却跳过了需求分析、架构设计、测试验证这些关键环节。

今天要介绍的项目，正是为解决这个问题而生。它不试图让 AI 变得更"聪明"，而是通过架构设计让它变得更"可靠"。

它叫 Superpowers，一个在 GitHub 上获得超过 123,000 Stars 的开源项目，由 Jesse Vincent（obra）打造，核心理念是：

Process over Prompt（流程大于提示词）

给 AI 套上软件工程的"纪律与护栏"，让它像资深工程师一样：先思考、再规划、后编码、必验证。

一、Superpowers 是什么：重新定义 AI 编程的工作流

1.1 它不是什么

在看 Superpowers 之前，先搞清楚它不是什么：

• 不是 AI 模型：它不提供任何新的推理能力，底层还是用 Claude、GPT 等模型
• 不是 IDE：它不替代 VS Code、Cursor 等编辑器
• 不是 Prompt 模板库：虽然它包含大量 Markdown 文件，但远比"复制粘贴提示词"复杂得多
• 不是自动化脚本：它不会自动完成整个项目，而是强制人工介入关键决策点

1.2 它是什么

Superpowers 是一套 Agent 技能框架（Skills Framework），本质上是：

1. 一组结构化的 Markdown 文件（SKILL.md），每个文件定义一个特定场景下的行为协议
2. 一套完整的工作流引擎，自动激活、编排这些技能
3. 一系列人工审批关卡，确保关键决策由人类确认

用一句话概括：

Superpowers 是 AI 编程助手的"工程大脑"，把"急于表现的实习生"变成"遵循流程的资深工程师"。

1.3 核心理念：流程胜于智能

Superpowers 的设计哲学可以用四个原则概括：

这套框架的颠覆性在于：它不试图让 AI 变得更"聪明"，而是通过架构设计让它变得更"可靠"。

二、技术架构：14 个可组合技能模块

Superpowers 的核心是一组结构化 Markdown 文件（SKILL.md），每个文件定义一个特定场景下的行为协议。

2.1 三层架构设计

┌─────────────────────────────────────────────────────────┐
│                 可插拔技能层 (Skills Layer)              │
│  brainstorming │ writing-plans │ tdd │ code-review ... │
├─────────────────────────────────────────────────────────┤
│               平台适配层 (Platform Adapter)              │
│     Claude Code │ Cursor │ OpenCode │ Copilot CLI       │
├─────────────────────────────────────────────────────────┤
│                 共享核心模块 (Core Engine)               │
│     技能注册 │ 工作流编排 │ 上下文管理 │ 审批网关        │
└─────────────────────────────────────────────────────────┘

共享核心模块：提供基础功能和技能注册系统，确保各平台间功能一致性。

平台适配层：针对 Claude Code、Cursor、OpenCode 等不同 AI 编码环境进行适配。

可插拔技能层：提供丰富的开发技能，用户可根据需要选择加载。

2.2 核心技能全景图

2.3 技能文件结构（SKILL.md）

每个技能都是一个独立的 Markdown 文件，遵循统一的结构：

---
name: brainstorming
description: 交互式需求澄清与设计方案生成
triggers:
  - user_request_needs_clarification
  - vague_requirements
  - new_feature_request
dependencies:
  - using-superpowers
---

# brainstorming 技能

## 触发条件
当用户提出需求但信息不完整时自动激活。

## 行为协议
1. 通过苏格拉底式提问深化用户想法
2. 探索至少两种替代方案
3. 分模块展示设计文档供用户确认
4. 保存设计文档到 `.claude/design/` 目录

## 输出格式
[设计文档模板...]

## 审批关卡
设计文档必须获得用户明确批准才能进入下一阶段。

这种结构化的定义方式，让每个技能的行为完全可预测、可审计。

三、7 步核心工作流详解

Superpowers 的核心是一个 7 步开发工作流，强制 AI 在每个关键节点停下来做正确的事：

① 头脑风暴 (brainstorming)
        ↓
② Git Worktree 创建隔离工作区
        ↓
③ 编写计划 (writing-plans)
        ↓
④ 执行计划 (executing-plans / subagent-driven-development)
        ↓
⑤ 测试驱动开发 (test-driven-development)
        ↓
⑥ 代码评审 (requesting-code-review)
        ↓
⑦ 完成开发分支 (finishing-a-development-branch)

3.1 第一步：头脑风暴（Brainstorming）

触发时机：用户提出新需求时

核心目标：在写任何代码之前，先确保设计获得批准

执行流程：

# AI 行为示例
用户："我要开发一个待办事项 API 服务"

AI 响应：
"I'll help you clarify the requirements. Let me ask some questions:

1. **Authentication**: Do you need user authentication? If yes, what type?
   - OAuth 2.0 (Google/GitHub)
   - JWT token-based
   - Session-based
   - No authentication needed

2. **Data Persistence**: What database do you prefer?
   - SQLite (file-based, zero setup)
   - PostgreSQL (production-grade)
   - MongoDB (document-based)

3. **API Style**: RESTful or GraphQL?

Please confirm or adjust these assumptions..."

关键特性：

• 通过提问细化粗略想法
• 探索至少两种替代方案
• 分模块展示设计方案供用户验证
• 自动保存设计文档到 .claude/design/ 目录

审批关卡：设计文档必须获得用户明确批准（yes/no）才能进入下一阶段。

3.2 第二步：Git Worktree 隔离工作区

触发时机：设计方案通过批准后

核心目标：确保每个任务在独立的 Git 环境中执行，避免污染主分支

执行流程：

# AI 自动执行
git worktree add .worktrees/feature-add-auth -b feature/add-auth

# 创建隔离环境后输出：
"Created isolated worktree at .worktrees/feature-add-auth
Branch: feature/add-auth
Base: main (commit abc123)

Verified clean test baseline: ✅ All tests passing"

关键特性：

• 在新分支创建独立工作区
• 完成项目初始化
• 验证干净的测试基线（所有测试必须通过）

为什么用 Worktree 而不是 Branch？

传统分支切换需要 stash 或 commit 当前工作，而 Worktree 允许同时检出多个分支：

project/
├── .worktrees/
│   ├── feature-add-auth/    # 独立工作区 1
│   └── fix-login-bug/       # 独立工作区 2
└── src/                      # 主工作区

这意味着你可以同时开发多个功能，互不干扰。

3.3 第三步：编写计划（Writing Plans）

触发时机：设计方案通过批准后

核心目标：将工作拆分为 2-5 分钟可完成的小型任务

执行流程：

# Implementation Plan

## Task 1: Create User Model (Est. 3 min)
- File: `src/models/User.ts`
- Code: Define interface with id, email, password_hash
- Verify: TypeScript compiles without errors

## Task 2: Add Password Hashing (Est. 4 min)
- File: `src/utils/password.ts`
- Code: Import bcrypt, create hash() and verify() functions
- Verify: Unit tests pass for both functions

## Task 3: Create Auth Middleware (Est. 5 min)
- File: `src/middleware/auth.ts`
- Code: JWT verification logic
- Verify: Middleware rejects invalid tokens

## Task 4: Add Login Endpoint (Est. 4 min)
- File: `src/routes/auth.ts`
- Code: POST /auth/login handler
- Verify: Integration test returns valid JWT

## Checkpoint
Human review required before proceeding to Task 5.

关键特性：

• 每个任务精确到文件路径、代码片段、验证步骤
• 任务粒度：2-5 分钟可完成
• 内置验证步骤，确保每个任务可独立验收

3.4 第四步：执行计划（Subagent-Driven Development）

触发时机：计划获得批准后

核心目标：为每个任务分配全新的子代理，执行两阶段评审

执行流程：

# AI 自动分配任务
[Task 1] Spawning subagent for: Create User Model
         → Working directory: .worktrees/feature-add-auth
         → Model: claude-3-sonnet (cost-optimized)

[Subagent Output]
Created file: src/models/User.ts
TypeScript compiled: ✅
Self-review: Passed specification check
Quality check: Passed

[Task 2] Spawning subagent for: Add Password Hashing
...

两阶段评审机制：

1. 规格一致性检查：代码是否符合设计文档？
2. 代码质量检查：是否有明显的问题（未处理的错误、安全漏洞）？

3.5 第五步：测试驱动开发（TDD）

触发时机：实施阶段

核心目标：强制遵循红-绿-重构流程

执行流程：

# Step 1: 编写失败测试
Created test: tests/auth.test.ts
Test name: "should reject invalid JWT"
Status: FAILING ❌ (expected: 401, got: 404)

# Step 2: 编写最简代码
Modified: src/middleware/auth.ts
Added: JWT verification logic

# Step 3: 观察通过
Running tests...
✅ All tests passing

# Step 4: 可选重构
Refactored: Extracted JWT logic to separate module
Tests still passing: ✅

强制规则：

• 必须先写失败的测试用例
• 观察测试失败（确保测试有效）
• 编写最简代码使测试通过
• 重构后必须重新验证测试

3.6 第六步：代码评审（Requesting Code Review）

触发时机：任务间

核心目标：对照计划进行评审，按严重程度报告问题

执行流程：

# Code Review Report

## Summary
- Tasks completed: 4/4
- Tests passing: 15/15
- Coverage: 89%

## Issues Found

### Critical (Blocks Merge)
- None ✅

### High Priority (Should Fix)
- [Task 3] Missing error handling for expired tokens
  File: src/middleware/auth.ts:23
  Suggestion: Add try-catch for jwt.verify()

### Medium Priority (Nice to Have)
- [Task 2] Consider using async bcrypt for better performance
  File: src/utils/password.ts:15

## Recommendation
Fix high-priority issues before merge. Medium-priority can be addressed in follow-up.

评审维度：

• 规格一致性：是否完全按照计划执行？
• 代码质量：是否有明显的坏味道？
• 测试覆盖：边界情况是否覆盖？
• 安全性：是否有潜在的安全风险？

3.7 第七步：完成开发分支（Finishing a Development Branch）

触发时机：任务完成后

核心目标：验证测试，提供选项，清理工作树

执行流程：

# Final Verification
Running full test suite...
✅ Unit tests: 45/45 passed
✅ Integration tests: 12/12 passed
✅ E2E tests: 8/8 passed
Coverage: 92%

# Merge Options
What would you like to do?

1. Merge to main (fast-forward)
2. Create Pull Request
3. Keep branch (manual merge later)
4. Discard changes

Your choice: 2

Creating Pull Request...
PR #42 created: https://github.com/user/repo/pull/42

Cleaning up worktree...
Removed: .worktrees/feature-add-auth

四、实战演示：从零开发一个完整项目

下面我们通过一个完整的实战案例，演示 Superpowers 如何引导 AI 完成一个 RESTful API 服务的开发。

4.1 项目需求

开发一个待办事项（Todo）API 服务，提供以下功能：

技术栈：Node.js + Express.js + SQLite（文件型数据库，无需安装）

4.2 第一步：Brainstorming —— 需求分析

# 用户输入
/superpowers.brainstorming

我要开发一个待办事项 API 服务（Node.js + Express + SQLite），请帮我分析需求。

AI 响应：

# Requirements Clarification

## Core Questions

### 1. Task Properties
What information should each todo item contain?
- [ ] Title (required, string)
- [ ] Description (optional, string)
- [ ] Completed status (boolean, default: false)
- [ ] Created/Updated timestamps
- [ ] Priority level (low/medium/high)
- [ ] Due date (optional)

### 2. Validation Rules
- Title: max length? (suggest: 200 chars)
- Description: max length? (suggest: 1000 chars)
- Allow empty completed status? (suggest: default to false)

### 3. Error Handling
- Invalid request body → 400 Bad Request
- Todo not found → 404 Not Found
- Database error → 500 Internal Server Error

### 4. Additional Features
- Pagination for GET /api/todos?
- Filter by completed status?
- Search by title?

## Proposed Architecture

project/
├── src/
│ ├── index.ts # Entry point
│ ├── app.ts # Express app
│ ├── routes/
│ │ └── todos.ts # Todo routes
│ ├── controllers/
│ │ └── todoController.ts
│ ├── models/
│ │ └── Todo.ts # Todo interface
│ ├── services/
│ │ └── todoService.ts
│ └── db/
│ └── database.ts # SQLite connection
├── tests/
│ └── todos.test.ts
└── package.json

## Alternative Approaches

**Option A**: Simple CRUD (recommended for MVP)
- Single table: todos
- No authentication
- In-memory SQLite

**Option B**: Full-featured
- User authentication (JWT)
- Multiple tables: users, todos
- PostgreSQL with migrations

Please confirm which option you prefer.

用户确认选项 A 后，AI 保存设计文档到 .claude/design/todos-api.md。

4.3 第二步：创建隔离工作区

# AI 自动执行
git worktree add .worktrees/todo-api -b feature/todo-api

# 输出
Created isolated worktree at .worktrees/todo-api
Branch: feature/todo-api
Base: main (commit: abc123)

Initializing project structure...
Created: package.json
Created: tsconfig.json
Created: .gitignore

Installing dependencies...
npm install express sqlite3 typescript @types/express @types/node --save
npm install jest @types/jest ts-jest --save-dev

Verified clean baseline: ✅ No tests yet (fresh project)

4.4 第三步：编写实施计划

# Implementation Plan: Todo API

## Task 1: Setup Express Server (Est. 3 min)
- File: `src/index.ts`
- Code: Create Express app, define port, start server
- Verify: Server starts without errors on `npm run dev`

## Task 2: Create Todo Interface (Est. 2 min)
- File: `src/models/Todo.ts`
- Code: Define interface with id, title, completed, createdAt
- Verify: TypeScript compiles

## Task 3: Setup SQLite Database (Est. 4 min)
- File: `src/db/database.ts`
- Code: Create SQLite connection, initialize todos table
- Verify: Database file created, table exists

## Task 4: Implement Todo Service (Est. 5 min)
- File: `src/services/todoService.ts`
- Code: CRUD operations using sqlite3
- Verify: TypeScript compiles

## Task 5: Implement Todo Controller (Est. 4 min)
- File: `src/controllers/todoController.ts`
- Code: Express route handlers calling service
- Verify: TypeScript compiles

## Task 6: Setup Routes (Est. 3 min)
- File: `src/routes/todos.ts`
- Code: Define GET, POST, PUT, DELETE routes
- Verify: Routes registered correctly

## Task 7: Add Error Handling (Est. 3 min)
- File: `src/middleware/errorHandler.ts`
- Code: Global error handler middleware
- Verify: Invalid routes return 404

## Checkpoint
Human review required before proceeding to tests.

## Task 8: Write Integration Tests (Est. 8 min)
- File: `tests/todos.test.ts`
- Code: Test all endpoints using supertest
- Verify: All tests pass

## Task 9: Add Stats Endpoint (Est. 3 min)
- File: `src/controllers/statsController.ts`
- Code: Return count of completed/pending todos
- Verify: GET /api/stats returns correct format

4.5 第四步：执行计划（TDD 流程）

# Task 1: Setup Express Server
[Subagent] Creating Express server...
Created: src/index.ts
Server running on port 3000 ✅

# Task 2: Create Todo Interface
[Subagent] Defining Todo interface...
Created: src/models/Todo.ts
TypeScript compiled ✅

# Task 8: Write Integration Tests (TDD)
[Subagent] Writing tests first...
Created: tests/todos.test.ts

Running tests...
❌ GET /api/todos - Expected 200, got 404
❌ POST /api/todos - Expected 201, got 404
... (8 tests failing)

Now implementing routes...

# Task 6: Setup Routes
[Subagent] Creating route handlers...
Created: src/routes/todos.ts
Modified: src/index.ts (added router)

Running tests...
✅ GET /api/todos - 200 OK
❌ POST /api/todos - Database error (table not found)

# Task 3: Setup SQLite Database
[Subagent] Initializing database...
Created: src/db/database.ts
Table 'todos' created ✅

Running tests...
✅ POST /api/todos - 201 Created
✅ All 8 tests passing!

4.6 第五步：代码评审

# Code Review Report

## Summary
- Tasks completed: 9/9
- Tests passing: 8/8
- Coverage: 94%

## Issues Found

### Critical
None ✅

### High Priority
- [Task 4] Missing transaction for concurrent updates
  File: src/services/todoService.ts:45
  Impact: Race condition when updating same todo

### Medium Priority
- [Task 3] Hardcoded database path
  File: src/db/database.ts:12
  Suggestion: Use environment variable

## Recommendation
High-priority issue should be fixed before merge.

修复后，所有测试重新通过。

4.7 第六步：完成分支

# Final Verification
Running full test suite...
✅ All tests passing
Coverage: 96%

Creating Pull Request...
PR #1: https://github.com/user/todo-api/pull/1

Cleaning up...
Removed: .worktrees/todo-api

五、高级特性：并行代理与复杂任务编排

5.1 Dispatching Parallel Agents

当多个任务相互独立时，Superpowers 可以同时启动多个子代理并行执行：

# 场景：同时添加 3 个独立的 API 端点

[Main Agent] Detecting parallelizable tasks:
- Task A: Add GET /api/users (no dependencies)
- Task B: Add GET /api/products (no dependencies)
- Task C: Add GET /api/orders (no dependencies)

Spawning 3 parallel agents...

[Agent A] Working on users endpoint...
          Progress: ████████░░ 80%
          
[Agent B] Working on products endpoint...
          Progress: ██████████ 100% ✅
          
[Agent C] Working on orders endpoint...
          Progress: ██████░░░░ 60%

All agents completed: 3/3 tasks done

并行策略：

• 自动检测任务依赖关系
• 有依赖的任务串行执行
• 无依赖的任务并行执行
• 每个代理有独立的上下文，避免交叉污染

5.2 处理阻塞（Handling Blockers）

当遇到无法自动解决的问题时，系统化升级：

# Blocker Detected

## Context
Task: Integrate payment gateway
Issue: API credentials not found in environment

## Impact
- Blocks: Task 5, 6, 7
- Estimated delay: Unknown (waiting for credentials)

## Options
1. Skip task (mark as blocked, continue others)
2. Use mock implementation (for development)
3. Request human intervention

## Recommendation
Option 2: Use mock implementation to unblock development.
Tests can verify against mock, and real credentials added later.

六、与其他工具的对比

6.1 Superpowers vs. 传统 Prompt Engineering

6.2 Superpowers vs. Cursor Rules

6.3 Superpowers vs. GitHub Copilot Workspace

七、安装与配置指南

7.1 Claude Code 安装（推荐）

# 1. 添加官方插件源
/plugin marketplace add obra/superpowers-marketplace

# 2. 安装 Superpowers 技能
/plugin install superpowers@superpowers-marketplace

# 3. 重启 Claude Code
关闭客户端重新打开，确保插件加载生效

# 4. 验证安装成功
/find-skills
# 应出现 superpowers: 开头的技能

7.2 Cursor 安装

# 1. 克隆仓库
git clone https://github.com/obra/superpowers.git ~/.cursor/superpowers

# 2. 配置 Cursor Rules
# 编辑 ~/.cursorrules，添加：
@import ~/.cursor/superpowers/skills/*/SKILL.md

# 3. 重启 Cursor

7.3 OpenCode 安装

# 1. 添加技能目录
mkdir -p ~/.opencode/skills
git clone https://github.com/obra/superpowers.git ~/.opencode/skills/superpowers

# 2. 在 OpenCode 配置中启用
# 编辑 ~/.opencode/config.json:
{
  "skills": ["superpowers"]
}

7.4 环境要求

• Git 2.17+（支持 worktree）
• Node.js 18+ 或 Bun
• 目标语言的 LSP（可选，用于代码分析）

八、最佳实践与常见陷阱

8.1 最佳实践

1. 信任流程：不要跳过任何审批关卡，即使看起来"显而易见"

2. 保持任务粒度：每个任务控制在 2-5 分钟，太大容易失控

3. 利用 Worktree：为每个功能创建独立工作区，避免污染主分支

4. 写设计文档：Brainstorming 阶段生成的文档是后续验收的依据

5. 监控子代理：并行执行时，定期检查各代理进度

8.2 常见陷阱

1. 跳过测试：AI 可能建议"先实现功能再补测试"，坚决拒绝

2. 过度依赖并行：有依赖的任务强制并行会导致混乱

3. 忽略评审：代码评审是质量保障的最后一道防线

4. 盲目合并：分支完成后务必再次运行完整测试套件

九、性能优化与成本控制

9.1 模型选择策略

Superpowers 支持为不同阶段指定不同模型：

{
  "model_routing": {
    "brainstorming": "claude-3-opus",      // 需要深度推理
    "writing_plans": "claude-3-sonnet",     // 平衡成本与质量
    "executing_tasks": "claude-3-haiku",   // 简单任务，节省成本
    "code_review": "claude-3-sonnet"       // 需要理解上下文
  }
}

9.2 上下文管理

Superpowers 自动管理上下文，避免 token 浪费：

• 设计文档精简：只保留决策要点，删除冗长讨论
• 任务隔离：每个子代理独立上下文，不继承历史对话
• 增量更新：只传递变更部分，避免重复传输完整文件

十、生态与未来展望

10.1 社区生态

Superpowers 采用 Apache-2.0 开源许可，鼓励社区贡献：

• 官方技能库：obra/superpowers（14+ 核心技能）
• 社区技能库：skills/awesome-superpowers（50+ 扩展技能）
• 企业定制：可创建私有技能库

10.2 未来路线图

根据官方规划，Superpowers 2.0 将带来：

1. 可视化工作流编辑器：拖拽式定义技能组合
2. 远程代理支持：云端部署子代理
3. 多语言 SDK：Python、Go、Rust 原生支持
4. IDE 深度集成：VS Code、JetBrains 插件

总结：从"实习生"到"工程师"的转变

Superpowers 的价值不在于让 AI 更"聪明"，而在于让 AI 更"可靠"。

它解决的不是"能不能写代码"的问题，而是"能不能写好代码"的问题。

通过强制的工作流、结构化的审批关卡、独立的工作区隔离，Superpowers 把 AI 编程助手从"急于表现的实习生"转变为"遵循流程的资深工程师"。

Process over Prompt —— 这四个字，道尽了 AI 编程的未来。

不是更聪明的 AI，而是更有纪律的 AI。

附录：核心技能速查表

项目信息：

• 仓库：https://github.com/obra/superpowers
• 作者：Jesse Vincent (obra)
• Star 数：123,000+
• 开源协议：Apache-2.0
• 支持平台：Claude Code、Cursor、OpenCode、Copilot CLI

参考资源：

• 官方文档：https://github.com/obra/superpowers/wiki
• 社区论坛：https://github.com/obra/superpowers/discussions
• 技能开发指南：https://github.com/obra/superpowers/blob/main/CONTRIBUTING.md