Superpowers 深度解析：174K Star 的 AI 编程智能体技能框架——从 Vibe Coding 到工程化开发范式的终极进化

一、背景：AI 编程的「巴别塔困境」

2025 年至今，AI 编程工具如雨后春笋般涌现——Claude Code、Cursor、Codex CLI、OpenCode、Gemini CLI……每一个都号称能「自动写代码」。但现实是残酷的：模型虽然能快速生成代码，却缺乏系统性的工程思维。拍脑袋写代码、无测试覆盖、架构随意——这些问题让开发者不得不频繁手动介入审查、调试和重构，AI 辅助开发的效率优势被严重削弱。

这就是所谓的 Vibe Coding（氛围编程）：你给 AI 一个模糊的需求，它凭「直觉」写出一堆代码，看起来能跑，但经不起推敲。没有设计文档、没有测试、没有代码审查，一切都在「感觉」中完成。

Superpowers 正是为解决这个问题而生的。它不是模型，不是 IDE 插件，而是一套完整的软件工程方法论框架——把资深工程师的「肌肉记忆」注入到 AI 编码代理中，让 Vibe Coding 从随意发挥变成有章可循。

这个项目由 Jesse Vincent（Prime Radiant 创始人）开发，2025 年 10 月发布，在短短几个月内狂揽 174,000+ GitHub Stars，成为 AI 编程领域最炙手可热的开源项目。它被 Anthropic 官方接纳进入 Claude 插件市场，同时也支持 Codex CLI、Cursor、OpenCode、Gemini CLI、GitHub Copilot CLI 等主流 AI 编程工具。

二、核心理念：技能驱动的工程化开发

2.1 从「提示词」到「技能」的范式跃迁

传统的 AI 编程工具依赖用户写提示词来引导模型行为。但提示词有几个致命问题：

• 不可复用：每个项目的提示词都要从零写起
• 不可组合：不同提示词之间容易冲突
• 不可验证：无法保证模型是否真的遵循了你的指令
• 不可演化：无法系统性地迭代和改进

Superpowers 引入了技能（Skill） 的概念：

传统方式：用户写 Prompt → AI 生成代码 → 人工审查
Superpowers：技能自动激活 → AI 遵循工程规范 → 系统化交付

一个 Skill 是一个自包含的工程行为单元，包含触发条件、执行步骤、验证标准和输出规范。多个 Skill 可以组合成完整的开发工作流。

2.2 五大设计原则

Superpowers 的设计遵循五个核心原则：

1. 测试驱动开发（TDD）：先写测试，再写代码。这不是建议，是强制。
2. 系统化优于临时性（Systematic over Ad-hoc）：流程优于猜测，每个决策都有依据。
3. 复杂度削减（Complexity Reduction）：简洁是首要目标，YAGNI（You Aren't Gonna Need It）贯穿始终。
4. 证据优于断言（Evidence over Claims）：验证在先，声明在后。没跑过测试就不算完成。
5. 可组合性（Composability）：每个技能独立工作，也能与其他技能无缝协作。

2.3 技能系统架构

┌─────────────────────────────────────────────────┐
│              Superpowers Framework               │
├─────────────────────────────────────────────────┤
│                                                  │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐      │
│  │brainstorm│  │  plan    │  │  build   │      │
│  │  -ing    │→ │  -ning   │→ │  -ing    │→ ... │
│  └──────────┘  └──────────┘  └──────────┘      │
│       ↑              ↑              ↑            │
│       │    Skill Registry & Dispatcher          │
│       │              │              │            │
│  ┌──────────────────────────────────────────┐   │
│  │         Platform Adaptation Layer         │   │
│  │  Claude Code │ Cursor │ Codex │ Gemini   │   │
│  └──────────────────────────────────────────┘   │
│                                                  │
│  ┌──────────────────────────────────────────┐   │
│  │          Shared Core Module               │   │
│  │    Skill Registration │ Dispatch │ Verify  │   │
│  └──────────────────────────────────────────┘   │
└─────────────────────────────────────────────────┘

三层架构确保了：

• 共享核心模块：提供基础功能和技能注册系统，各平台间功能一致
• 平台适配层：针对不同 AI 编码环境进行适配
• 可插拔技能层：用户可根据需要选择加载不同技能

三、完整工作流：从想法到交付

Superpowers 定义了一套完整的软件开发工作流，每个阶段都有对应的技能自动激活：

3.1 阶段一：头脑风暴（Brainstorming）

当你开始一个新任务时，brainstorming 技能自动激活。它不会直接写代码，而是通过苏格拉底式提问来提炼需求：

你：我想做一个用户认证系统

Superpowers 激活的对话：
├── 你的目标用户是谁？
├── 需要支持哪些认证方式？（OAuth、邮箱密码、MFA？）
├── 有没有现成的用户表？还是从零开始？
├── 安全要求是什么？（会话时长、密码策略？）
└── MVP 的边界在哪里？哪些功能可以先不做？

这个阶段的输出是一份设计文档，被分成足够短的段落，让你能真正读进去并逐一确认。

3.2 阶段二：Git Worktree 隔离

设计确认后，using-git-worktrees 技能自动激活：

# Superpowers 自动执行的操作
git worktree add ../feature-auth-system feature/auth-system
cd ../feature-auth-system

# 运行项目设置
npm install
npm test  # 确保测试基线干净

为什么要用 worktree 而不是 branch？因为在 worktree 中，你可以在不影响主工作区的情况下进行完整的开发循环。Superpowers 的目标是你能在主分支继续日常工作的同时，让 AI 在隔离环境中自主完成开发。

3.3 阶段三：编写计划（Writing Plans）

writing-plans 技能将设计文档拆解为可执行的任务清单。每个任务都有：

• 精确的文件路径
• 完整的代码变更
• 验证步骤
• 预估时间（2-5 分钟每个任务）

Plan: 用户认证系统
├── Task 1: 创建 User 模型 [src/models/user.ts]
│   ├── 代码: 定义 User 接口和 Schema
│   ├── 测试: src/models/__tests__/user.test.ts
│   └── 验证: npm test -- user.test.ts
│
├── Task 2: 实现 JWT 签发 [src/auth/jwt.ts]
│   ├── 代码: signToken, verifyToken 函数
│   ├── 测试: src/auth/__tests__/jwt.test.ts
│   └── 验证: npm test -- jwt.test.ts
│
├── Task 3: 认证中间件 [src/middleware/auth.ts]
│   ├── 代码: authenticate 中间件
│   ├── 测试: src/middleware/__tests__/auth.test.ts
│   └── 验证: npm test -- auth.test.ts
│
└── Task 4: 登录/注册路由 [src/routes/auth.ts]
    ├── 代码: POST /register, POST /login
    ├── 测试: src/routes/__tests__/auth.test.ts
    └── 验证: npm test -- auth.test.ts

3.4 阶段四：子代理驱动开发（Subagent-Driven Development）

这是 Superpowers 最核心的创新。subagent-driven-development 技能为每个任务派发一个全新的子代理，独立完成实现：

主代理（你对话的 AI）
├── 派发子代理 A → 完成 Task 1（User 模型）
│   └── 两阶段审查：规格合规 + 代码质量
├── 派发子代理 B → 完成 Task 2（JWT 签发）
│   └── 两阶段审查：规格合规 + 代码质量
├── 派发子代理 C → 完成 Task 3（认证中间件）
│   └── 两阶段审查：规格合规 + 代码质量
└── 派发子代理 D → 完成 Task 4（路由）
    └── 两阶段审查：规格合规 + 代码质量

两阶段审查是关键：

1. 规格合规审查：代码是否完成了计划中定义的所有功能？
2. 代码质量审查：代码质量、测试覆盖、错误处理是否达标？

只有通过两阶段审查，子代理的工作才会被接受。否则，主代理会要求子代理修改或自己修复问题。

3.5 阶段五：测试驱动开发（TDD）

test-driven-development 技能强制执行 RED-GREEN-REFACTOR 循环：

┌─────────────────────────────────────────────┐
│              TDD 循环                        │
│                                              │
│   1. RED    ──→  写一个失败的测试            │
│   2. GREEN  ──→  写最少的代码让测试通过      │
│   3. REFACTOR ─→  重构，保持测试通过         │
│   4. COMMIT ──→  提交                        │
│                                              │
│   ⚠️ 如果代码先于测试写出来，删除代码重来    │
└─────────────────────────────────────────────┘

Superpowers 对 TDD 的执行是极其严格的——如果它检测到代码在没有对应测试的情况下被编写，会直接删除该代码，要求先写测试。这不是开玩笑，这是强制性的工程纪律。

3.6 阶段六：代码审查（Code Review）

requesting-code-review 技能在任务之间自动激活，对照计划逐项审查：

## 代码审查报告

### 合规性检查
- [x] User 模型包含所有计划中定义的字段
- [x] JWT 签发使用了 HS256 算法
- [ ] 认证中间件缺少速率限制 ⚠️ 严重

### 代码质量
- [x] 测试覆盖率 > 90%
- [x] 错误处理完善
- [ ] JWT 密钥硬编码在源码中 🚨 阻塞

### 结论
2 个严重问题需要修复后才能继续。

严重问题会阻塞进度，必须修复后才能继续下一个任务。

3.7 阶段七：分支完成（Finishing a Development Branch）

finishing-a-development-branch 技能在所有任务完成后激活：

# 验证所有测试
npm test

# 提供选项
? 如何处理这个分支？
  1. 合并到主分支（merge）
  2. 创建 Pull Request
  3. 保留分支，稍后处理
  4. 丢弃所有更改

四、技能库详解：15+ 可组合技能

Superpowers 的技能库分为三大类：

4.1 协作类技能

4.2 测试与调试类技能

4.3 元技能

4.4 Systematic Debugging 深度剖析

systematic-debugging 是最被低估但最强大的技能之一。它遵循四阶段根因分析流程：

阶段 1: 复现（Reproduce）
├── 建立最小可复现环境
├── 确认复现条件
└── 排除环境因素

阶段 2: 根因追踪（Root Cause Tracing）
├── 从错误现象反向追踪
├── 使用二分法缩小范围
└── 确认唯一根因

阶段 3: 纵深防御（Defense in Depth）
├── 修复根因
├── 添加防护层防止同类问题
└── 在每一层都添加验证

阶段 4: 验证（Verification）
├── 原始 Bug 不再复现
├── 新增回归测试
└── 检查是否有连锁影响

对比一下没有 Superpowers 时的典型调试：

# 没有 Superpowers —— AI 的「试错式调试」
# 第一次尝试：加个 try-catch
try:
    result = fetch_user(user_id)
except:
    result = None  # "应该能修吧"

# 第二次尝试：换个写法
# result = fetch_user(int(user_id))  # "可能是类型问题"

# 第三次尝试：加日志
# print(f"debug: user_id={user_id}")  # "先看看输出什么"

有了 Superpowers 的 systematic-debugging：

# 阶段 1: 复现
# ✅ 确认：当 user_id 为 None 时触发 KeyError
# ✅ 最小复现：fetch_user(None) → KeyError: None

# 阶段 2: 根因追踪
# ✅ 调用链：route_handler → get_user_id(request) → fetch_user(user_id)
# ✅ 根因：get_user_id() 在 request.headers 缺少 user-id 时返回 None
# ✅ fetch_user() 没有对 None 做防御

# 阶段 3: 纵深防御
def get_user_id(request: Request) -> str:
    """从请求头获取用户ID，缺失时抛出 401"""
    user_id = request.headers.get("user-id")
    if user_id is None:
        raise HTTPException(status_code=401, detail="Missing user-id header")
    return user_id

def fetch_user(user_id: str) -> User:
    """获取用户信息，user_id 必须非空"""
    if not user_id:
        raise ValueError("user_id cannot be empty")
    return db.users.find_one({"id": user_id})

# 阶段 4: 验证
# ✅ 原始 Bug 不再复现
# ✅ 新增回归测试：test_missing_user_id_header_returns_401
# ✅ 新增回归测试：test_empty_user_id_raises_value_error

五、实战：用 Superpowers 构建一个 RESTful API

让我们用 Superpowers 从零构建一个任务管理 API，体验完整的工作流。

5.1 初始化项目

# 创建项目
mkdir task-api && cd task-api
npm init -y

# 安装依赖
npm install express jsonwebtoken bcrypt
npm install -D jest supertest @types/jest @types/express

# 初始化 Superpowers（以 Claude Code 为例）
# /plugin install superpowers@claude-plugins-official

5.2 头脑风暴阶段

当你告诉 AI「我想做一个任务管理 API」时，Superpowers 的 brainstorming 技能自动激活，引导你完成需求定义：

Superpowers: 我来帮你梳理这个任务管理 API 的需求。
  
  首先，几个关键问题：
  
  1. 目标用户：个人使用还是团队协作？
  2. 任务模型：需要哪些字段？（标题、描述、截止日期、优先级、标签？）
  3. 权限模型：是否需要用户认证？任务是否区分公开/私有？
  4. MVP 边界：第一版需要哪些核心功能？哪些可以后续迭代？
  
  请逐一回答，我会整理成设计文档。

你：个人使用，任务有标题、描述、截止日期、优先级、完成状态。需要简单的 JWT 认证。MVP 只要 CRUD + 认证。

Superpowers: 好的，我整理了设计文档，请分步确认：

  ── 第 1 部分：数据模型 ──
  
  Task {
    id: string (UUID)
    title: string (required, max 200 chars)
    description: string (optional, max 2000 chars)
    dueDate: string (ISO 8601, optional)
    priority: enum [low, medium, high] (default: medium)
    completed: boolean (default: false)
    userId: string (JWT subject)
    createdAt: string (ISO 8601)
    updatedAt: string (ISO 8601)
  }
  
  这个模型是否满足需求？

你：可以，继续。

5.3 计划阶段

Superpowers 自动生成实现计划：

Plan: 任务管理 API (10 tasks, estimated ~35 min)

Task 1: 项目结构与配置 [package.json, jest.config.js, .env.example]
  - 更新 package.json scripts
  - 配置 Jest
  - 创建环境变量模板
  Verify: npm test (should pass with no tests)

Task 2: 数据库连接层 [src/db/connection.ts]
  - 内存数据库实现（MVP 阶段不引入真实 DB）
  - 连接/断开生命周期
  Test: src/db/__tests__/connection.test.ts
  Verify: npm test -- connection.test.ts

Task 3: Task 模型 [src/models/task.ts]
  - Task 接口定义
  - TaskRepository 类（CRUD 操作）
  Test: src/models/__tests__/task.test.ts
  Verify: npm test -- task.test.ts

Task 4: JWT 工具 [src/auth/jwt.ts]
  - signToken(userId) → token
  - verifyToken(token) → payload
  Test: src/auth/__tests__/jwt.test.ts
  Verify: npm test -- jwt.test.ts

Task 5: 认证中间件 [src/middleware/auth.ts]
  - extractToken(request) → token
  - authenticate(request, response, next) → userId
  Test: src/middleware/__tests__/auth.test.ts
  Verify: npm test -- auth.test.ts

Task 6: 认证路由 [src/routes/auth.ts]
  - POST /auth/register → { token, userId }
  - POST /auth/login → { token, userId }
  Test: src/routes/__tests__/auth.test.ts
  Verify: npm test -- auth.test.ts

Task 7: 任务路由 [src/routes/tasks.ts]
  - GET /tasks → Task[]
  - POST /tasks → Task
  - GET /tasks/:id → Task
  - PUT /tasks/:id → Task
  - DELETE /tasks/:id → 204
  Test: src/routes/__tests__/tasks.test.ts
  Verify: npm test -- tasks.test.ts

Task 8: 错误处理中间件 [src/middleware/errorHandler.ts]
  - 统一错误响应格式
  - JWT 错误 → 401
  - 验证错误 → 400
  - 未知错误 → 500
  Test: src/middleware/__tests__/errorHandler.test.ts
  Verify: npm test -- errorHandler.test.ts

Task 9: 应用入口 [src/app.ts, src/server.ts]
  - 组装 Express 应用
  - 挂载路由和中间件
  - 优雅关闭
  Test: src/__tests__/app.test.ts
  Verify: npm test -- app.test.ts

Task 10: 集成测试 [tests/integration/api.test.ts]
  - 完整用户流程测试
  - 注册 → 创建任务 → 查询 → 更新 → 删除
  Verify: npm test

5.4 TDD 实战：Task 模型

Superpowers 的子代理会按照 TDD 严格实现每个任务。以 Task 3 为例：

第一步：RED（写失败的测试）

// src/models/__tests__/task.test.ts
import { TaskRepository } from '../task';

describe('TaskRepository', () => {
  let repo: TaskRepository;

  beforeEach(() => {
    repo = new TaskRepository();
  });

  describe('create', () => {
    it('should create a task with required fields', () => {
      const task = repo.create({
        title: '写技术博客',
        userId: 'user-1',
      });

      expect(task.id).toBeDefined();
      expect(task.title).toBe('写技术博客');
      expect(task.priority).toBe('medium');
      expect(task.completed).toBe(false);
      expect(task.createdAt).toBeDefined();
    });

    it('should create a task with all fields', () => {
      const task = repo.create({
        title: '紧急修复',
        description: '线上 Bug 需要立即修复',
        dueDate: '2026-05-20T00:00:00Z',
        priority: 'high',
        userId: 'user-1',
      });

      expect(task.description).toBe('线上 Bug 需要立即修复');
      expect(task.priority).toBe('high');
      expect(task.dueDate).toBe('2026-05-20T00:00:00Z');
    });

    it('should reject empty title', () => {
      expect(() => repo.create({ title: '', userId: 'user-1' }))
        .toThrow('Title is required');
    });

    it('should reject title exceeding 200 chars', () => {
      const longTitle = 'a'.repeat(201);
      expect(() => repo.create({ title: longTitle, userId: 'user-1' }))
        .toThrow('Title must be at most 200 characters');
    });
  });

  describe('findByUserId', () => {
    it('should return only tasks belonging to the user', () => {
      repo.create({ title: '我的任务', userId: 'user-1' });
      repo.create({ title: '别人的任务', userId: 'user-2' });

      const userTasks = repo.findByUserId('user-1');
      expect(userTasks).toHaveLength(1);
      expect(userTasks[0].title).toBe('我的任务');
    });
  });

  describe('update', () => {
    it('should update task fields', () => {
      const task = repo.create({ title: '原始标题', userId: 'user-1' });
      const updated = repo.update(task.id, { title: '新标题', completed: true });

      expect(updated.title).toBe('新标题');
      expect(updated.completed).toBe(true);
      expect(updated.updatedAt).not.toBe(task.createdAt);
    });

    it('should throw for non-existent task', () => {
      expect(() => repo.update('non-existent', { title: 'x' }))
        .toThrow('Task not found');
    });
  });

  describe('delete', () => {
    it('should remove a task', () => {
      const task = repo.create({ title: '待删除', userId: 'user-1' });
      repo.delete(task.id);
      expect(repo.findByUserId('user-1')).toHaveLength(0);
    });
  });
});

运行测试：全部失败 ✅（这是 RED 阶段的预期）

第二步：GREEN（写最少的代码让测试通过）

// src/models/task.ts
import { randomUUID } from 'crypto';

export interface TaskCreateInput {
  title: string;
  description?: string;
  dueDate?: string;
  priority?: 'low' | 'medium' | 'high';
  userId: string;
}

export interface TaskUpdateInput {
  title?: string;
  description?: string;
  dueDate?: string;
  priority?: 'low' | 'medium' | 'high';
  completed?: boolean;
}

export interface Task {
  id: string;
  title: string;
  description: string;
  dueDate: string | null;
  priority: 'low' | 'medium' | 'high';
  completed: boolean;
  userId: string;
  createdAt: string;
  updatedAt: string;
}

export class TaskRepository {
  private tasks: Map<string, Task> = new Map();

  create(input: TaskCreateInput): Task {
    if (!input.title) {
      throw new Error('Title is required');
    }
    if (input.title.length > 200) {
      throw new Error('Title must be at most 200 characters');
    }

    const now = new Date().toISOString();
    const task: Task = {
      id: randomUUID(),
      title: input.title,
      description: input.description ?? '',
      dueDate: input.dueDate ?? null,
      priority: input.priority ?? 'medium',
      completed: false,
      userId: input.userId,
      createdAt: now,
      updatedAt: now,
    };

    this.tasks.set(task.id, task);
    return task;
  }

  findByUserId(userId: string): Task[] {
    return Array.from(this.tasks.values())
      .filter(task => task.userId === userId);
  }

  findById(id: string): Task | undefined {
    return this.tasks.get(id);
  }

  update(id: string, input: TaskUpdateInput): Task {
    const task = this.tasks.get(id);
    if (!task) {
      throw new Error('Task not found');
    }

    const updated: Task = {
      ...task,
      ...input,
      updatedAt: new Date().toISOString(),
    };

    this.tasks.set(id, updated);
    return updated;
  }

  delete(id: string): boolean {
    return this.tasks.delete(id);
  }
}

运行测试：全部通过 ✅

第三步：REFACTOR（重构，保持测试通过）

当前实现使用内存 Map，对于 MVP 够用。未来可以替换为数据库实现，只需修改 TaskRepository 内部实现，接口不变。

5.5 认证中间件实现

同样是 TDD 流程：

// src/middleware/__tests__/auth.test.ts
import { authenticate, extractToken } from '../auth';
import { signToken } from '../../auth/jwt';
import { Request, Response, NextFunction } from 'express';

describe('auth middleware', () => {
  describe('extractToken', () => {
    it('should extract Bearer token from Authorization header', () => {
      const req = {
        headers: { authorization: 'Bearer abc123' },
      } as Request;
      expect(extractToken(req)).toBe('abc123');
    });

    it('should return null for missing header', () => {
      const req = { headers: {} } as Request;
      expect(extractToken(req)).toBeNull();
    });

    it('should return null for non-Bearer scheme', () => {
      const req = {
        headers: { authorization: 'Basic abc123' },
      } as Request;
      expect(extractToken(req)).toBeNull();
    });
  });

  describe('authenticate', () => {
    it('should set userId on request for valid token', async () => {
      const token = signToken('user-1');
      const req = {
        headers: { authorization: `Bearer ${token}` },
      } as any;
      const res = {} as Response;
      const next = jest.fn() as NextFunction;

      await authenticate(req, res, next);

      expect(req.userId).toBe('user-1');
      expect(next).toHaveBeenCalledWith();
    });

    it('should return 401 for missing token', async () => {
      const req = { headers: {} } as Request;
      const res = {
        status: jest.fn().mockReturnThis(),
        json: jest.fn(),
      } as any;
      const next = jest.fn() as NextFunction;

      await authenticate(req, res, next);

      expect(res.status).toHaveBeenCalledWith(401);
      expect(next).not.toHaveBeenCalled();
    });
  });
});

实现：

// src/middleware/auth.ts
import { verifyToken } from '../auth/jwt';
import { Request, Response, NextFunction } from 'express';

export function extractToken(req: Request): string | null {
  const authHeader = req.headers.authorization;
  if (!authHeader?.startsWith('Bearer ')) {
    return null;
  }
  return authHeader.slice(7);
}

export async function authenticate(
  req: Request & { userId?: string },
  res: Response,
  next: NextFunction
): Promise<void> {
  const token = extractToken(req);
  if (!token) {
    res.status(401).json({ error: 'Missing or invalid authorization token' });
    return;
  }

  try {
    const payload = verifyToken(token);
    req.userId = payload.userId;
    next();
  } catch {
    res.status(401).json({ error: 'Invalid or expired token' });
  }
}

5.6 完整的路由实现

// src/routes/tasks.ts
import { Router } from 'express';
import { authenticate } from '../middleware/auth';
import { TaskRepository } from '../models/task';

export function createTaskRouter(repo: TaskRepository): Router {
  const router = Router();

  // 所有任务路由都需要认证
  router.use(authenticate);

  // GET /tasks - 获取当前用户的所有任务
  router.get('/', (req: any, res) => {
    const tasks = repo.findByUserId(req.userId);
    res.json(tasks);
  });

  // POST /tasks - 创建新任务
  router.post('/', (req: any, res) => {
    try {
      const task = repo.create({
        ...req.body,
        userId: req.userId,
      });
      res.status(201).json(task);
    } catch (error: any) {
      res.status(400).json({ error: error.message });
    }
  });

  // GET /tasks/:id - 获取单个任务
  router.get('/:id', (req: any, res) => {
    const task = repo.findById(req.params.id);
    if (!task || task.userId !== req.userId) {
      return res.status(404).json({ error: 'Task not found' });
    }
    res.json(task);
  });

  // PUT /tasks/:id - 更新任务
  router.put('/:id', (req: any, res) => {
    const existing = repo.findById(req.params.id);
    if (!existing || existing.userId !== req.userId) {
      return res.status(404).json({ error: 'Task not found' });
    }
    try {
      const updated = repo.update(req.params.id, req.body);
      res.json(updated);
    } catch (error: any) {
      res.status(400).json({ error: error.message });
    }
  });

  // DELETE /tasks/:id - 删除任务
  router.delete('/:id', (req: any, res) => {
    const existing = repo.findById(req.params.id);
    if (!existing || existing.userId !== req.userId) {
      return res.status(404).json({ error: 'Task not found' });
    }
    repo.delete(req.params.id);
    res.status(204).send();
  });

  return router;
}

5.7 集成测试：完整用户流程

// tests/integration/api.test.ts
import request from 'supertest';
import { createApp } from '../../src/app';

describe('Task API Integration', () => {
  const app = createApp();

  let token: string;
  let userId: string;

  // 步骤 1: 注册
  it('should register a new user', async () => {
    const res = await request(app)
      .post('/auth/register')
      .send({ username: 'testuser', password: 'password123' });

    expect(res.status).toBe(201);
    expect(res.body.token).toBeDefined();
    expect(res.body.userId).toBeDefined();

    token = res.body.token;
    userId = res.body.userId;
  });

  // 步骤 2: 创建任务
  let taskId: string;

  it('should create a task', async () => {
    const res = await request(app)
      .post('/tasks')
      .set('Authorization', `Bearer ${token}`)
      .send({
        title: '完成 API 开发',
        description: '实现任务管理 API 的所有端点',
        priority: 'high',
        dueDate: '2026-05-20T00:00:00Z',
      });

    expect(res.status).toBe(201);
    expect(res.body.title).toBe('完成 API 开发');
    expect(res.body.priority).toBe('high');
    expect(res.body.completed).toBe(false);
    taskId = res.body.id;
  });

  // 步骤 3: 查询任务列表
  it('should list user tasks', async () => {
    const res = await request(app)
      .get('/tasks')
      .set('Authorization', `Bearer ${token}`);

    expect(res.status).toBe(200);
    expect(res.body).toHaveLength(1);
  });

  // 步骤 4: 更新任务
  it('should update a task', async () => {
    const res = await request(app)
      .put(`/tasks/${taskId}`)
      .set('Authorization', `Bearer ${token}`)
      .send({ completed: true });

    expect(res.status).toBe(200);
    expect(res.body.completed).toBe(true);
  });

  // 步骤 5: 删除任务
  it('should delete a task', async () => {
    const res = await request(app)
      .delete(`/tasks/${taskId}`)
      .set('Authorization', `Bearer ${token}`);

    expect(res.status).toBe(204);
  });

  // 步骤 6: 确认任务已删除
  it('should return empty task list', async () => {
    const res = await request(app)
      .get('/tasks')
      .set('Authorization', `Bearer ${token}`);

    expect(res.status).toBe(200);
    expect(res.body).toHaveLength(0);
  });

  // 安全测试：未认证访问
  it('should reject unauthenticated access', async () => {
    const res = await request(app).get('/tasks');
    expect(res.status).toBe(401);
  });

  // 安全测试：访问别人的任务
  it('should not access another user tasks', async () => {
    // 注册另一个用户
    const other = await request(app)
      .post('/auth/register')
      .send({ username: 'other', password: 'password456' });

    // 尝试用别人的 token 访问已删除的任务（虽然已删除，但即使存在也不应能访问）
    const res = await request(app)
      .get(`/tasks/${taskId}`)
      .set('Authorization', `Bearer ${other.body.token}`);

    expect(res.status).toBe(404);
  });
});

六、多平台安装与配置

6.1 Claude Code

# 方式一：官方插件市场（推荐）
/plugin install superpowers@claude-plugins-official

# 方式二：Superpowers 市场
/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplace

6.2 Codex CLI

# 打开插件搜索
/plugins
# 搜索 Superpowers
# 选择 Install Plugin

6.3 Cursor

# 在 Agent Chat 中
/add-plugin superpowers
# 或在插件市场中搜索 "superpowers"

6.4 Gemini CLI

# 安装扩展
gemini extensions install https://github.com/obra/superpowers

# 更新
gemini extensions update superpowers

6.5 OpenCode

# 让 OpenCode 执行：
Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.opencode/INSTALL.md

6.6 GitHub Copilot CLI

# 注册市场
copilot plugin marketplace add obra/superpowers-marketplace

# 安装插件
copilot plugin install superpowers@superpowers-marketplace

七、与其他 AI 编程框架的对比

7.1 Superpowers vs Agent Skills（addyosmani）

这是最容易混淆的两个项目。虽然都在做「AI 编程智能体的工程化」，但定位完全不同：

简单来说：Superpowers 是方法论框架，Agent Skills 是技能库。两者可以互补使用。

7.2 Superpowers vs Cursor Rules

7.3 Superpowers vs Claude Code 内置工作流

Claude Code 本身没有强制工程流程。它生成代码的质量完全取决于用户的提示词。Superpowers 在 Claude Code 之上添加了结构化的工程纪律，两者是互补关系而非竞争关系。

八、性能优化与最佳实践

8.1 子代理并发控制

Superpowers 支持 dispatching-parallel-agents 技能，允许同时运行多个子代理。但需要注意：

建议配置：
├── CPU 密集型任务：并发数 = CPU 核心数 - 1
├── I/O 密集型任务：并发数 = 4-8
└── 混合型任务：从 2 开始，逐步增加

8.2 Worktree 管理策略

# 定期清理已合并的 worktree
git worktree list
git worktree remove ../feature-completed
git worktree prune

# 命名规范
feature/xxx  → 新功能
fix/xxx      → Bug 修复
refactor/xxx → 重构

8.3 技能自定义

Superpowers 提供了 writing-skills 元技能来创建自定义技能：

# 自定义技能模板

## 触发条件
当 [具体条件] 时自动激活

## 执行步骤
1. 步骤一：[具体操作]
2. 步骤二：[具体操作]
3. 步骤三：[具体操作]

## 验证标准
- [ ] 标准一
- [ ] 标准二

## 输出规范
- 输出格式：[具体格式]
- 文件位置：[具体路径]

8.4 与 CI/CD 集成

# .github/workflows/superpowers.yml
name: Superpowers CI

on:
  pull_request:
    branches: [main]

jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '22'
          
      - name: Install dependencies
        run: npm ci
        
      - name: Run tests (TDD verification)
        run: npm test -- --coverage
        
      - name: Check coverage threshold
        run: |
          COVERAGE=$(cat coverage/coverage-summary.json | jq '.total.lines.pct')
          if (( $(echo "$COVERAGE < 80" | bc -l) )); then
            echo "Coverage $COVERAGE% is below 80% threshold"
            exit 1
          fi

九、Superpowers 的局限性与思考

9.1 当前局限

1. Token 消耗较高：子代理模式会显著增加 Token 使用量，每个子代理都需要完整的上下文
2. 复杂度门槛：对于简单任务，Superpowers 的流程可能显得过重
3. 平台兼容性：虽然支持多个平台，但每个平台的体验不完全一致
4. 贡献限制：官方明确表示一般不接受新技能的贡献，保持核心精简

9.2 适用场景

适合：

• 中大型项目开发
• 需要高代码质量的团队
• 长期维护的项目
• 需要严格测试覆盖的场景

不太适合：

• 快速原型验证
• 一次性脚本
• 学习/实验性质的项目

9.3 对 AI 编程未来的启示

Superpowers 的成功揭示了一个重要趋势：AI 编程的未来不在于更强的模型，而在于更好的工程框架。

就像 Rails 之于 Ruby、Spring 之于 Java——真正改变开发效率的不是语言本身，而是框架提供的那套「约定优于配置」的方法论。Superpowers 做的就是把这种理念带入 AI 编程领域。

十、总结

Superpowers 用 174K+ Star 的成绩证明了一件事：开发者需要的不只是能写代码的 AI，而是能系统化地写好代码的 AI。

它的核心价值在于：

1. 从 Vibe Coding 到 Engineering：用结构化技能替代随意编码
2. 强制工程纪律：TDD 不是口号，是可执行的规则
3. 子代理驱动开发：让 AI 真正实现自主、可控的开发
4. 跨平台兼容：一套方法论，适用于所有主流 AI 编程工具
5. 可组合可扩展：技能系统让框架能随需求演进

如果你还在用 AI 编程工具「拍脑袋写代码」，是时候给它们装上 Superpowers 了。

项目地址：https://github.com/obra/superpowers
作者：Jesse Vincent (Prime Radiant)
协议：MIT
社区 Discord：https://discord.gg/35wsABTejz