Superpowers 深度解析：145k Star 的 AI 编程技能框架，如何让 AI 学会软件工程

从「代码生成器」到「工程搭档」，一套让 AI 编程 Agent 遵循专业开发流程的结构化技能框架

一、引言：AI 编程 Agent 的「失控」困境

你有没有遇到过这样的场景：让 Claude Code 帮你实现一个功能，它一顿操作猛如虎，代码写得飞快，结果跑起来全是 bug；或者让它重构模块，它直接删了旧代码重写，把测试也一起干掉了；更常见的是，它跳过设计阶段直接开写，写完你才发现方向完全错了。

这不是 AI 不够聪明，而是它缺乏「软件工程的纪律」。

AI 编程 Agent 的典型失败模式包括：

1. 跳过设计直接写代码：拿到需求就动手，没有规划、没有文档
2. 缺乏测试驱动：写完代码不写测试，或者测试只是象征性的
3. 无法验证完成状态：什么时候算做完？AI 自己说了算
4. 积累技术债：快速实现不考虑可维护性
5. 无法复用经验：每次都从零开始，不会记住上次的做法

Superpowers 就是为解决这些问题而生的——一个专为 AI 编码 Agent 设计的结构化技能框架与软件开发方法论。它的核心理念是：Process over Prompt（流程大于提示词），给 AI 套上软件工程的「纪律与护栏」，让它像资深工程师一样：先思考、再规划、后编码、必验证。

项目由 Jesse Vincent（obra）开发，MIT 协议开源，截至 2026 年 4 月已获得 165,000+ Stars，支持 Claude Code、Cursor、Codex、OpenCode、GitHub Copilot CLI 和 Gemini CLI 等主流 AI 编码工具。

二、核心理念：三层指令优先级体系

Superpowers 的核心创新在于建立了一套三层指令优先级体系，让 AI 在执行任务时有明确的「行为准则」：

┌─────────────────────────────────────────────────────┐
│                    技能层 (Skills)                    │ ← 最高优先级
│    结构化的工作流定义，强制执行特定场景的行为规范        │
├─────────────────────────────────────────────────────┤
│                    配置层 (CLAUDE.md)                 │ ← 中等优先级
│    项目级和个人级的偏好设置、技术栈约定、代码风格        │
├─────────────────────────────────────────────────────┤
│                    对话层 (Conversation)              │ ← 最低优先级
│    用户当前的指令和需求，可以被技能层和配置层约束        │
└─────────────────────────────────────────────────────┘

这种设计的关键在于：技能层可以「覆盖」用户的直接指令。比如用户说「快速实现这个功能」，但技能层规定必须先通过 brainstorming 环节，AI 就会先和用户确认需求细节，而不是直接写代码。

这解决了 AI 编程的核心痛点：用户的即时指令往往不完整，需要更高层级的规范来保证质量。

三、七步工作流：从想法到交付的完整链路

Superpowers 定义了一套严格的七步工作流，每一步都有明确的输入输出和执行规范：

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

核心问题：用户真正想做什么？

输入：用户的模糊想法或需求
处理：苏格拉底式提问，深入挖掘需求本质
输出：精炼后的设计文档，用户确认后进入下一步

这一步强制 AI 不直接写代码，而是先和用户对话。它会问：

• 「这个功能的目标用户是谁？」
• 「预期的使用场景有哪些？」
• 「有没有性能或安全方面的约束？」
• 「现有的架构是否需要调整？」

代码示例（技能触发条件）：

# skill: brainstorming

## 触发条件
- 用户提出新功能需求
- 需求描述超过 3 句话但缺少具体细节
- 涉及架构层面的决策

## 执行规范
1. 不允许直接生成代码
2. 必须提出至少 3 个澄清问题
3. 问题必须涵盖：目标用户、使用场景、技术约束
4. 生成结构化的需求文档供用户确认
5. 用户确认后才可进入下一阶段

3.2 第二步：Git Worktrees（隔离工作空间）

核心问题：我们的代码基线干净吗？

输入：确认后的设计文档
处理：创建隔离的 Git worktree，验证基线测试通过
输出：干净的开发环境，不污染主分支

这一步的核心价值是风险隔离。AI 在实验性开发时，所有代码都在独立的 worktree 中，不会影响主分支。同时验证现有测试是否通过，确保基线是健康的。

# AI 自动执行的命令
git worktree add .worktrees/feature-auth -b feature/auth-module
cd .worktrees/feature-auth
npm test  # 验证基线测试通过

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

核心问题：如何把大任务拆成可执行的小任务？

输入：设计文档
处理：将任务拆分为 2-5 分钟可完成的子任务
输出：详细的实施计划，包含每个任务的预期输出

这一步强制 AI 进行「任务分解」。每个子任务都要满足：

• 单一职责
• 可在 2-5 分钟内完成
• 有明确的验证标准
• 独立可测试

计划示例：

## 实施计划：用户认证模块

### 任务 1：定义数据模型（预计 3 分钟）
- 创建 User 接口类型
- 定义认证状态枚举
- 验证：TypeScript 编译通过

### 任务 2：实现密码哈希工具（预计 4 分钟）
- 使用 bcrypt 实现 hash 和 verify
- 添加单元测试
- 验证：测试覆盖率达到 100%

### 任务 3：实现 JWT 生成与验证（预计 5 分钟）
- 创建 sign 和 verify 函数
- 处理过期逻辑
- 验证：集成测试通过

### 任务 4：实现登录接口（预计 4 分钟）
- 创建 /auth/login 路由
- 验证用户凭据
- 验证：API 测试通过

### 任务 5：实现注册接口（预计 4 分钟）
- 创建 /auth/register 路由
- 验证邮箱唯一性
- 验证：API 测试通过

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

核心问题：如何保证每个子任务的质量？

输入：实施计划
处理：为每个子任务派发独立的子 Agent 执行
输出：每个子任务的实现代码和测试

这是 Superpowers 最精妙的设计之一。每个子任务由独立的子 Agent 执行，执行完成后进行两阶段审查：

1. 规范符合性审查：检查是否符合项目的编码规范
2. 代码质量审查：检查是否有潜在的 bug 或性能问题

这种设计的优势：

• 隔离失败：一个子任务失败不影响其他
• 并行执行：独立任务可以并行处理
• 独立回滚：出问题的任务可以单独重做

3.5 第五步：Test-Driven Development（测试驱动开发）

核心问题：如何保证代码可靠性？

输入：子任务实现
处理：严格执行 RED-GREEN-REFACTOR 循环
输出：测试通过的代码

Superpowers 强制执行 TDD 的「铁律」：

1. 不写测试就不能写代码：测试必须在实现之前
2. 红灯才能写代码：测试失败后才能开始实现
3. 绿灯才能重构：测试通过后才能优化代码

RED     → 写一个失败的测试
GREEN   → 写最少的代码让测试通过
REFACTOR → 优化代码，保持测试通过

违规检测示例：

# skill: test-driven-development

## 约束规则
- 如果检测到代码变更但没有对应的测试变更 → 阻断流程
- 如果测试文件修改时间晚于实现文件 → 发出警告
- 如果测试覆盖率低于 80% → 阻断合并

## 强制行为
1. 先生成测试用例
2. 运行测试确认失败
3. 编写实现代码
4. 运行测试确认通过
5. 检查覆盖率

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

核心问题：代码质量达标吗？

输入：完成的实现代码
处理：自动化的预审查清单检查
输出：审查报告，关键问题必须解决

Superpowers 内置了一套预审查清单，包括：

• 安全问题：SQL 注入、XSS、敏感信息泄露
• 性能问题：N+1 查询、内存泄漏、无限循环风险
• 可维护性：命名规范、注释完整度、代码复杂度
• 测试覆盖：单元测试、集成测试、边界条件

审查门控机制：

// 预审查清单配置
const reviewChecklist = {
  security: [
    { id: 'sql-injection', severity: 'blocker', description: '检查 SQL 拼接' },
    { id: 'xss', severity: 'blocker', description: '检查用户输入转义' },
    { id: 'secrets', severity: 'blocker', description: '检查敏感信息硬编码' }
  ],
  performance: [
    { id: 'n-plus-one', severity: 'warning', description: '检查循环中的数据库查询' },
    { id: 'memory-leak', severity: 'warning', description: '检查事件监听器是否解绑' }
  ],
  maintainability: [
    { id: 'naming', severity: 'info', description: '检查命名规范' },
    { id: 'complexity', severity: 'warning', description: '检查函数复杂度' }
  ]
};

// 门控逻辑
function gateReview(results) {
  const blockers = results.filter(r => r.severity === 'blocker' && !r.passed);
  if (blockers.length > 0) {
    return {
      passed: false,
      message: `发现 ${blockers.length} 个阻断性问题，必须解决后才能继续`,
      issues: blockers
    };
  }
  return { passed: true };
}

3.7 第七步：Finishing（收尾交付）

核心问题：如何安全地合并代码？

输入：审查通过的代码
处理：合并到主分支或创建 PR
输出：完成的功能模块

这一步提供三个选项：

1. 直接合并：合并到当前分支
2. 创建 PR：生成 Pull Request，等待人工审查
3. 丢弃变更：放弃这次实验

四、技能系统架构深度解析

4.1 技能文件格式设计

每个技能都是一个独立的 Markdown 文件（SKILL.md），包含以下结构：

---
skill: brainstorming
version: 2.1.0
priority: 100
triggers:
  - new_feature_request
  - architecture_decision
  - requirement_ambiguous
dependencies:
  - core:filesystem
  - core:git
---

# Brainstorming Skill

## 目标
在编码之前，通过苏格拉底式提问澄清需求。

## 触发条件
- 用户提出新功能需求
- 需求描述模糊或缺少关键细节

## 执行步骤
1. 分析用户输入，识别缺失信息
2. 生成 3-5 个澄清问题
3. 等待用户回答
4. 整合信息，生成需求文档
5. 请求用户确认

## 输出格式
- 结构化的需求文档
- 明确的功能边界
- 技术约束清单

## 约束
- 不允许在此阶段生成代码
- 问题必须涵盖：用户、场景、约束三个维度

4.2 技能发现机制

Superpowers 使用三层技能发现机制：

项目级技能 (.claude/skills/)
    ↓ 优先级最高，针对当前项目的定制化需求
个人级技能 (~/.claude/skills/)
    ↓ 中等优先级，用户自定义的工作流
基础技能库 (superpowers/skills/)
    ↓ 最低优先级，标准技能集合

当 AI 接收到任务时，它会：

1. 扫描所有可用技能
2. 根据触发条件匹配合适的技能
3. 按优先级排序
4. 执行最高优先级的技能

4.3 技能强制调用规则

Superpowers 使用Hook 机制在关键决策点拦截 AI 行为：

// 核心拦截逻辑
const hooks = {
  'pre-code-generation': ['brainstorming', 'writing-plans'],
  'pre-file-write': ['file-safety-check', 'import-validation'],
  'pre-commit': ['test-coverage-check', 'lint-check'],
  'post-task-complete': ['self-improvement', 'memory-update']
};

function intercept(action, context) {
  const requiredSkills = hooks[action];
  if (requiredSkills) {
    for (const skill of requiredSkills) {
      const result = executeSkill(skill, context);
      if (result.shouldBlock) {
        return { blocked: true, reason: result.message };
      }
    }
  }
  return { blocked: false };
}

五、核心技能模块详解

5.1 设计思维技能组

brainstorming 技能

将模糊想法转化为清晰设计方案，通过苏格拉底式提问深入挖掘需求本质。

提问模板：

┌────────────────────────────────────────────────────┐
│                    用户视角                          │
├────────────────────────────────────────────────────┤
│ Q1: 这个功能的主要用户是谁？                          │
│ Q2: 用户在什么场景下会使用这个功能？                   │
│ Q3: 用户期望达到什么目标？                            │
└────────────────────────────────────────────────────┘

┌────────────────────────────────────────────────────┐
│                    技术视角                          │
├────────────────────────────────────────────────────┤
│ Q4: 现有架构是否支持这个功能？需要调整吗？              │
│ Q5: 有没有性能或安全方面的约束？                      │
│ Q6: 依赖哪些外部服务或库？                           │
└────────────────────────────────────────────────────┘

┌────────────────────────────────────────────────────┐
│                    边界视角                          │
├────────────────────────────────────────────────────┤
│ Q7: 这个功能不包含什么？                             │
│ Q8: 未来可能的扩展方向有哪些？                        │
│ Q9: 什么时候算「完成」？                             │
└────────────────────────────────────────────────────┘

writing-plans 技能

创建详细的实施计划，将大任务分解为 2-5 分钟可完成的子任务。

任务拆分原则：

def split_task(task):
    """将任务拆分为原子级子任务"""
    subtasks = []
    
    # 1. 识别任务类型
    task_type = classify_task(task)
    
    # 2. 根据类型应用拆分模板
    if task_type == 'api_endpoint':
        subtasks = [
            '定义请求/响应类型',
            '实现路由处理器',
            '添加输入验证',
            '编写单元测试',
            '编写集成测试',
            '更新 API 文档'
        ]
    elif task_type == 'ui_component':
        subtasks = [
            '设计组件结构',
            '实现基础布局',
            '添加交互逻辑',
            '处理边界状态',
            '编写组件测试',
            '添加 Storybook 示例'
        ]
    
    # 3. 验证每个子任务的可完成性
    for subtask in subtasks:
        if estimate_time(subtask) > 5:  # 分钟
            subtasks.extend(split_task(subtask))
            subtasks.remove(subtask)
    
    return subtasks

5.2 开发执行技能组

subagent-driven-development 技能

采用双阶段审查机制，先确保规范符合性，再评估代码质量。

子 Agent 派发流程：

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  主 Agent    │────→│ 任务队列      │────→│  子 Agent    │
│  (协调者)    │     │ (优先级排序)  │     │  (执行者)    │
└──────────────┘     └──────────────┘     └──────────────┘
       ↑                                          │
       │                                          ↓
       │              ┌──────────────┐     ┌──────────────┐
       └──────────────│ 结果汇总      │←────│ 两阶段审查   │
                      └──────────────┘     └──────────────┘

双阶段审查实现：

async function reviewCode(code, context) {
  // 第一阶段：规范符合性审查
  const styleReview = await checkCodeStyle(code, context.styleGuide);
  const importReview = await checkImports(code, context.dependencies);
  const namingReview = await checkNaming(code, context.conventions);
  
  const phase1Passed = styleReview.passed && importReview.passed && namingReview.passed;
  
  if (!phase1Passed) {
    return {
      passed: false,
      phase: 1,
      issues: [...styleReview.issues, ...importReview.issues, ...namingReview.issues]
    };
  }
  
  // 第二阶段：代码质量审查
  const securityReview = await checkSecurity(code);
  const performanceReview = await checkPerformance(code);
  const maintainabilityReview = await checkMaintainability(code);
  
  const phase2Passed = securityReview.passed && performanceReview.passed;
  
  return {
    passed: phase2Passed,
    phase: 2,
    issues: [...securityReview.issues, ...performanceReview.issues, ...maintainabilityReview.issues],
    warnings: maintainabilityReview.warnings
  };
}

test-driven-development 技能

严格执行 RED-GREEN-REFACTOR 循环，保障代码可靠性和可维护性。

TDD 执行监控：

class TDDMonitor {
  constructor() {
    this.state = 'INIT';
    this.testFile = null;
    this.implFile = null;
  }
  
  async onFileChange(file, content) {
    const isTestFile = file.endsWith('.test.ts') || file.endsWith('.spec.ts');
    
    if (isTestFile && this.state === 'INIT') {
      this.testFile = file;
      const result = await this.runTests();
      if (!result.passed) {
        this.state = 'RED';
        console.log('✅ 正确：测试失败，可以开始实现');
      } else {
        console.log('⚠️ 警告：测试已通过，请确保测试是失败的');
      }
    }
    
    if (!isTestFile && this.state === 'RED') {
      this.implFile = file;
      const result = await this.runTests();
      if (result.passed) {
        this.state = 'GREEN';
        console.log('✅ 测试通过，可以开始重构');
      }
    }
    
    if (this.state === 'GREEN') {
      const result = await this.runTests();
      if (!result.passed) {
        console.log('❌ 错误：重构导致测试失败');
        this.state = 'RED';
      }
    }
  }
  
  async runTests() {
    // 执行测试命令
    return { passed: true, coverage: 85 };
  }
}

5.3 质量保障技能组

systematic-debugging 技能

四阶段根本原因分析流程，从症状追踪到根源解决。

调试流程：

阶段 1：症状收集
    ├── 记录错误信息
    ├── 记录复现步骤
    └── 收集环境信息

阶段 2：假设生成
    ├── 分析可能的原因
    ├── 排序假设（按可能性）
    └── 设计验证实验

阶段 3：验证排查
    ├── 执行验证实验
    ├── 收集实验结果
    └── 更新假设列表

阶段 4：根因修复
    ├── 定位根本原因
    ├── 实施修复方案
    └── 添加回归测试

调试技能示例：

# skill: systematic-debugging

## 触发条件
- 测试失败
- 运行时错误
- 用户报告 bug

## 执行流程

### 阶段 1：症状收集
1. 收集完整的错误堆栈
2. 记录输入数据和预期输出
3. 记录实际输出和错误信息
4. 确认复现步骤

### 阶段 2：假设生成
根据错误类型生成假设列表：

| 错误类型 | 常见假设 |
|---------|---------|
| TypeError | 变量为 null/undefined、类型转换错误 |
| ReferenceError | 变量未声明、作用域问题 |
| SyntaxError | 括号不匹配、关键字拼写错误 |
| 逻辑错误 | 边界条件、状态管理、并发问题 |

### 阶段 3：验证排查
为每个假设设计最小验证实验。

### 阶段 4：修复验证
1. 实施修复
2. 验证原问题已解决
3. 添加回归测试
4. 检查是否有类似问题

## 约束
- 不允许通过 try-catch 隐藏错误
- 必须找到根本原因，不能只修复症状
- 每个修复必须添加对应的测试

requesting-code-review 技能

预审查清单机制，关键问题必须解决才能继续推进。

审查清单示例：

code_review_checklist:
  security:
    - id: sql-injection
      description: 检查是否使用参数化查询
      severity: blocker
      pattern: "SELECT.*\\+|INSERT.*\\+|UPDATE.*\\+|DELETE.*\\+"
    
    - id: xss
      description: 检查用户输入是否转义
      severity: blocker
      patterns:
        - "innerHTML\\s*="
        - "dangerouslySetInnerHTML"
    
    - id: hardcoded-secrets
      description: 检查是否硬编码密钥
      severity: blocker
      pattern: "(password|secret|token|key)\\s*=\\s*['\"]"

  performance:
    - id: n-plus-one
      description: 检查循环中的数据库查询
      severity: warning
      
    - id: memory-leak
      description: 检查事件监听器是否解绑
      severity: warning
      pattern: "addEventListener(?!.*removeEventListener)"

  testing:
    - id: test-coverage
      description: 检查测试覆盖率
      severity: warning
      threshold: 80
      
    - id: edge-cases
      description: 检查边界条件测试
      severity: info

六、多 Agent 协作架构

6.1 子 Agent 模型选择策略

Superpowers 支持为不同类型的子任务选择不同能力的模型：

const modelSelection = {
  // 高复杂度任务：架构设计、复杂算法
  'architecture': {
    model: 'claude-opus-4',
    reason: '需要更强的推理能力'
  },
  
  // 中等复杂度任务：常规功能开发
  'feature': {
    model: 'claude-sonnet-4',
    reason: '平衡速度和质量'
  },
  
  // 低复杂度任务：简单脚本、配置修改
  'utility': {
    model: 'claude-haiku-3.5',
    reason: '快速执行，节省成本'
  },
  
  // 审查任务：代码审查、安全检查
  'review': {
    model: 'claude-sonnet-4',
    reason: '需要全面的分析能力'
  }
};

function selectModel(taskType, complexity) {
  if (complexity === 'high') {
    return modelSelection[taskType].model;
  }
  // 复杂度降低时可以使用更轻量的模型
  return downgradeIfNeeded(modelSelection[taskType].model, complexity);
}

6.2 任务调度与结果汇总

class AgentOrchestrator {
  constructor() {
    this.taskQueue = [];
    this.agents = new Map();
    this.results = new Map();
  }
  
  async executePlan(plan) {
    // 1. 构建任务依赖图
    const dependencyGraph = this.buildDependencyGraph(plan.tasks);
    
    // 2. 拓扑排序获取执行顺序
    const executionOrder = this.topologicalSort(dependencyGraph);
    
    // 3. 并行执行无依赖的任务
    const batches = this.groupIntoBatches(executionOrder, dependencyGraph);
    
    for (const batch of batches) {
      const promises = batch.map(task => this.dispatchAgent(task));
      await Promise.all(promises);
    }
    
    // 4. 汇总结果
    return this.aggregateResults();
  }
  
  async dispatchAgent(task) {
    const model = selectModel(task.type, task.complexity);
    const agent = new SubAgent(model);
    
    const result = await agent.execute(task);
    
    // 两阶段审查
    const review = await reviewCode(result.code, this.context);
    
    if (!review.passed) {
      // 标记任务失败，不阻塞其他任务
      this.results.set(task.id, { success: false, review });
    } else {
      this.results.set(task.id, { success: true, code: result.code });
    }
  }
}

七、安装与配置指南

7.1 快速安装

Claude Code（推荐）：

# 方法 1：通过官方插件市场安装
claude plugin install superpowers@claude-plugins-official

# 方法 2：通过项目市场安装
claude plugin marketplace add obra/superpowers-marketplace
claude plugin install superpowers@superpowers-marketplace

Cursor：

# 在项目根目录创建 .cursor/skills/superpowers
mkdir -p .cursor/skills
git clone https://github.com/obra/superpowers.git .cursor/skills/superpowers

7.2 验证安装

安装成功后，输入以下命令验证：

/superpowers:help

你应该看到以下可用命令：

/superpowers:brainstorm     # 开始头脑风暴
/superpowers:write-plan     # 编写开发计划
/superpowers:execute-plan   # 执行开发计划
/superpowers:review         # 代码审查
/superpowers:debug          # 系统化调试

7.3 项目级配置

在项目根目录创建 .claude/skills/ 目录，可以添加项目特定的技能：

# .claude/skills/project-conventions.md

---
skill: project-conventions
priority: 150  # 高于默认技能
triggers:
  - file_create
  - file_modify
---

# 项目约定

## 代码风格
- 使用 ESLint + Prettier
- 组件使用 PascalCase 命名
- 函数使用 camelCase 命名
- 常量使用 UPPER_SNAKE_CASE

## 技术栈
- 前端：React 19 + TypeScript 5
- 状态管理：Zustand
- 样式：Tailwind CSS
- 测试：Vitest + Testing Library

## API 约定
- RESTful 风格
- 响应格式：{ data, error, meta }
- 错误码：HTTP 状态码 + 业务错误码

八、与同类框架对比

核心差异：Superpowers 是唯一一个提供完整工作流强制执行和多 Agent 协作能力的框架，其他工具更多是提供「建议」而非「约束」。

九、实战案例：从零构建用户认证模块

让我们通过一个完整案例，看看 Superpowers 如何改变 AI 编程体验。

9.1 传统方式 vs Superpowers 方式

传统方式：

用户：帮我实现用户认证模块

AI：好的，我来实现...

[AI 直接开始写代码，30 分钟后]
- 写了 500 行代码
- 没有测试
- 没有考虑错误处理
- API 设计不符合 RESTful
- 用户发现需要重做

Superpowers 方式：

用户：帮我实现用户认证模块

AI：[触发 brainstorming 技能]
在开始之前，我需要了解一些细节：

1. 这个认证模块的目标用户是？
   - 管理员？普通用户？还是两者都有？

2. 需要支持哪些登录方式？
   - 用户名密码？邮箱验证？第三方登录？

3. 有什么安全要求？
   - 密码强度？登录失败次数限制？Token 过期时间？

用户：
1. 普通用户
2. 邮箱 + 密码登录
3. 密码至少 8 位，包含大小写字母和数字

AI：[触发 writing-plans 技能]
根据您的需求，我制定了以下计划：

### 任务 1：定义数据模型（3 分钟）
- User 类型定义
- 认证状态枚举
- 验证：TypeScript 编译通过

### 任务 2：实现密码工具（4 分钟）
- bcrypt hash 函数
- bcrypt verify 函数
- 单元测试
- 验证：测试通过，覆盖率 100%

### 任务 3：实现 JWT 工具（5 分钟）
- sign 函数
- verify 函数
- 过期处理
- 单元测试
- 验证：测试通过

... 共 8 个任务

用户：计划看起来不错，开始执行

AI：[触发 execute-plan 技能]
创建 Git worktree: .worktrees/auth-module
验证基线测试通过 ✓

[子 Agent 1] 执行任务 1...
[子 Agent 2] 执行任务 2...
...

[两阶段审查]
阶段 1 - 规范符合性：✓
阶段 2 - 代码质量：发现 1 个警告
- 函数复杂度超过阈值，建议拆分

所有测试通过 ✓ 覆盖率 92%

9.2 关键代码示例

JWT 工具实现：

// src/auth/jwt.ts
import jwt from 'jsonwebtoken';

const JWT_SECRET = process.env.JWT_SECRET!;
const JWT_EXPIRES_IN = '7d';

export interface TokenPayload {
  userId: string;
  email: string;
}

export function signToken(payload: TokenPayload): string {
  return jwt.sign(payload, JWT_SECRET, { expiresIn: JWT_EXPIRES_IN });
}

export function verifyToken(token: string): TokenPayload | null {
  try {
    return jwt.verify(token, JWT_SECRET) as TokenPayload;
  } catch {
    return null;
  }
}

对应的测试：

// src/auth/jwt.test.ts
import { describe, it, expect, beforeEach } from 'vitest';
import { signToken, verifyToken } from './jwt';

describe('JWT Tools', () => {
  beforeEach(() => {
    process.env.JWT_SECRET = 'test-secret';
  });

  it('should sign and verify token', () => {
    const payload = { userId: '123', email: 'test@example.com' };
    const token = signToken(payload);
    const decoded = verifyToken(token);
    
    expect(decoded).toMatchObject(payload);
  });

  it('should return null for invalid token', () => {
    const result = verifyToken('invalid-token');
    expect(result).toBeNull();
  });

  it('should include expiration', () => {
    const payload = { userId: '123', email: 'test@example.com' };
    const token = signToken(payload);
    const decoded = jwt.decode(token) as jwt.JwtPayload;
    
    expect(decoded.exp).toBeDefined();
  });
});

十、性能优化与 Token 效率

10.1 Token 消耗优化

Superpowers 的技能系统可以显著降低 Token 消耗：

// 传统方式：每次对话都要重复说明约束
const traditionalPrompt = `
You are a helpful coding assistant.
Please follow these rules:
1. Always write tests first
2. Use TypeScript strict mode
3. Follow our coding style guide...
[重复 500+ tokens 的规则]

Now help me implement user authentication...
`;

// Superpowers 方式：技能只加载一次
const superpowersPrompt = `
Use skill: test-driven-development
Use skill: project-conventions

Implement user authentication...
`;

实测效果：

10.2 技能懒加载

Superpowers 使用按需加载策略，只在需要时加载相关技能：

class SkillLoader {
  constructor() {
    this.loadedSkills = new Set();
    this.skillRegistry = new Map();
  }
  
  async loadSkill(skillName) {
    if (this.loadedSkills.has(skillName)) {
      return; // 已加载，跳过
    }
    
    const skill = await this.fetchSkill(skillName);
    this.skillRegistry.set(skillName, skill);
    this.loadedSkills.add(skillName);
  }
  
  async onTaskStart(task) {
    // 根据任务类型预加载相关技能
    const requiredSkills = this.analyzeRequiredSkills(task);
    await Promise.all(requiredSkills.map(s => this.loadSkill(s)));
  }
}

十一、最佳实践与常见陷阱

11.1 最佳实践

1. 始终使用 brainstorming：不要跳过需求澄清阶段
2. 保持任务粒度：每个子任务控制在 2-5 分钟
3. 写好测试用例：TDD 的核心是测试先行
4. 定期审查技能：删除不再需要的技能，避免 Token 浪费
5. 项目级定制：为项目创建特定的技能文件

11.2 常见陷阱

1. 过度依赖 AI：Superpowers 是工具，不是替代品
2. 忽略审查警告：警告可能演变成严重问题
3. 技能冲突：多个技能可能有重叠行为，注意优先级
4. 测试覆盖率陷阱：高覆盖率不等于高质量测试

十二、总结与展望

Superpowers 代表了 AI 编程工具从「代码生成器」向「工程搭档」演进的重要一步。它通过结构化的技能系统和强制执行的工作流，让 AI 编程 Agent 遵循专业的软件工程实践。

核心价值：

• ✅ 提升代码质量：TDD 强制执行、自动化审查
• ✅ 降低风险：Git worktree 隔离、分阶段验证
• ✅ 提高效率：任务并行、Token 优化
• ✅ 积累经验：技能可复用、知识可沉淀

未来方向：

• 更多 AI 编程工具的支持
• 更智能的技能推荐系统
• 团队协作能力增强
• 与 CI/CD 深度集成

如果你正在使用 AI 编程工具，Superpowers 值得一试。它不会让 AI 替代你，但会让 AI 成为更可靠的队友。

参考资源：

• GitHub 仓库：https://github.com/obra/superpowers
• 官方文档：https://superpowers.dev
• 技能市场：https://github.com/obra/superpowers-marketplace
• 社区讨论：https://github.com/obra/superpowers/discussions