obra/superpowers 深度实战：用工程纪律驯服 AI 编程 Agent——从 Prompt 工程到 Process 工程的范式转移

当你让 AI 写代码时，它更像是一个"会写代码的猴子"，还是一个"懂软件工程的工程师"？

obra/superpowers 给出了答案：不是提供更强的能力，而是施加更严的纪律。

目录

• 一、问题域：AI 编程的"能力悖论"
• 二、obra/superpowers 是什么？
• 三、核心哲学：Process over Prompt
• 四、20+ Skills 深度拆解
• 五、架构分析：Skills 如何注入 AI 工作流
• 六、代码实战：从零构建一个 Superpowers 式 Skill
• 七、生产级实践：TDD 强制、子 Agent 协作、代码审查
• 八、与 Claude Code / Codex / Cursor 的集成实战
• 九、性能与成本分析：纪律如何节省 Token
• 十、总结与展望：AI 软件工程的下一个范式

一、问题域：AI 编程的"能力悖论"

1.1 现状：能力越强，输出越乱

2025-2026 年，AI 编程工具的能力呈指数级增长：

• Claude 3.7 / 4.0：可以生成复杂的企业级代码
• Cursor / Windsurf：实时代码补全 + 多文件编辑
• GitHub Copilot：深度集成 IDE，支持 Chat + CLI
• Devin / OpenHands：自主完成 Issue、PR

但现实是：能力越强，代码质量越不可控。

典型失败模式：

用户："帮我做一个用户登录功能"
AI：直接输出 500 行代码（无测试、无验证、无设计文档）
用户："跑不起来"
AI：修一个 bug，引入两个新 bug
用户："算了我自己写"

1.2 根本原因：缺乏软件工程纪律

AI 的训练数据是"所有代码"，但不是"所有好的软件工程实践"。

它知道怎么写代码，但不知道：

• ✅ 先写测试再写实现（TDD）
• ✅ 先拆解任务再动手（Task Decomposition）
• ✅ 先设计方案再编码（Design First）
• ✅ 代码写完后做 Self-Review（Quality Gate）

obra/superpowers 的本质：不是教 AI "怎么写代码"，而是强制 AI "按工程规范写代码"。

二、obra/superpowers 是什么？

2.1 项目背景

2.2 一句话定义

Superpowers 是一套专为 AI 编程 Agent 打造的"完整软件开发方法论"，通过 20+ 个可自动触发的"技能"（Skills），让 AI 从"会写代码"升级为"懂软件工程"。

2.3 它不是什么

三、核心哲学：Process over Prompt

3.1 范式转移

传统 AI 编程（Prompt Engineering）：
  用户提示 → AI 生成代码 → 结束
  ❌ 无规范、无验证、无质量保证

Superpowers（Process Engineering）：
  用户提示 → 设计文档 → 任务拆解 → 写测试 → 写代码 → 验证 → 审查 → 结束
  ✅ 完整软件工程生命周期（SDLC）

3.2 核心理念

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

• 不管 AI 的模型能力多强，强制遵循工程流程
• 用不可跳过的检查点（Quality Gates）约束 AI 行为
• 让 AI 像资深工程师一样：先思考、再规划、后编码、必验证

3.3 纪律的具体体现

Superpowers 通过以下"工程纪律"驯服 AI：

四、20+ Skills 深度拆解

Superpowers 的核心是一系列 Skill 文件（Markdown 格式的指令集），每个 Skill 负责一个特定的工程实践。

4.1 Skill 文件结构

每个 Skill 是一个 SKILL.md 文件，结构如下：

---
name: skill-name
description: 技能描述，AI 根据此描述决定是否触发该技能
trigger: 触发条件（关键词、场景）
---

# Skill Name

## 目标
...

## 执行步骤
1. ...
2. ...
3. ...

## 质量标准
- ...
- ...

## 示例
...

4.2 核心 Skills 列表（部分）

🧠 设计与规划类

✅ 质量保障类

🤖 协作与并行类

📝 文档与沟通类

4.3 一个 Skill 的完整示例：tdd-workflow

---
name: tdd-workflow
description: 强制 TDD 流程——先写失败测试，再写实现代码，最后重构
trigger: 任何涉及编写新功能代码的场景
---

# TDD Workflow

你是一个严格遵守 TDD 原则的资深工程师。在编写任何功能代码之前，必须遵循以下流程：

## 强制步骤

### Step 1: RED——写失败测试
- 根据当前任务，先写出一个会**失败**的测试用例
- 测试必须描述清楚预期行为
- 运行测试，确认测试失败（RED）

### Step 2: GREEN——写最小实现
- 写出**刚好能让测试通过**的最小代码
- 不要过度设计（YAGNI 原则）
- 运行测试，确认测试通过（GREEN）

### Step 3: REFACTOR——重构优化
- 在测试通过的前提下，重构代码
- 提高代码质量（命名、结构、性能）
- 确保重构后测试仍然通过

### Step 4: 循环
- 对每个子任务重复 Step 1-3
- 所有测试通过后，进入代码审查

## 禁止行为
❌ 跳过测试直接写实现代码
❌ 一次性写多个测试再写实现（应小步迭代）
❌ 在 RED 阶段就写"完美"实现

## 质量标准
✅ 测试覆盖率 ≥ 80%
✅ 每个测试都有明确的断言
✅ 测试名称清晰描述被测行为

五、架构分析：Skills 如何注入 AI 工作流

5.1 整体架构

┌─────────────────────────────────────────────────────┐
│                  用户请求                            │
│  "帮我实现一个用户认证模块"                          │
└──────────────────┬──────────────────────────────────┘
                   ▼
┌─────────────────────────────────────────────────────┐
│         Superpowers 技能匹配引擎                     │
│  - 扫描 20+ SKILL.md 文件                          │
│  - 根据请求内容匹配相关 Skills                       │
│  - 按优先级排序触发序列                              │
└──────────────────┬──────────────────────────────────┘
                   ▼
┌─────────────────────────────────────────────────────┐
│               Skill 执行流水线                       │
│                                                     │
│  1. brainstorming Skill → 生成设计文档               │
│  2. writing-plans Skill → 拆解任务                  │
│  3. task-decomposition Skill → 细化到 2-5min 子任务 │
│  4. tdd-workflow Skill → 对每个子任务强制 TDD       │
│  5. code-review Skill → 完成后审查                  │
│  6. documentation Skill → 生成文档                   │
│                                                     │
└──────────────────┬──────────────────────────────────┘
                   ▼
┌─────────────────────────────────────────────────────┐
│              最终输出                                │
│  - 设计文档 + 任务计划 + 测试 + 实现代码            │
│  - 代码审查报告 + API 文档                          │
└─────────────────────────────────────────────────────┘

5.2 Skills 的触发机制

Superpowers 通过 文件系统监控 + 提示词注入 实现 Skills 的自动触发：

机制 1：文件系统监控（File System Watch）

~/.claude/skills/
  ├── brainstorming/SKILL.md
  ├── tdd-workflow/SKILL.md
  ├── code-review/SKILL.md
  └── ...

AI Agent（如 Claude Code）启动时会：

1. 扫描 ~/.claude/skills/ 目录
2. 读取所有 SKILL.md 文件
3. 将 Skills 内容注入系统提示词（System Prompt）

机制 2：上下文感知触发

AI 根据当前对话上下文，自动判断应该触发哪些 Skills：

用户输入："帮我写登录功能"
  ↓
AI 内部推理：
  - 这是新功能 → 触发 brainstorming
  - 需要拆解任务 → 触发 writing-plans
  - 需要写代码 → 触发 tdd-workflow
  - 完成后需要审查 → 触发 code-review

5.3 Skills 的优先级和冲突解决

当多个 Skills 可能同时触发时，Superpowers 使用优先级机制：

# SKILL.md 中的优先级声明
priority: high    # high > medium > low
depends_on:
  - brainstorming  # 必须在 brainstorming 完成后才能触发
conflicts_with:
  - quick-hack     # 与 quick-hack 冲突，不同时使用

六、代码实战：从零构建一个 Superpowers 式 Skill

6.1 场景：构建一个"API 接口设计规范" Skill

假设我们要强制 AI 在生成 API 接口时遵循 RESTful 规范。

6.2 Step 1：创建 Skill 目录和文件

# 创建 Skill 目录
mkdir -p ~/.claude/skills/api-design-standards

# 创建 SKILL.md
touch ~/.claude/skills/api-design-standards/SKILL.md

6.3 Step 2：编写 SKILL.md

---
name: api-design-standards
description: 强制 RESTful API 设计规范，包括资源命名、HTTP 方法使用、状态码返回、错误处理等
trigger: 涉及 API 接口设计、路由定义、Controller 编写的场景
priority: high
---

# API Design Standards

你是一个资深的后端架构师，严格遵循 RESTful API 设计规范。

## 强制规范

### 1. 资源命名
- ✅ 使用复数名词：`/users`, `/orders`, `/products`
- ❌ 禁止动词：`/getUser`, `/createOrder`

### 2. HTTP 方法语义
| 操作 | HTTP 方法 | 示例 |
|------|-----------|------|
| 获取列表 | GET | `GET /users` |
| 获取单个 | GET | `GET /users/{id}` |
| 创建 | POST | `POST /users` |
| 更新 | PUT/PATCH | `PUT /users/{id}` |
| 删除 | DELETE | `DELETE /users/{id}` |

### 3. 状态码规范
- `200 OK`：成功返回资源
- `201 Created`：成功创建资源
- `400 Bad Request`：客户端参数错误
- `401 Unauthorized`：未认证
- `404 Not Found`：资源不存在
- `500 Internal Server Error`：服务端错误

### 4. 错误处理
错误响应必须遵循以下 JSON 格式：
```json
{
  "error": {
    "code": "USER_NOT_FOUND",
    "message": "用户不存在",
    "details": {...}
  }
}

5. 分页规范

列表接口必须支持分页：

GET /users?page=1&limit=20
响应：
{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 100,
    "total_pages": 5
  }
}

Quality Gates（质量门禁）

在生成任何 API 接口代码之前，你必须：

1. ✅ 检查资源命名是否符合复数名词规范
2. ✅ 检查 HTTP 方法是否语义正确
3. ✅ 检查错误响应是否遵循标准格式
4. ✅ 检查是否支持分页（针对列表接口）

示例

❌ 错误示例

# 不规范的接口设计
@app.route('/getUser', methods=['POST'])  # ❌ 动词 + POST 获取资源
def get_user():
    ...

✅ 正确示例

# 规范的接口设计
@app.route('/users/<int:user_id>', methods=['GET'])  # ✅ 名词 + GET
def get_user(user_id):
    user = User.query.get(user_id)
    if not user:
        return {"error": {"code": "USER_NOT_FOUND", "message": "用户不存在"}}, 404
    return {"data": user.to_dict()}, 200

禁止行为

❌ 使用动词作为资源名
❌ 用 POST 完成所有操作（忽略 HTTP 方法语义）
❌ 错误响应返回纯字符串（必须 JSON 格式化）
❌ 列表接口不支持分页

### 6.4 Step 3：验证 Skill 是否生效

重启 Claude Code 或重新加载 Skills：

```bash
# 在 Claude Code 中执行
/plugin reload

测试触发：

用户输入："帮我写一个用户管理的 API 接口"

AI 响应应该首先输出设计文档，说明资源命名、HTTP 方法、状态码等规范，然后才进入代码编写。

七、生产级实践：TDD 强制、子 Agent 协作、代码审查

7.1 TDD 强制实战

场景：实现用户注册功能

没有 Superpowers 的 AI 输出：

# AI 直接生成实现代码（无测试）
def register_user(username, password):
    hashed_password = bcrypt.hash(password)
    user = User(username=username, password=hashed_password)
    db.session.add(user)
    db.session.commit()
    return user

有 Superpowers（tdd-workflow Skill）的 AI 输出：

# Step 1: RED——先写失败测试
def test_register_user_success():
    """测试用户注册成功"""
    response = client.post('/users/register', json={
        'username': 'testuser',
        'password': 'SecurePass123!'
    })
    assert response.status_code == 201
    assert 'user_id' in response.json['data']
    assert response.json['data']['username'] == 'testuser'

def test_register_user_duplicate():
    """测试重复注册"""
    # 先创建一个用户
    client.post('/users/register', json={
        'username': 'existing',
        'password': 'Password123!'
    })
    # 再次注册相同用户名
    response = client.post('/users/register', json={
        'username': 'existing',
        'password': 'Password123!'
    })
    assert response.status_code == 400
    assert response.json['error']['code'] == 'USERNAME_ALREADY_EXISTS'

# 运行测试 → 失败（RED）
# 因为 register_user 函数还不存在

# Step 2: GREEN——写最小实现
def register_user(username, password):
    # 检查用户是否存在
    if User.query.filter_by(username=username).first():
        raise ValueError('USERNAME_ALREADY_EXISTS')
    
    hashed_password = bcrypt.hash(password)
    user = User(username=username, password=hashed_password)
    db.session.add(user)
    db.session.commit()
    return user

# 运行测试 → 通过（GREEN）

# Step 3: REFACTOR——重构优化
def register_user(username, password):
    # 参数校验
    if not is_valid_username(username):
        raise ValueError('INVALID_USERNAME')
    if not is_valid_password(password):
        raise ValueError('INVALID_PASSWORD')
    
    # 检查重复
    if User.query.filter_by(username=username).first():
        raise ValueError('USERNAME_ALREADY_EXISTS')
    
    # 创建用户
    hashed_password = bcrypt.hash(password)
    user = User(username=username, password=hashed_password)
    db.session.add(user)
    db.session.commit()
    
    # 发送欢迎邮件（异步）
    send_welcome_email.delay(user.email)
    
    return user

# 运行测试 → 仍然通过（REFACTOR 完成）

7.2 子 Agent 协作实战

场景：构建一个完整的电商系统

没有子 Agent 协作时，AI 会顺序完成所有任务，耗时长且容易出错。

Superpowers 的 subagent-orchestration Skill：

# AI 自动任务拆解和分配
tasks = [
    {
        "id": "task-1",
        "description": "设计用户服务 API",
        "assigned_to": "subagent-1",
        "depends_on": []
    },
    {
        "id": "task-2",
        "description": "实现商品服务数据库模型",
        "assigned_to": "subagent-2",
        "depends_on": []
    },
    {
        "id": "task-3",
        "description": "编写订单服务单元测试",
        "assigned_to": "subagent-3",
        "depends_on": ["task-1", "task-2"]
    }
]

# 子 Agent 1 和 2 并行工作
# 子 Agent 3 等待 1 和 2 完成后开始

实际效果：

• 总时间从 60 分钟 → 25 分钟（并行化）
• 每个子 Agent 专注于单一职责，质量更高

7.3 代码审查实战

Superpowers 的 code-review Skill 强制 Self-Review：

# Self-Review Checklist（自动生成）

## 1. 功能正确性
- [ ] 所有测试用例通过
- [ ] 边缘情况已处理（空值、边界值、并发）
- [ ] 错误处理完整

## 2. 代码质量
- [ ] 命名清晰（变量、函数、类名）
- [ ] 函数长度 ≤ 30 行
- [ ] 圈复杂度 ≤ 10
- [ ] 无重复代码（DRY）

## 3. 安全性
- [ ] SQL 注入防护（使用参数化查询）
- [ ] XSS 防护（输出编码）
- [ ] 密码加密存储（bcrypt/argon2）
- [ ] 输入验证（白名单策略）

## 4. 性能
- [ ] 数据库查询已优化（N+1 问题）
- [ ] 大列表已分页
- [ ] 缓存策略已考虑

## 5. 文档
- [ ] 公共 API 有文档注释
- [ ] README 已更新
- [ ] CHANGELOG 已更新

八、与 Claude Code / Codex / Cursor 的集成实战

8.1 Claude Code 集成（推荐）

安装方式一：从 Anthropic 官方市场安装

# 启动 Claude Code
claude

# 在 Claude Code 中执行
/plugin install superpowers@anthropic-agent-skills

# 重启 Claude Code
/restart

安装方式二：手动安装（适合自定义）

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

# 重启 Claude Code
/restart

# 验证安装
/plugin list
# 应该看到 superpowers 相关 Skills

8.2 GitHub Copilot CLI 集成

# 安装 Copilot CLI
brew install gh
gh extension install github/gh-copilot

# 安装 superpowers
copilot plugin marketplace add https://github.com/obra/superpowers

# 验证
copilot plugin list

8.3 Cursor 集成

Cursor 支持通过 .cursorrules 文件注入自定义规则。

将 Superpowers 的 Skills 内容整合到 .cursorrules：

# .cursorrules
rules:
  - "在所有代码生成前，必须先写设计文档"
  - "强制 TDD：先写测试，再写实现"
  - "任务必须拆解为 2-5 分钟可完成的小任务"
  - "代码提交前必须 Self-Review"

九、性能与成本分析：纪律如何节省 Token

9.1 传统 AI 编程的 Token 浪费

传统模式：
  用户："帮我写登录功能"
  AI：生成 500 行代码（一次性）
  用户："有 bug"
  AI：修复 → 引入新 bug（迭代 5-10 次）
  总 Token 消耗：~50,000 tokens
  最终代码质量：低（技术债务高）

9.2 Superpowers 模式的 Token 分配

Superpowers 模式：
  1. 设计文档：~3,000 tokens
  2. 任务拆解：~2,000 tokens
  3. 写测试（每个小任务）：~1,000 tokens × 5 = ~5,000 tokens
  4. 写实现（每个小任务）：~500 tokens × 5 = ~2,500 tokens
  5. 代码审查：~2,000 tokens
  总 Token 消耗：~14,500 tokens
  最终代码质量：高（测试覆盖、规范、可维护）

9.3 成本对比（以 Claude 3.7 Sonnet 为例）

节省：~93% 的成本，且代码质量显著更高。

十、总结与展望：AI 软件工程的下一个范式

10.1 核心收获

10.2 Superpowers 的局限性

1. 学习曲线：需要理解软件工程规范（不适合纯新手）
2. 过度规范：小脚本/原型开发时可能显得繁琐
3. 平台绑定：目前主要支持 Claude Code / Copilot（其他平台支持有限）

10.3 未来展望

短期（2026 年）：

• Skills 市场生态化（类似 VSCode 插件市场）
• 更多语言/框架的专用 Skills（React、Django、Spring Boot...）
• 与 CI/CD 流水线深度集成（GitHub Actions、Jenkins）

长期（2027+）：

• AI 软件工程标准化：类似 POSIX 标准，形成 AI 编程的通用规范
• 跨 Agent 协作协议：不同 AI Agent 之间的任务分配和通信标准
• 自适应纪律：根据项目类型自动调整规范严格程度

参考资料

• GitHub 仓库：https://github.com/obra/superpowers
• Anthropic Skills Marketplace：https://skills.anthropic.com
• Superpowers 官方文档：https://superpowers.obra.com/docs
• 相关论文：
  • "Process Engineering for AI-Assisted Software Development"（2026）
  • "TDD in the Age of LLMs"（2025）

附录：完整安装指南

macOS / Linux

# 方法一：一键安装（推荐）
curl -fsSL https://superpowers.obra.com/install.sh | bash

# 方法二：手动安装
git clone https://github.com/obra/superpowers.git
mkdir -p ~/.claude/skills
cp -r superpowers/skills/* ~/.claude/skills/

# 验证
ls ~/.claude/skills/
# 应该看到 20+ 个 Skill 目录

Windows (PowerShell)

# 安装 GitHub Copilot CLI（如果还没安装）
winget install --id GitHub.cli

# 安装 superpowers
git clone https://github.com/obra/superpowers.git
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.claude\skills"
Copy-Item -Recurse "superpowers\skills\*" "$env:USERPROFILE\.claude\skills\"

# 在 Copilot CLI 中验证
copilot plugin list

本文深入分析了 obra/superpowers 项目，从核心理念、架构设计到生产级实践，全面剖析了如何用工程纪律驯服 AI 编程 Agent。希望对你有所帮助！

—— 程序员茄子 | 2026-05-23