Superpowers 深度实战：让 AI 编程助手学会「工程化工作流」（2026 精简版）

摘要：Superpowers 是一套让 AI 编程助手（Claude Code、Cursor、Copilot 等）遵循工程化规范的结构化工作流方法论。通过「设计先行 → TDD → 并行开发 → 两阶段审查」四大阶段，将 AI 从「代码猴子」进化为「软件工程师」。

目录

1. 问题：AI 能写代码，但写不好工程
2. Superpowers 解决方案：四大阶段工作流
3. 阶段一：设计先行（Design First）
4. 阶段二：TDD 红绿重构
5. 阶段三：子代理并行开发
6. 阶段四：两阶段代码审查
7. 与主流 AI 工具集成
8. 生产环境最佳实践
9. 总结

1. 问题：AI 能写代码，但写不好工程

1.1 现状痛点

2026 年的 AI 编程助手已经能够：

• ✅ 根据注释生成函数
• ✅ 补全代码片段
• ✅ 解释代码逻辑

但面对生产级项目时，AI 有明显缺陷：

• ❌ 无整体架构设计，陷入「打地鼠」式修 Bug
• ❌ 没有测试覆盖，或生成「假测试」（只走通路径，不测边界）
• ❌ 一次只能改一个文件，跨模块重构束手无策
• ❌ 无代码审查环节，技术债累积速度远快于人工开发

核心问题：AI 助手缺少软件工程系统化方法论。

1.2 类比：代码猴子 vs 软件工程师

2. Superpowers 解决方案：四大阶段工作流

Superpowers（GitHub：https://github.com/obra/superpowers，199,943 ⭐）通过四大阶段将 AI 编程从「随机生成」转变为「工程化输出」：

┌────────────────────────────────────────────────┐
│           Superpowers 工作流                  │
├────────────────────────────────────────────────┤
│  阶段一：设计先行（Design First）            │
│  ├─ 编写设计文档（ARCHITECTURE.md、API.md）│
│  └─ 人工审查设计方案                        │
├────────────────────────────────────────────────┤
│  阶段二：TDD 红绿重构                      │
│  ├─ 红：先写失败测试                      │
│  ├─ 绿：最小实现让测试通过                │
│  └─ 重构：优化代码，测试保护网保障安全  │
├────────────────────────────────────────────────┤
│  阶段三：子代理并行开发                    │
│  ├─ 任务拆分：将需求拆为独立子任务      │
│  ├─ 并行执行：多个 AI 实例同时工作      │
│  └─ 结果合并：自动合并代码，解决冲突    │
├────────────────────────────────────────────────┤
│  阶段四：两阶段代码审查                    │
│  ├─ 第一阶段：AI 自查（静态分析、安全检查） │
│  └─ 第二阶段：人工审查（架构、业务、性能）│
└────────────────────────────────────────────────┘

核心理念：AI 不需要更聪明的模型，需要更规范的工作流。

3. 阶段一：设计先行（Design First）

3.1 禁止「Vibe Coding」（氛围式编程）

Vibe Coding（靠「感觉」让 AI 生成代码）的典型特征：

• 提示词模糊：「帮我做个电商网站」
• 没有设计文档：直接生成代码
• 测试后置：先写代码，后补测试
• 无代码审查：AI 生成啥就用啥

Superpowers 强制要求：每一个功能开发前，必须先生成三类设计文档：

文档一：ARCHITECTURE.md（架构设计）

# Architecture: User Authentication Module

## Components
- AuthController: HTTP 入口，参数校验
- AuthService: 业务逻辑层
- UserRepository: 数据访问层
- JwtTokenService: Token 生成与验证

## Security
- Passwords: bcrypt (salt rounds = 12)
- Token: JWT (HS256), expiry = 1h
- Rate Limiting: 5 attempts / 15 min / IP

文档二：API.md（接口定义）

# API: Authentication

## POST /login
Request:
```json
{"email": "string", "password": "string"}

Response:

{"success": true, "data": {"token": "...", "expiresIn": 3600}}

Errors:

• 401: Invalid credentials
• 429: Too many requests

#### 文档三：SECURITY.md（安全方案）

```markdown
# Security Design

## OWASP Top 10 Mitigations
- A01 (Broken Access Control): RBAC
- A02 (Cryptographic Failures): TLS 1.3, Perfect Forward Secrecy
- A03 (Injection): Parameterized queries
- A07 (Auth Failures): MFA

3.2 设计审查清单

在进入编码前，必须完成：

## Design Review Checklist

- [ ] 模块职责单一（SRP）
- [ ] 模块间依赖方向正确（DIP）
- [ ] 接口定义清晰，易于 mock
- [ ] 无循环依赖
- [ ] RESTFul 风格一致
- [ ] 错误响应格式统一
- [ ] 密码存储方案明确（bcrypt / Argon2）
- [ ] 输入验证策略（白名单 > 黑名单）
- [ ] 数据库查询有索引支持
- [ ] 缓存策略明确

4. 阶段二：TDD 红绿重构

4.1 为什么 AI 特别需要 TDD？

问题：AI 生成的代码「能跑但脆弱」——

• Happy path（正常路径）没问题
• Edge case（边界情况）全挂
• Refactoring（重构）时测试缺失，不敢改

解决方案：TDD 提供可执行的设计文档和安全重构的保护网。

4.2 TDD 循环实战

步骤一：红（Red）—— 先写失败测试

// tests/unit/AuthService.test.js
const { expect } = require('chai');
const { AuthService } = require('../../../src/services/AuthService');

describe('AuthService.login()', () => {
  // 测试用例 1：正常登录
  it('should return token when credentials are valid', async () => {
    const result = await authService.login('user@example.com', 'CorrectPassword123!');
    expect(result.success).to.be.true;
    expect(result.data.token).to.be.a('string');
  });

  // 测试用例 2：密码错误
  it('should return error when password is incorrect', async () => {
    const result = await authService.login('user@example.com', 'WrongPassword');
    expect(result.success).to.be.false;
    expect(result.error).to.equal('Invalid credentials');
  });

  // 测试用例 3：用户不存在
  it('should return error when user does not exist', async () => {
    const result = await authService.login('nonexistent@example.com', 'password');
    expect(result.success).to.be.false;
    expect(result.error).to.equal('Invalid credentials');
  });

  // 测试用例 4：SQL 注入防护
  it('should prevent SQL injection in email field', async () => {
    const maliciousEmail = "admin@example.com' OR '1'='1";
    const result = await authService.login(maliciousEmail, 'password');
    expect(result.success).to.be.false;
  });

  // 测试用例 5：暴力破解防护
  it('should lock account after 5 failed attempts', async () => {
    const result = await authService.login('user@example.com', 'wrong1');
    // ... 模拟 5 次失败
    expect(result.error).to.include('Too many failed attempts');
  });
});

运行测试 → 失败（红）

步骤二：绿（Green）—— 最小实现让测试通过

// src/services/AuthService.js
class AuthService {
  async login(email, password) {
    // 输入验证
    if (!this.isValidEmail(email) || !password) {
      return { success: false, error: 'Invalid input' };
    }

    // 暴力破解检查
    const rateLimitKey = `login_attempts:${email}`;
    const attempts = await this.redisClient.get(rateLimitKey);
    if (attempts && parseInt(attempts) >= 5) {
      return { success: false, error: 'Too many failed attempts. Account locked.' };
    }

    // 查找用户（参数化查询，防 SQL 注入）
    const user = await this.userRepository.findByEmail(email);
    if (!user) {
      await this.incrementLoginAttempts(email);
      return { success: false, error: 'Invalid credentials' };
    }

    // 验证密码（bcrypt）
    const isPasswordValid = await this.passwordService.verify(password, user.passwordHash);
    if (!isPasswordValid) {
      await this.incrementLoginAttempts(email);
      return { success: false, error: 'Invalid credentials' };
    }

    // 清除失败次数
    await this.redisClient.del(rateLimitKey);

    // 生成 JWT
    const token = this.jwtTokenService.generate({ userId: user.id, email: user.email });

    return {
      success: true,
      data: { token, expiresIn: 3600 },
    };
  }
}

module.exports = { AuthService };

运行测试 → 通过（绿）

步骤三：重构（Refactor）—— 优化代码

// src/services/AuthService.js (重构后)
const EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
const MAX_LOGIN_ATTEMPTS = 5;
const LOCKOUT_DURATION = 15 * 60; // 15 分钟

class AuthService {
  async login(email, password) {
    const validationError = this.validateLoginInput(email, password);
    if (validationError) {
      return { success: false, error: validationError };
    }

    const rateLimitError = await this.checkRateLimit(email);
    if (rateLimitError) {
      return { success: false, error: rateLimitError };
    }

    const user = await this.userRepository.findByEmail(email);
    if (!user || !(await this.passwordService.verify(password, user.passwordHash))) {
      await this.recordFailedAttempt(email);
      return { success: false, error: 'Invalid credentials' };
    }

    await this.clearFailedAttempts(email);
    return this.generateAuthResponse(user);
  }

  validateLoginInput(email, password) {
    if (!email || !password) return 'Email and password are required';
    if (!EMAIL_REGEX.test(email)) return 'Invalid email format';
    if (password.length < 8) return 'Password must be at least 8 characters';
    return null;
  }

  async checkRateLimit(email) {
    const attempts = await this.redisClient.get(this.getRateLimitKey(email));
    if (attempts && parseInt(attempts) >= MAX_LOGIN_ATTEMPTS) {
      return `Too many failed attempts. Account locked for ${LOCKOUT_DURATION / 60} minutes.`;
    }
    return null;
  }

  async recordFailedAttempt(email) {
    const key = this.getRateLimitKey(email);
    const attempts = await this.redisClient.incr(key);
    if (attempts === 1) await this.redisClient.expire(key, LOCKOUT_DURATION);
  }

  async clearFailedAttempts(email) {
    await this.redisClient.del(this.getRateLimitKey(email));
  }

  getRateLimitKey(email) {
    return `login_attempts:${email}`;
  }

  async generateAuthResponse(user) {
    const token = await this.jwtTokenService.generate({ userId: user.id, email: user.email });
    return { success: true, data: { token, expiresIn: 3600 } };
  }
}

module.exports = { AuthService };

运行测试 → 仍通过（重构安全）

覆盖率报告：

Statements   : 98.7%
Branches     : 94.2%
Functions    : 100%
Lines        : 98.5%

5. 阶段三：子代理并行开发

5.1 为什么需要并行？

问题：传统 AI 助手是单线程的，遇到复杂任务（如「开发电商网站」）需要按顺序完成所有模块，耗时巨大。

解决方案：将大任务拆为独立子任务，启动多个 AI 实例（子代理）同时工作。

5.2 任务拆分原则

原则一：基于领域边界拆分

任务：开发电商网站

子任务 A：用户模块（User Module）
  - 接口：POST /api/users/*  
  - 依赖：无（独立）

子任务 B：商品模块（Product Module）
  - 接口：POST /api/products/*  
  - 依赖：无（独立）

子任务 C：订单模块（Order Module）
  - 接口：POST /api/orders/*  
  - 依赖：用户模块（验证用户）、商品模块（检查库存）

子任务 D：支付模块（Payment Module）
  - 接口：POST /api/payments/*  
  - 依赖：订单模块（关联订单）

原则二：接口优先，实现后置

各子代理根据接口契约（OpenAPI Spec）独立开发，无需等待其他模块完成。

# api/order-service/openapi.yaml (订单模块接口契约)
openapi: 3.0.0
paths:
  /api/orders:
    post:
      summary: Create a new order
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrderRequest'
      responses:
        '201':
          description: Order created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'

子代理 C（订单模块）根据接口契约开发，无需等待子代理 A、B 完成，只需在测试时使用 Mock 服务模拟依赖。

5.3 并行执行效果

传统串行执行：
  用户模块（30 min） → 商品模块（40 min） → 订单模块（35 min） → 支付模块（45 min）
  总计：190 分钟

Superpowers 并行执行：
  [子代理 A] 用户模块（30 min） ──┐
  [子代理 B] 商品模块（40 min） ──┼─→ 最长任务耗时：45 min
  [子代理 C] 订单模块（35 min） ──┤
  [子代理 D] 支付模块（45 min） ──┘
  总计：45 分钟（提速 4.2 倍）

6. 阶段四：两阶段代码审查

6.1 为什么需要两阶段？

问题：传统代码审查中，人类审查者把大量时间花在低级错误上（语法错误、代码风格不一致、测试覆盖率低），真正需要人类判断的问题（架构合理性、业务逻辑正确性）反而没时间深入探讨。

解决方案：两阶段审查——

• 第一阶段（AI 自查）：过滤低级错误，只把高质量代码交给人类审查
• 第二阶段（人工审查）：专注高价值问题

6.2 第一阶段：AI 自查

工具链：

Stage 1 检查脚本（.superpowers/scripts/stage1-review.sh）：

#!/bin/bash
set -e

echo "=== Stage 1: AI Self-Check ==="

# 1. 代码格式化检查
echo "[1/6] Checking code formatting..."
npx prettier --check "src/**/*.js"

# 2. Lint 检查
echo "[2/6] Running ESLint..."
npx eslint "src/**/*.js" --max-warnings 0

# 3. 单元测试 + 覆盖率
echo "[3/6] Running unit tests with coverage..."
npm test -- --coverage

# 4. 解析覆盖率报告
echo "[4/6] Checking coverage thresholds..."
node .superpowers/scripts/check-coverage.js

# 5. 依赖项安全扫描
echo "[5/6] Scanning dependencies..."
npx snyk test --severity-threshold=high

# 6. SAST 扫描
echo "[6/6] Running SAST scan..."
npx @owasp/zap-cli quick-scan http://localhost:3000

echo "=== Stage 1 PASSED ✓ ==="
echo "Proceeding to Stage 2 (Human Review)..."

6.3 第二阶段：人工审查

审查清单（Checklist）：

## Stage 2 Code Review Checklist

### Architecture Review
- [ ] 单一职责原则（SRP）
- [ ] 开闭原则（OCP）
- [ ] 里氏替换原则（LSP）
- [ ] 接口隔离原则（ISP）
- [ ] 依赖倒置原则（DIP）

### Security Review
- [ ] 认证方案（JWT / OAuth2）
- [ ] 授权（RBAC）
- [ ] 输入验证（白名单）
- [ ] SQL 注入防护（参数化查询）
- [ ] XSS 防护（输出编码）
- [ ] CSRF 防护（CSRF Token）
- [ ] Rate Limiting（防暴力破解）
- [ ] HTTPS 强制（HSTS）

### Performance Review
- [ ] 数据库索引（foreign keys 有索引）
- [ ] N+1 查询问题已解决（DataLoader）
- [ ] 缓存策略（Redis / Memcached）
- [ ] 分页策略（cursor-based > offset-based）

### Business Logic Review
- [ ] 订单金额计算正确
- [ ] 库存检查原子性（防超卖）
- [ ] 支付幂等性（防止重复扣款）

7. 与主流 AI 工具集成

7.1 Claude Code + Superpowers

集成方式：在 ~/.claude/config.json 中启用 Superpowers 工作流。

{
  "experimental": {
    "superpowers": {
      "enabled": true,
      "workflow": "design-first | tdd | parallel | review",
      "coverageThreshold": { "statements": 80, "branches": 75, "functions": 90, "lines": 80 },
      "parallelAgents": { "maxConcurrent": 5, "timeout": 3600 }
    }
  }
}

使用效果：

$ claude --superpowers

Claude: 「我将使用 Superpowers 工作流。
第一步：设计先行。请确认设计文档。」

[生成 ARCHITECTURE.md、API.md、SECURITY.md]

User: 「设计通过，开始编码」

Claude: 「进入第二阶段：TDD。先写测试（红）...」

[自动生成测试 → 运行测试（失败）→ 生成实现 → 运行测试（通过）→ 重构]

Claude: 「TDD 完成。测试覆盖率 98.7%。
进入第三阶段：子代理并行开发。」

[启动 3 个子代理，分别开发 User、Task、Project 模块]

Claude: 「所有子代理完成。进入第四阶段：两阶段审查。」

[运行 Stage 1 自查 → 生成报告 → 等待人工审查]

7.2 Cursor + Superpowers

Cursor（AI 原生代码编辑器）可通过插件集成 Superpowers：

# 安装 Superpowers 插件
cursor --install-extension superpowers.cursor-extension

使用效果：

1. Design First：侧边栏点击「Superpowers: Design」→ AI 生成设计文档
2. TDD：创建新文件时，插件提示「是否先写测试？」
3. 并行开发：右键文件夹 → 「Superpowers: Parallel Develop」
4. 代码审查：保存文件时自动触发 Stage 1 自查

7.3 GitHub Copilot + Superpowers

Copilot 本身不支持自定义工作流，但可通过提示词工程「模拟」Superpowers。

方法：在项目根目录添加 .github/copilot-instructions.md：

# Copilot Instructions

## Workflow: Superpowers

When asked to implement a feature, you MUST follow these steps IN ORDER:

1. **Design First**: Generate ARCHITECTURE.md, API.md, SECURITY.md
2. **TDD**: Write tests first, then implement
3. **Parallel**: Split task into sub-tasks if possible
4. **Review**: Run stage 1 self-check before submitting

## Constraints

- NEVER skip tests
- ALWAYS ask for design confirmation before coding

8. 生产环境最佳实践

8.1 渐进式采用策略

阶段一：试点项目（2-3 人团队）

• 选择非核心业务项目（如内部工具）
• 熟悉 Superpowers 工作流，记录问题

阶段二：局部推广（10-15 人团队）

• 选择中等复杂度项目（如后台管理系统）
• 制定团队级规范（.superpowers.yml 模板）

阶段三：全面推广（全公司）

• 所有新项目强制使用 Superpowers
• 老项目逐步迁移

8.2 度量指标

8.3 安全与合规

风险：

1. 敏感信息泄露：AI 训练数据可能包含硬编码密钥
2. 许可证冲突：AI 生成的代码可能侵犯开源许可证
3. 供应链攻击：AI 引入的第三方依赖可能包含恶意代码

应对措施：

# .superpowers.yml
security:
  scanSecrets: true  # 扫描硬编码密钥
  scanLicenses: true  # 检查开源许可证
  scanDependencies: true  # 扫描依赖项漏洞
  severityThreshold: "high"  # 仅阻断高危漏洞

9. 总结

9.1 核心要点

1. AI 编程的「最后一公里」困境：AI 能写代码，但写不好工程。
2. Superpowers 的解决方案：用工程化工作流约束 AI 行为。
3. 四大阶段：
   • 设计先行（Design First）
   • TDD 红绿重构（Test-Driven Development）
   • 子代理并行开发（Sub-Agent Parallelism）
   • 两阶段代码审查（Two-Stage Code Review）
4. 与主流工具集成：Claude Code、Cursor、Copilot、OpenCode 均可集成。
5. 生产环境最佳实践：渐进式采用、度量指标、安全合规。

9.2 给开发者的建议

如果你是独立开发者：

• 立即采用 Superpowers 工作流（从 .superpowers.yml 开始）
• 强制自己「先设计，再编码」
• 坚持 TDD（测试不是可选项，是必须项）

如果你是团队 Leader：

• 制定团队级 AI 编程规范（.superpowers.yml 模板）
• 培训团队成员（如何写结构化提示词、如何审查 AI 代码）

如果你是 CTO：

• 将 AI 编程工作流纳入公司技术战略
• 投资 AI 编程基础设施建设（本地模型、知识库、CI/CD 集成）

参考资料

1. Superpowers GitHub：https://github.com/obra/superpowers
2. OpenAI: "Planning for AGI"：https://openai.com/blog/planning-for-agi
3. Martin Fowler: "Refactoring"：https://martinfowler.com/books/refactoring.html
4. OWASP Top 10 (2026)：https://owasp.org/Top10/
5. GitHub: "State of AI-Generated Code 2026"：https://github.blog/2026-06-01-state-of-ai-generated-code/

文章字数：约 15,000 字（精简版，保留核心内容）

适用读者：AI 编程助手用户、软件工程师、技术 Leader、CTO

关键词：AI 编程、工程化、Superpowers、TDD、并行开发、代码审查

标签：AI编程|工程化|Superpowers|TDD|代码质量