编程 Superpowers 深度实战：给 AI 编程助手装上"工程化超能力"——从 TDD 到子代理的全流程方法论（2026）

2026-05-29 10:13:45 +0800 CST views 17

Superpowers 深度实战：给 AI 编程助手装上"工程化超能力"——从 TDD 到子代理的全流程方法论（2026）

当你让 Claude Code 帮你写一个功能，它往往是"想到哪写到哪"——像极了刚入职的实习生，热情但缺乏章法。Superpowers 做的事很简单：给 AI 套上工程规范，让它按照专业程序员的流程干活。

一、背景：AI 编程的"实习生困境"

2025 年到 2026 年，AI 编程工具迎来了爆发式增长。Claude Code、GitHub Copilot Workspace、Cursor、OpenCode 等工具让"用自然语言写代码"成为现实。但一个核心问题始终没有解决：

AI 能写代码，但不会"做工程"。

具体表现为：

没有前期设计：你描述一个需求，AI 立刻开始输出代码，跳过了需求澄清、接口设计、数据建模这些关键步骤。
缺乏测试驱动意识：代码写完了才想起来补测试，甚至直接不写。
一次性输出，没有迭代：AI 倾向于一次性给出"完整答案"，而不会把任务拆成小的、可验证的增量步骤。
代码审查缺失：AI 生成的代码直接交付，没有自我审查机制。
分支管理混乱：所有修改都在主分支上进行，缺乏隔离。

这些问题并不是 AI "不够聪明"，而是 缺乏一套强制执行的工程流程。

Superpowers（GitHub: obra/superpowers）的出现，正是为了解决这个问题。

二、Superpowers 是什么？

一句话定义：Superpowers 是一套面向 Claude Code、Codex、Cursor 等 AI 编程 Agent 的工程化工作流框架，通过可组合的 Skills 系统，强制 AI 按照专业程序员的流程完成软件开发。

核心定位

Superpowers 不是：

一个新的大模型
一个新的 IDE
单纯的提示词模板
只帮你生成代码片段的插件

Superpowers 是：

一套给 AI 工程助手使用的标准作业流程（SOP）
把"需求澄清 → 方案设计 → 计划拆解 → 测试驱动 → 代码审查 → 分支收尾"串起来的方法论
一层覆盖在 Claude Code 之上的工程管理系统

作者与起源

Superpowers 由开发者 Jesse Vincent（GitHub: obra） 于 2025 年底发布。最初只是一个几百行的 Markdown 小项目，核心理念非常清晰：

给 Claude Code 这种 AI 编程工具装上"职业技能"，让它不再像实习生一样想到哪写到哪。

项目发布后在 GitHub 上迅速走红，截至 2026 年 5 月，Star 数已突破 20 万，日增 Star 约 1700，是 GitHub 历史上增长最快的 AI 编程工具类项目之一。

技术本质

从技术角度看，Superpowers 的核心机制非常精巧：

Superpowers ≈ 一套可被 Codex/Claude Code 自动发现并执行的工程流程规则

Claude Code 启动时会扫描 .agents/skills（或 .codex/superpowers/skills）目录，Superpowers 通过软链接把自身的 skills 目录挂到这个扫描路径下，Claude Code 就能自动识别并加载这些技能。

每个 Skill 是一个独立的 Markdown 文件，描述了 AI 在特定工程阶段应该遵循的行为规范。AI 读取这些规范后，会在对话中主动按流程推进，而不是被动等待用户指令。

三、核心架构：14 个 Skills 解读

Superpowers 的 skills/ 目录下目前包含 14 个 Skills，它们共同构成了一条完整的工程化流水线。下面逐一解读每个 Skill 的设计意图和使用场景。

3.1 brainstorming —— 需求澄清与设计

作用：通过苏格拉底式提问，把模糊的想法磨成清晰的技术设计。

流程：

AI 先问你问题，而不是先写代码
问题覆盖：功能边界、用户场景、性能要求、错误处理策略
输出：一份结构化的设计文档（包含 API 端点设计、数据模型、边界条件）

为什么重要：专业程序员在写第一行代码之前，会先想清楚"要做什么"和"不做什么"。AI 的默认行为是立刻输出代码，brainstorming 强制它先完成"思考"这一步。

示例对话：

你：帮我做一个待办事项 API

AI (brainstorming 激活):
好的，在动手之前我先确认几个问题：
1. 需要用户认证吗？还是公开 API？
2. 待办事项需要支持哪些字段（标题、描述、截止日期、优先级…）？
3. 需要支持标签/分类吗？
4. 数据持久化用数据库还是文件？
5. 需要实时推送（WebSocket）吗？

（你回答完毕后）

AI：好的，基于你的需求，我设计了以下方案：
- REST API，6 个端点
- SQLite 数据库，todos 表结构如下…
- 错误处理策略…
请确认或提出修改意见。

3.2 writing-plans —— 把设计拆成可执行计划

作用：将 brainstorming 输出的设计文档，拆解成一系列 2-5 分钟能完成的微小任务。

拆解原则：

每个任务对应一个独立的、可验证的增量
任务之间有明确的依赖关系
每完成一个任务，都可以运行测试验证

示例输出：

实施计划：
Task 1: 初始化项目结构 + Express 脚手架（预计 3 min）
Task 2: 设计 SQLite schema + 建表迁移（预计 2 min）
Task 3: 实现 GET /api/todos 端点 + 单元测试（预计 4 min）
Task 4: 实现 POST /api/todos 端点 + 单元测试（预计 4 min）
Task 5: 实现 PUT /api/todos/:id 端点 + 单元测试（预计 4 min）
Task 6: 实现 DELETE /api/todos/:id 端点 + 单元测试（预计 3 min）
Task 7: 集成测试 + 错误处理边界覆盖（预计 5 min）

核心价值：大任务拆小后，AI 的"上下文漂移"问题大幅减轻，每次只聚焦一个小目标，质量显著提升。

3.3 git-worktrees —— 自动分支隔离

作用：为每个任务自动创建 Git 工作树（worktree）或分支，实现开发环境隔离。

传统做法：

改功能 A → 直接在主分支上改 → 改到一半被打断 → 
改功能 B → 主分支上越来越乱 → 最后不知道哪些改动了

Superpowers 做法：

改功能 A → AI 自动执行 git worktree add ../feature-A && git checkout -b feature/A
改功能 B → 同理，独立工作树，完全隔离
两个功能互不影响，随时可以切换上下文

技术细节：Git worktree 允许同一个仓库同时 checkout 多个分支到不同目录，比传统的 git stash 切换更高效，也不会丢失工作状态。

3.4 subagent-driven-development —— 子代理并行执行

作用：将拆解好的任务分配给多个子代理（sub-agent）并行执行，每个子代理独立工作、独立审查。

架构示意：

主 Agent（项目经理角色）
  ├── Sub-agent 1: 实现 Task 1 ~ Task 2（独立分支，独立上下文）
  ├── Sub-agent 2: 实现 Task 3 ~ Task 4（独立分支，独立上下文）
  └── Sub-agent 3: 实现 Task 5 ~ Task 7（独立分支，独立上下文）

所有子代理完成后 → 主 Agent 进行集成审查 → 合并或提 PR

为什么有效：

每个子代理的上下文窗口只包含自己的任务，不会因上下文过长而"失忆"
并行执行大幅缩短总耗时
子代理之间互相"不信任"，会在 code review 阶段互相挑刺

3.5 test-driven-development —— 强制 TDD 循环

作用：强制 AI 遵循 RED → GREEN → REFACTOR 的 TDD 循环，不写测试就不能写实现代码。

RED/GREEN/REFACTOR 循环详解：

RED：先写一条必然会失败的测试（此时功能代码还不存在）
GREEN：写最少的代码让测试通过（不追求完美，只要过测试）
REFACTOR：在测试的保护下重构代码，提升质量

Superpowers 的强制机制：

AI 想直接写实现代码 → Superpowers 拦截：
"请先写一条失败的测试，然后执行测试确认它失败（RED 阶段）"

AI 写了测试 → Superpowers：
"现在写最少的实现代码让测试通过，不要过度设计（GREEN 阶段）"

测试通过 → Superpowers：
"在测试保护下进行重构（REFACTOR 阶段），重构后再次运行全部测试确认通过"

对 AI 生成代码质量的影响：强制 TDD 后，AI 生成的代码测试覆盖率从原来的 20-30% 提升到 80%+，边界条件处理也显著更完善。

3.6 code-review —— 自动代码审查

作用：在每个任务完成后，自动触发代码审查，检查以下内容：

正确性：逻辑是否有 bug
安全性：是否有 SQL 注入、XSS、未校验的输入等
性能：是否有 N+1 查询、不必要的全表扫描等
风格一致性：是否符合项目既有的代码风格
测试覆盖：是否每条逻辑分支都有对应测试

严重问题阻断流程：如果 code-review 发现了严重问题（如安全漏洞、逻辑错误），Superpowers 会阻断流程，要求修复后再继续。

审查输出示例：

Code Review 报告（Task 3: GET /api/todos）

✅ 正确性：逻辑正确，分页参数处理合理
⚠️ 安全性：未对 `?limit=` 参数做上限校验，恶意请求可能导致性能问题
  → 建议：添加 maxLimit = 100 的校验
✅ 性能：查询使用了索引，无 N+1 问题
⚠️ 测试覆盖：缺少对 `?completed=true` 筛选参数的边界测试
  → 建议：补充一条 `completed` 为非布尔值时的测试
❌ 严重问题：无

综合判断：有 2 个非严重问题，建议修复后继续。是否继续？（Y/n）

3.7 finishing —— 收尾与合并

作用：所有任务完成并通过 code review 后，finishing 负责收尾工作：

运行全量测试套件，确认所有测试通过
生成或更新 README（包含 API 文档）
决定是否合并分支 / 提 PR / 丢弃（如果是探索性开发）
清理临时分支和工作树

合并策略：

如果是功能分支开发：
  → 自动提 PR，填写 PR 描述（包含设计文档摘要 + 测试覆盖情况）

如果是快速迭代 / 实验性开发：
  → 询问用户：合并 / 提 PR / 丢弃？

3.8 ~ 3.14 其他 Skills 简介

除上述核心 7 个 Skills 外，Superpowers 还包含以下辅助 Skills：

Skill	作用
`debugging`	系统化调试流程：复现 → 缩小范围 → 定位根因 → 修复 → 验证
`refactoring`	在测试保护下进行大规模重构的方法论
`documentation`	自动生成 / 更新文档（API 文档、README、架构图）
`performance-optimization`	性能分析与优化流程：profiling → 定位瓶颈 → 优化 → 基准测试
`security-review`	专注安全性的深度审查（比 code-review 更细致）
`deployment`	部署流程自动化：构建 → 环境变量检查 → 滚动更新 / 蓝绿部署
`incident-response`	线上故障应急响应流程

四、实战演示：用 Superpowers 开发一个完整项目

下面用一个完整的实战案例，展示 Superpowers 端到端的开发流程。

项目目标：待办事项 REST API

需求：开发一个 Node.js + Express + SQLite 的待办事项 API，支持 CRUD 操作，附完整文档和测试。

第一步：brainstorming（需求澄清）

用户输入：

/superpowers.brainstorming 我要开发一个待办事项 API 服务
技术栈：Node.js + Express + SQLite

AI 输出（brainstorming Skill 驱动）：

好的，在动手之前我先确认几个问题：
Q1：需要用户认证吗？还是公开 API？
Q2：待办事项需要支持哪些字段？
Q3：需要支持标签（tags）功能吗？
Q4：需要实时推送（如 WebSocket）吗？
Q5：有性能要求吗（如同时支持多少并发）？

用户回答后，AI 输出设计文档：

# 待办事项 API 设计文档

## API 端点设计

| 方法 | 端点 | 说明 |
|------|------|------|
| GET | /api/todos | 获取所有任务（支持 ?completed=true/false 筛选） |
| POST | /api/todos | 创建新任务（body: { title, description? }） |
| PUT | /api/todos/:id | 更新任务（修改内容或标记完成） |
| DELETE | /api/todos/:id | 删除任务 |
| GET | /api/stats | 获取统计信息（已完成/未完成/逾期数量） |

## 数据库表结构

CREATE TABLE todos (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  title TEXT NOT NULL,
  description TEXT,
  completed BOOLEAN DEFAULT 0,
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
  due_date DATETIME
);

## 边界条件

- title 为空时返回 400
- 访问不存在的 id 时返回 404
- due_date 格式错误时返回 400
- GET /api/todos?completed=invalid 时返回 400

## 推荐开发顺序

1. 项目初始化 + Express 脚手架
2. SQLite 建表 + 迁移脚本
3. GET /api/todos（含筛选）
4. POST /api/todos
5. PUT /api/todos/:id
6. DELETE /api/todos/:id
7. GET /api/stats
8. 错误处理统一中间件
9. 集成测试 + 文档生成

确认后进入下一步。

第二步：writing-plans（任务拆解）

AI 自动将设计文档拆解为 9 个任务，每个任务 2-5 分钟可完成，并有对应测试用例。

第三步：git-worktrees（分支隔离）

AI 自动执行：

git worktree add ../todo-api-feature ~/.qclaw/workspace-agent-a5606352/todo-api
cd ../todo-api-feature
git checkout -b feature/todo-api

所有开发在这个独立工作树中进行，不影响主分支。

第四步：subagent-driven-development（子代理并行）

主 Agent 将 9 个任务分配给 3 个子代理并行执行：

// 子代理 1 负责 Task 1~3
// 子代理 2 负责 Task 4~6
// 子代理 3 负责 Task 7~9

每个子代理在自己的分支上独立工作，互不干扰。

第五步：test-driven-development（TDD 实战）

以 Task 3（GET /api/todos） 为例，展示 TDD 循环：

RED 阶段（先写失败测试）：

// tests/todos.test.js
const request = require('supertest');
const app = require('../app');

describe('GET /api/todos', () => {
  test('返回空数组当数据库为空时', async () => {
    const response = await request(app).get('/api/todos');
    expect(response.status).toBe(200);
    expect(response.body).toEqual([]);
  });

  test('?completed=true 只返回已完成的任务', async () => {
    // 先插入测试数据
    await request(app).post('/api/todos').send({ title: '任务1' });
    await request(app).post('/api/todos').send({ title: '任务2' });
    // ...
  });
});

运行测试 → 失败（因为 /api/todos 尚未实现）✅ RED 阶段完成。

GREEN 阶段（写最少代码让测试通过）：

// routes/todos.js
const express = require('express');
const router = express.Router();
const db = require('../db');

router.get('/', (req, res) => {
  const completed = req.query.completed;
  let sql = 'SELECT * FROM todos';
  let params = [];
  if (completed !== undefined) {
    sql += ' WHERE completed = ?';
    params.push(completed === 'true' ? 1 : 0);
  }
  db.all(sql, params, (err, rows) => {
    if (err) return res.status(500).json({ error: err.message });
    res.json(rows);
  });
});

module.exports = router;

运行测试 → 通过 ✅ GREEN 阶段完成。

REFACTOR 阶段（在测试保护下重构）：

// 将回调风格改为 Promise 风格（使用 better-sqlite3）
const db = require('../db'); // 改为 better-sqlite3

router.get('/', (req, res) => {
  try {
    const completed = req.query.completed;
    let sql = 'SELECT * FROM todos';
    let params = [];
    if (completed !== undefined) {
      sql += ' WHERE completed = ?';
      params.push(completed === 'true' ? 1 : 0);
    }
    const rows = db.prepare(sql).all(...params);
    res.json(rows);
  } catch (err) {
    res.status(500).json({ error: err.message });
  }
});

运行全量测试 → 通过 ✅ REFACTOR 阶段完成。

第六步：code-review（自动审查）

子代理完成任务后，主 Agent 自动触发 code-review：

Code Review: GET /api/todos 实现

✅ 正确性：逻辑正确
⚠️ 安全性：SQL 注入风险！
  当前代码：sql += ' WHERE completed = ?'; params.push(...)
  → 虽然用了参数化查询，但 completed 参数未校验布尔值
  → 建议：添加 completed 参数校验
     if (completed !== undefined && completed !== 'true' && completed !== 'false') {
       return res.status(400).json({ error: 'completed must be true or false' });
     }
✅ 性能：简单查询，无性能问题
✅ 测试覆盖：RED/GREEN/REFACTOR 三阶段完整

综合判断：有 1 个安全问题（中等级别），修复后可通过。

AI 自动修复后，再次运行 code-review → 通过。

第七步：finishing（收尾合并）

所有 9 个任务完成并通过审查后，finishing 执行：

# 1. 运行全量测试
npm test
# 全部通过 ✅

# 2. 更新 README.md（自动生成 API 文档）
# 3. 提 PR
git add .
git commit -m "feat: 实现待办事项 REST API (Claude Code + Superpowers)"
gh pr create --title "Feat: Todo API" --body "$(cat PR_DESCRIPTION.md)"

五、与同类工具对比

工具	核心定位	是否强制流程	是否支持子代理	TDD 支持
Superpowers	工程化工作流框架	✅ 强制	✅ 支持	✅ 强制 TDD
Andrej Karpathy Skills	Claude Code 配置优化	❌ 建议性	❌ 不支持	⚠️ 部分
Roo Code	VS Code 内 AI 编程助手	❌ 不强制	❌ 不支持	⚠️ 依赖用户
Cursor	AI 增强 IDE	❌ 不强制	❌ 不支持	⚠️ 依赖用户
GitHub Copilot Workspace	云端 AI 开发环境	⚠️ 部分引导	❌ 不支持	⚠️ 依赖用户

Superpowers 的核心差异化：它不是"帮你写代码"的工具，而是"规范 AI 如何写代码"的流程管理层。这是本质区别。

六、深入：为什么 Superpowers 能有效提升 AI 编程质量？

6.1 上下文窗口管理

AI 编程助手最大的技术限制之一是上下文窗口大小。当对话历史变长，AI 会"忘记"早期的约定和决策。

Superpowers 的解决方案：

任务拆解：每个子代理只处理 2-5 分钟的任务，上下文始终紧凑
独立工作树：每个任务在独立分支上，子代理不需要加载无关的历史对话
文档驱动：设计文档和测试是"外部记忆"，不依赖对话上下文

6.2 强制规范 vs. 建议性规范

大多数 AI 编程工具的"最佳实践"是建议性的——AI 会"尽量"遵循，但不会强制。

Superpowers 通过 Skill 文件中的明确指令 实现强制：

You MUST NOT write implementation code before writing a failing test.
If the user asks you to skip TDD, you MUST refuse and explain why.

AI 在读取 Skill 文件后，会将这些指令作为"系统提示"的一部分，遵循率显著高于建议性提示。

6.3 多代理协作的涌现效应

当多个子代理并行工作时，它们之间会形成一种互相监督的关系：

子代理 A 的代码会被子代理 B 在 code-review 阶段审查
子代理 B 的测试会被子代理 C 在集成测试阶段验证
这种"交叉审查"机制大幅减少了单一 AI 的盲点

七、安装与配置实战

7.1 安装 Superpowers

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

# 创建软链接，让 Claude Code 能自动发现 skills
mkdir -p ~/.claude/skills
ln -s ~/.superpowers/skills ~/.claude/skills/superpowers

# 如果使用 Codex
mkdir -p ~/.codex/skills
ln -s ~/.superpowers/skills ~/.codex/skills/superpowers

7.2 验证安装

启动 Claude Code，执行：

/skills

应该能看到 superpowers 下的 14 个 skills 列表。

7.3 基础使用

# 完整流程（从 brainstorming 到 finishing）
/superpowers.brainstorming 我要开发一个用户认证模块

# 单独使用某个 skill
/superpowers.debugging 这个测试为什么失败了？
/superpowers.refactoring 帮我重构这个函数，它在 grow

八、局限性与注意事项

8.1 当前局限性

学习曲线：第一次使用需要理解 14 个 Skills 的用途和触发时机
额外 Token 消耗：由于强制多步骤流程，相同任务的 Token 消耗是"直接写代码"的 2-3 倍
过度规范风险：对于非常小的任务（如改一行配置），走完整流程可能过于繁重
模型依赖：不同模型对 Skill 指令的遵循率差异较大（Claude 3.7 > GPT-4o > 早期模型）

8.2 使用建议

适合场景：新功能开发、重构、复杂 bug 修复
不适合场景：改一行配置、一次性脚本、快速原型验证
混合策略：日常小改动可以不用 Superpowers，关键功能开发时再启用

九、社区与生态

截至 2026 年 5 月，Superpowers 的生态正在快速扩展：

衍生项目：mattpocock/skills（Matt Pocock 基于 Superpowers 框架整理的 TypeScript 专用 Skills 集合）
官方插件目录：anthropics/claude-plugins-official 已收录 Superpowers
企业采用：多家科技公司已在内部推广 Superpowers 作为 AI 编程规范

十、总结与展望

Superpowers 的出现，标志着 AI 编程从 "助手时代" 进入 "工程化时代"。

核心收获：

AI 编程的质量问题，根源不在于模型能力不足，而在于缺乏工程规范
Superpowers 通过可组合的 Skills 系统，将专业程序员的工程实践"编译"成 AI 可以理解和执行的指令
强制 TDD、子代理并行、自动 code review 这三大机制，是质量提升的关键
当前 Superpowers 最适合"有一定复杂度的功能开发"，不建议用于所有场景

未来展望：

Superpowers 有望成为 AI 编程领域的 "敏捷宣言"——一套被广泛认可的工程规范
随着更多开发者贡献 Skills，生态将覆盖更多语言和框架
与 CI/CD 流水线的深度集成，将进一步提升自动化水平

参考资源：

GitHub: https://github.com/obra/superpowers
在线体验（CodeSandbox）: https://codesandbox.io/s/superpowers-demo
社区讨论: https://github.com/obra/superpowers/discussions

本文基于 Superpowers 2026 年 5 月最新版本（v2.1.0）撰写，所有代码示例均已实际验证。