Superpowers 深度实战：当 AI 编程助手遇见工程方法论——从 Skills 框架到子代理驱动开发的生产级完全指南（2026）

作者按：如果你曾把 Claude Code / Cursor / Copilot 当成"高级代码补全工具"来用，那你可能只发挥了它们 10% 的能力。Superpowers 的出现，标志着 AI 辅助编程从"提示词工程"跨入"工程方法论"的新时代。本文深入拆解这套由 Jesse Vincent（obra）打造的 Agentic Skills 框架，从设计哲学、核心技能、技术架构到生产实战，给你一份真正可用的完全指南。

一、引言：AI 编程的"野蛮生长"时代

1.1 我们踩过的坑

2024 年到 2026 年，AI 编程工具经历了爆发式增长。Claude Code、Cursor、GitHub Copilot、Codex CLI……几乎每个开发者都试过用 AI 来辅助写代码。

但现实很骨感。大多数人的使用体验是这样的：

开发者：帮我写一个用户登录功能
AI：好的！（立即生成 200 行代码）
开发者：（发现没测试、没错误处理、没文档）
开发者：算了我自己重写……

核心问题不在于 AI 的编码能力不够强，而在于它缺少一个人类工程师与生俱来的东西——工程方法论。

人类工程师 = 技术能力 + 工程方法论（规划、测试、代码审查、迭代）
AI 编程工具 = 技术能力（✓）+ 工程方法论（✗）

结果就是：AI 像一个"急于表现但没有经验的初级程序员"——代码能跑，但质量不可控，维护成本高，技术债务累积快。

1.2 根本矛盾：能力强，但行为不可预测

Superpowers 的解法：用方法论约束行为，让 AI 的能力转化为可靠的产出。

二、Superpowers 是什么：不只是技能包

2.1 一句话定义

Superpowers = 给 AI 编程助手装上"工程方法论大脑"的 Skills 框架

它不是传统意义上的库或工具链，而是一套可被 AI 代理理解并自动执行的"技能协议"（Skills Framework）。

2.2 它不是什么

• ❌ 不是一个你可以 import 的 JavaScript/Python 库
• ❌ 不是一个 Prompt 模板库
• ❌ 不是一个 AI 模型
• ❌ 不是 Vibe Coding（凭感觉编程）的延续

2.3 它是什么

• ✅ 一套软件工程方法论（TDD、YAGNI、DRY 的工程化落地）
• ✅ 一个 Agentic Skills 框架（可动态加载、可组合、可扩展）
• ✅ 一种 AI 行为的约束体系（用流程规范替代随意生成）
• ✅ 给 AI 的"开发 SOP 手册"——教 AI 如何正确地编程

2.4 核心数据

三、核心设计哲学：流程大于提示

3.1 传统 AI 编程 vs Superpowers

【传统模式】
开发者提需求 → AI 生成代码 → 人工检查修改
（AI 行为是"随机的"，质量取决于运气）

【Superpowers 模式】
定义工作流 → AI 按流程执行 → 自动验证质量 → 持续迭代优化
（AI 行为是可预测的，质量由流程保障）

3.2 五个核心原则

原则一：测试驱动开发（TDD）—— 永远先写测试

Superpowers 强制执行 RED-GREEN-REFACTOR 循环：

1. RED：写一个失败的测试
2. GREEN：写最少的代码让测试通过
3. REFACTOR：重构代码，保持测试通过

如果 AI 在写测试之前就写了实现代码，Superpowers 会删除这些代码，强迫它先写测试。

原则二：系统化优于临时凑合（Systematic over Ad-hoc）

不用"猜"的方式调试，而是用系统化的根因分析流程：

1. 复现问题
2. 二分法定位
3. 根因分析
4. 验证修复

原则三：复杂度削减（Complexity Reduction）

简化是首要目标。每一行代码都要问：这段代码真的需要存在吗？

原则四：证据优于主张（Evidence over Claims）

不要说"我修好了"，要证明它——运行测试，展示输出，提供证据。

原则五：1% 法则（The 1% Rule）

任何技能只要有 1% 的相关性，就必须调用，不可跳过。

这是 Superpowers 最"霸道"但也最有效的规则。它防止 AI "偷懒"跳过关键步骤。

四、14 个核心技能深度拆解

Superpowers 的核心是一系列可组合的技能（Skills），每个技能都是一个独立的 SKILL.md 文件，里面包含该技能的触发条件、执行流程、最佳实践。

4.1 brainstorming——苏格拉底式需求澄清

触发时机：在你开始写代码之前自动激活。

核心机制：AI 不会立即动手写代码，而是先通过提问来澄清你的真实需求。

典型对话流程：

AI：你想构建什么？能跟我详细说说吗？
你：我想做一个待办事项应用
AI：好的。这个类应用的核心用户是谁？他们最需要的功能是什么？
你：主要是我自己用，我需要……
AI：（继续追问，直到需求足够清晰）
AI：这是我对你需求的理解：[展示设计文档]
    有什么需要调整的吗？

为什么有效：大多数开发者（包括你）其实并不清楚自己真正想要什么。brainstorming 技能通过苏格拉底式的提问，帮你把模糊的想法变成清晰的设计。

输出：一份保存的设计文档（docs/designs/xxx.md），作为后续所有工作的基准。

4.2 using-git-worktrees——隔离工作区

触发时机：设计文档获得认可后自动激活。

核心机制：为每个功能创建独立的 Git worktree，在隔离的分支上工作。

# Superpowers 自动执行类似操作：
git worktree add ../my-project-feature-a feature-a
cd ../my-project-feature-a
# 运行项目 setup，验证测试基线干净

为什么重要：

• 防止不同功能之间的代码互相污染
• 可以随时切换上下文（main 分支保持干净）
• 符合"原子化提交"的工程实践

4.3 writing-plans——原子化任务拆解

触发时机：设计文档批准后，进入实现规划阶段。

核心机制：将大功能拆解为2-5 分钟可执行的原子任务。

一个典型的实现计划（docs/plans/xxx.md）结构：

# 实现计划：用户登录功能

## 任务 1：创建 User 模型（预计 3 分钟）
- 文件：`src/models/User.js`
- 代码：[完整的代码示例]
- 验证：`npm test -- --grep "User model"`

## 任务 2：实现密码哈希（预计 4 分钟）
- 文件：`src/utils/auth.js`
- 依赖：任务 1
- 代码：[完整的代码示例]
- 验证：`npm test -- --grep "password hashing"`

## 任务 3：……

关键设计原则：

1. 零上下文兼容：计划是写给"一个热情但没判断力、没项目上下文、讨厌测试的小白工程师"看的。他们拿到计划，不需要问任何问题，就能执行。
2. 每个任务都有完整代码：不是伪代码，是可直接使用的真实代码。
3. 每个任务都有验证步骤：知道怎么验证任务是否完成。

4.4 subagent-driven-development——子代理驱动开发

这是 Superpowers 最强大的技能，也是它区别于其他方案的核心。

触发时机：有实现计划，且任务大多独立时。

核心机制：为每个任务派发一个全新的子代理（subagent）来执行，每个任务后进行两阶段审查。

主代理（你）
  └─ 读取计划，创建 TodoList
       └─ 任务 1：派发子代理 A
       │     ├─ 子代理 A 实现代码
       │     ├─ 子代理 A 写测试
       │     ├─ 子代理 A 提交
       │     ├─ 规范合规性审查（派发审查子代理）
       │     └─ 代码质量审查（派发审查子代理）
       └─ 任务 2：派发子代理 B（全新上下文）
       └─ ……

为什么用"新子代理"而非"同一代理继续"：

• 上下文隔离：每个任务的执行都是从零开始，不会受到之前任务上下文的干扰
• 专注度更高：子代理只需要关心当前任务，不需要记住整个对话历史
• 可并行化：理论上可以同时派发多个子代理（用 dispatching-parallel-agents 技能）

两阶段审查：

第一阶段：规范合规性审查

• 验证代码是否匹配设计文档中的规范
• 检查是否实现了所有要求的功能
• 如果不匹配，打回修复

第二阶段：代码质量审查

• 评估代码的可读性、可维护性
• 检查是否有明显的 anti-pattern
• 如果质量不达标，打回修复

4.5 test-driven-development——TDD 纪律执行者

触发时机：在实现过程中自动激活。

核心机制：强制执行 RED-GREEN-REFACTOR 循环，并提供 testing anti-patterns 参考。

Anti-patterns 参考（部分）：

• ❌ 先写实现代码，再补测试（Superpowers 会删除这种行为产生的代码）
• ❌ 写一个永远通过的测试（没有断言，或者断言永远为真）
• ❌ 测试过于脆弱（实现细节一变，测试就挂）
• ❌ 测试覆盖率是唯一目标（覆盖率高不代表测试质量高）

正确示例：

// ❌ 错误：先写实现
function add(a, b) { return a + b; }
// 然后补测试（Superpowers 会删除 add 函数，强迫你先写测试）

// ✅ 正确：先写测试
describe('add', () => {
  it('should return 3 when given 1 and 2', () => {
    expect(add(1, 2)).toBe(3);
  });
});

// 运行测试 → 看到 RED（测试失败）
// 然后写最少代码让测试通过
function add(a, b) { return a + b; }
// 运行测试 → 看到 GREEN（测试通过）
// 重构（如果有必要）

4.6 systematic-debugging——系统化调试四步法

触发时机：遇到 Bug 或测试失败时。

四阶段流程：

阶段一：复现（Reproduce）

• 写一个最小可复现示例
• 确认 Bug 的稳定复现路径

阶段二：定位（Locate）

• 用二分法（git bisect 或代码注释法）定位引入 Bug 的提交/代码行
• 用防御性编程技巧缩小范围

阶段三：根因分析（Root Cause Analysis）

• 问"为什么"至少五次（5-Whys 方法）
• 区分"症状"和"根因"

阶段四：验证修复（Verify Fix）

• 先写一个暴露 Bug 的测试（让测试失败）
• 修复代码，让测试通过
• 运行完整测试套件，确保没有引入回归

4.7 requesting-code-review——代码审查前的最终检查

触发时机：任务完成之间，提交代码审查之前。

审查清单（部分）：

• 所有测试通过？
• 新代码有对应的测试？
• 没有违反 DRY / YAGNI 原则？
• 错误处理完整？
• 没有硬编码的密码/密钥/Token？
• 代码风格符合项目规范？

严重等级：

• Critical：阻塞进度，必须修复
• Major：建议修复，但不阻塞
• Minor：可选修复

4.8 finishing-a-development-branch——收尾工作流

触发时机：所有计划任务完成之后。

执行流程：

1. 运行完整测试套件
2. 展示选项：
   • Merge：直接合并到主分支
   • PR：创建 Pull Request（会生成 PR 描述）
   • Keep：保留分支，稍后继续
   • Discard：丢弃分支（如果实验失败）
3. 清理 worktree（如果用了 Git worktrees）

4.9 dispatching-parallel-agents——并行子代理

触发时机：多个独立任务可以并行执行时。

机制：同时派发多个子代理，每个子代理处理一个独立任务，最后汇总结果。

# 伪代码：Superpowers 内部的并行派发逻辑
import asyncio

async def execute_parallel_tasks(tasks):
    agents = [create_subagent() for _ in tasks]
    results = await asyncio.gather(*[
        agent.execute(task) for agent, task in zip(agents, tasks)
    ])
    return results

适用场景：

• 多个独立的 API 端点
• 多个独立的 UI 组件
• 数据库 Model 和对应的单元测试

4.10 writing-skills——创建新技能

触发时机：你需要为你的项目/团队创建自定义技能时。

最佳实践（部分）：

• 每个技能应该只做一件事（Single Responsibility）
• 技能的触发条件应该清晰明确
• 技能的描述应该让 AI 能准确判断是否需要调用该技能
• 包含完整的示例和边缘情况处理

自定义技能示例：

# skills/my-team-code-style/SKILL.md

---
name: my-team-code-style
description: >
  检查代码是否符合团队代码规范。
  触发条件：任何代码提交前，或 /review 命令。
---

# 团队代码规范检查

## 规则 1：变量命名
- 使用 camelCase（JavaScript/TypeScript）
- 使用 snake_case（Python）
- 不使用单字母变量名（除外：`i`, `j`, `k` 用于循环）

## 规则 2：函数长度
- 单个函数不超过 30 行

## 规则 3：……

4.11 其他重要技能（简介）

五、技术架构深度分析

5.1 SKILL.md 格式规范

每个技能都是一个包含 SKILL.md 文件的目录。SKILL.md 使用 Markdown 格式，但遵循特定的结构规范：

---
name: skill-name
description: >
  技能的描述。这是 AI 判断是否需要调用该技能的关键依据。
  描述应该具体、可执行，包含明确的触发条件。
---

# 技能名称

## 概述
这个技能做什么，什么时候应该用它。

## 触发条件
在以下情况下应该调用此技能：
- 条件 1
- 条件 2

## 执行流程
1. 步骤一
2. 步骤二
3. ……

## 示例
[具体的使用示例]

## 常见问题
[边缘情况和处理方法]

为什么用 Markdown 而不是代码：

• Markdown 是 AI 最擅长理解和生成的自然语言格式
• 人类可以轻松阅读和编辑
• 不需要编译或构建步骤
• 可以包含代码示例、流程图、表格等丰富内容

5.2 插件系统架构

Superpowers 通过各平台的插件系统注入技能文件：

Claude Code:
  /plugin marketplace add obra/superpowers-marketplace
  /plugin install superpowers@superpowers-marketplace

Cursor:
  /add-plugin superpowers
  或在插件市场搜索 "superpowers"

Codex CLI:
  /plugins → 搜索 superpowers → 安装

GitHub Copilot CLI:
  copilot plugin marketplace add obra/superpowers-marketplace
  copilot plugin install superpowers@superpowers-marketplace

插件安装后发生了什么：

1. 技能文件（SKILL.md 和相关资源）被下载到本地
2. 这些文件被注入到 AI 的上下文中
3. AI 在每次对话开始前，会自动检查是否有相关技能可以触发
4. 如果有，AI 会按照技能定义的流程执行

5.3 技能的可组合性

Superpowers 的精髓在于技能是可组合的。一个复杂的开发流程可能是多个技能的组合：

用户需求
  ↓
brainstorming（需求澄清）
  ↓
using-git-worktrees（创建隔离分支）
  ↓
writing-plans（制定计划）
  ↓
subagent-driven-development（执行计划）
  ↓ 每个任务：
  ├─ test-driven-development（写测试）
  ├─ 实现代码
  ├─ requesting-code-review（代码审查）
  └─ verification-before-completion（验证）
  ↓
finishing-a-development-branch（收尾）

六、实战演练：用 Superpowers 开发一个完整功能

6.1 场景：为 Express.js 应用添加 JWT 认证

让我们跟随一个完整的功能开发流程，看看 Superpowers 是如何工作的。

第一步：启动对话

你：我想给我的 Express 应用加一个 JWT 认证功能
Claude（加载了 Superpowers）：好的！在我开始之前，
我想先了解一下你的需求。能详细说说你想要实现什么吗？

你：就是用户登录后拿到一个 token，之后每次请求都带上这个 token
Claude：明白了。再问几个问题：
1. 你的应用现在有什么用户系统吗？还是从零开始？
2. Token 过期时间你打算设多长？
3. 需要支持 token 刷新吗？
4. 有特定的 JWT 库偏好吗？

你：1. 从零开始 2. 24小时 3. 需要 4. 没有，你推荐
Claude：好的，这是我对你需求的理解：[展示设计文档]
     主要包括：User 模型、注册接口、登录接口、Token 验证中间件、Token 刷新接口。
     这样理解对吗？有什么需要调整的吗？

你：对，就这样

第二步：设计文档确认后，创建 worktree

Claude：好的！我现在创建一个隔离的工作分支，
       并在那里进行开发。[执行 git worktree 相关操作]
       项目环境已验证，测试基线干净。可以开始制定实现计划了。

第三步：制定实现计划

Claude：这是我的实现计划，总共 8 个任务，预计 30 分钟完成。

## 任务 1：安装依赖（2 分钟）
- 执行：`npm install jsonwebtoken bcrypt`
- 验证：`npm list jsonwebtoken bcrypt`

## 任务 2：创建 User 模型（4 分钟）
- 文件：`src/models/User.js`
- [完整代码]
- 验证：`npm test -- --grep "User model"`

## 任务 3：实现密码哈希工具（3 分钟）
## 任务 4：实现 JWT 工具（4 分钟）
## 任务 5：创建注册接口（5 分钟）
## 任务 6：创建登录接口（4 分钟）
## 任务 7：实现认证中间件（4 分钟）
## 任务 8：实现 token 刷新接口（4 分钟）

你看这个计划可以吗？如果可以，我就开始执行了。
你说"go"，我就开始派发子代理执行。

你：go

第四步：子代理驱动开发

Claude：开始执行！我现在派发子代理来处理任务 1……
[派发子代理 A]

子代理 A：
  1. 执行 `npm install jsonwebtoken bcrypt`
  2. 验证安装成功
  3. 提交：`git commit -m "chore: add jsonwebtoken and bcrypt dependencies"`
  4. 汇报完成

Claude：任务 1 完成。现在派发子代理处理任务 2……
[派发子代理 B，全新上下文]

子代理 B：
  1. 先写测试（RED）
  2. 实现 User 模型（GREEN）
  3. 重构（REFACTOR）
  4. 提交
  5. 请求规范合规性审查

审查子代理：
  检查代码是否匹配设计文档……通过！

  请求代码质量审查……
  代码质量良好，建议：考虑添加 email 唯一性验证。是否修复？

子代理 B：
  好的，添加 email 唯一性验证。[修复并提交]

Claude：任务 2 完成。继续任务 3……

（中间过程省略，实际执行约 20-30 分钟，期间你可能去倒了杯咖啡）

第五步：完成并合并

Claude：所有 8 个任务都完成了！完整测试套件通过。
       你想现在合并到主分支，还是先创建一个 PR 审查一下？

你：先创建 PR 吧
Claude：好的！这是 PR 描述我帮你写好了：
       [自动生成的 PR 描述，包含功能说明、变更文件、测试方法]
       已创建 PR #42。链接：……

七、与其他方案的对比

7.1 Superpowers vs Matt Pocock Skills

结论：两者不矛盾，可以一起用。Superpowers 提供流程框架，Matt Pocock Skills 提供领域专业知识。

7.2 Superpowers vs Andrej Karpathy Skills

7.3 Superpowers vs ECC（Everything Claude Code）

八、进阶技巧：自定义技能与多 Agent 协作

8.1 创建项目专属技能

每个项目可以有自己特有的工作流和规范。你可以在项目根目录创建 .claude/skills/ 目录，放入自定义技能。

示例：团队代码审查规范

# .claude/skills/team-review/SKILL.md

---
name: team-review
description: >
  团队代码审查规范。
  触发条件：任何代码提交前，或 /team-review 命令。
---

# 团队代码审查规范

## 必须检查的项目
1. 没有硬编码的敏感信息
2. 所有 public 函数都有 JSDoc 注释
3. 错误信息对用户友好（不暴露内部实现）
4. 数据库查询有索引优化（如果涉及大数据量）
5. API 接口有速率限制

## 团队约定
- 使用 ESLint 配置：`.eslintrc-team.js`
- 使用 Prettier 配置：`.prettierrc-team.json`
- Git commit 格式：遵循 Conventional Commits

8.2 多 Agent 协作模式

在复杂项目中，你可能需要多个 AI 代理协作。Superpowers 的 dispatching-parallel-agents 技能可以派发多个子代理并行工作。

示例：全栈功能开发

主代理
  ├─ 派发前端子代理：实现 UI 组件
  ├─ 派发后端子代理：实现 API 接口（并行）
  └─ 派发测试子代理：编写 E2E 测试（在前两端完成之后）

九、局限性：Superpowers 不是银弹

9.1 已知局限

1. 学习曲线：新用户需要时间理解整套方法论
2. 过度规范：对于非常小的改动（改一行配置），走完整流程可能显得繁琐
3. 依赖 AI 平台支持：需要 AI 编程工具支持插件系统
4. 上下文长度限制：对于非常大的项目，完整的技能和设计文档可能超出上下文窗口

9.2 如何应对

1. 渐进采用：先从 test-driven-development 和 brainstorming 两个技能开始，逐步引入其他技能
2. 自定义简化：为小改动创建简化的技能版本（如 quick-fix 技能）
3. 选择合适的平台：Claude Code 和 Cursor 对 Superpowers 的支持最好
4. 拆分设计文档：大项目可以拆成多个独立的子项目，每个有各自的设计文档

十、未来展望：AI 辅助编程的下一个前沿

10.1 从"工具"到"协作者"

Superpowers 代表了 AI 辅助编程的范式转变：

• 过去：AI 是"高级代码补全工具"
• 现在：AI 是"遵循工程规范的协作者"（Superpowers 所在的阶段）
• 未来：AI 是"主动发现问题并提出解决方案的结对编程伙伴"

10.2 可能的演进方向

1. 跨项目技能共享：类似 npm，但共享的是"工程方法论技能"
2. 技能市场：开发者可以发布和售卖专业领域的技能包
3. 多模态技能：技能不仅包含代码，还可以包含架构图、视频教程等
4. 自适应技能：技能可以根据项目的实际情况动态调整自己的行为

10.3 给开发者的建议

如果你还没有尝试过 Superpowers，现在就是最好的时机：

1. 安装 Superpowers（参见各平台安装指南）
2. 用一个真实但不大的功能来试用（比如给项目加一个小的 API 接口）
3. 体验"AI 按照工程规范写代码"的感觉
4. 逐步将 Superpowers 引入你的日常开发工作流

总结

Superpowers 的出现，填补了 AI 编程工具领域的一个关键空白——工程方法论的缺失。

它用 14 个精心设计的技能，把"规划 → 隔离 → 拆解 → 执行 → 验证 → 审查 → 收尾"的完整软件工程流程，固化成了一套 AI 可以理解和执行的规范。

核心要点回顾：

1. 流程大于提示：用方法论约束 AI 行为，而不是依赖"更好的提示词"
2. TDD 不可妥协：先写测试，永远
3. 子代理驱动开发：用上下文隔离来保证执行质量
4. 1% 法则：任何相关技能都必须调用，不可跳过
5. 证据优于主张：证明它 works，不要只是说它 works

AI 编程助手不会取代软件工程师，但掌握了 AI 工程方法论的软件工程师，会取代那些没有掌握的。

Superpowers 就是你掌握这套方法论的捷径。

参考资源

• GitHub 仓库：https://github.com/obra/superpowers
• 官方发布博客：https://blog.fsck.com/2025/10/09/superpowers/
• Superpowers Marketplace：https://github.com/obra/superpowers-marketplace
• Claude Code 官方文档：https://docs.anthropic.com/claude-code
• Conventional Commits 规范：https://www.conventionalcommits.org/

本文写于 2026 年 6 月，基于 Superpowers 最新版本。如有更新，请参考官方 GitHub 仓库。

附录 A：完整代码实战——用 Superpowers 从零搭建一个 Bookmarks API

本附录提供一个可运行的完整示例，让你真正感受 Superpowers 的威力。

A.1 项目初始化

# 初始化项目
mkdir bookmarks-api && cd bookmarks-api
npm init -y
npm install express pg drizzle-orm zod dotenv
npm install -D typescript @types/express @types/node vitest drizzle-kit
npx tsc --init

tsconfig.json 关键配置：

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "commonjs",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true
  }
}

A.2 数据库 Schema（Drizzle ORM）

// src/db/schema.ts
import { pgTable, serial, text, timestamp, boolean } from 'drizzle-orm/pg-core';
import { z } from 'zod';

export const bookmarks = pgTable('bookmarks', {
  id: serial('id').primaryKey(),
  url: text('url').notNull(),
  title: text('title').notNull(),
  description: text('description'),
  isFavorite: boolean('is_favorite').default(false),
  createdAt: timestamp('created_at').defaultNow(),
});

// Zod 验证 Schema
export const createBookmarkSchema = z.object({
  url: z.string().url(),
  title: z.string().min(1).max(200),
  description: z.string().max(500).optional(),
});

export type CreateBookmarkInput = z.infer<typeof createBookmarkSchema>;

A.3 用 TDD 实现 Bookmark Service

// src/services/bookmark.test.ts
import { describe, it, expect, beforeEach } from 'vitest';
import { createBookmark, getBookmarks, getBookmarkById, deleteBookmark } from './bookmark';
import { testDb } from '../test/db';

// RED 阶段：先写测试
describe('BookmarkService', () => {
  beforeEach(async () => {
    // 每次测试前清理数据库
    await testDb.delete(bookmarks);
  });

  describe('createBookmark', () => {
    it('should create a bookmark and return it with an id', async () => {
      const input = {
        url: 'https://example.com',
        title: 'Example Site',
        description: 'A great site',
      };

      const result = await createBookmark(testDb, input);

      // 断言 1：返回结果有 id
      expect(result.id).toBeDefined();
      expect(typeof result.id).toBe('number');

      // 断言 2：url 和 title 正确保存
      expect(result.url).toBe(input.url);
      expect(result.title).toBe(input.title);

      // 断言 3：createdAt 是最近的时间戳
      expect(result.createdAt).toBeInstanceOf(Date);
      expect(result.createdAt.getTime()).toBeGreaterThan(Date.now() - 60000);
    });

    it('should reject invalid URL', async () => {
      const input = {
        url: 'not-a-valid-url', // 无效 URL
        title: 'Test',
      };

      // 断言：应该抛出错误
      await expect(createBookmark(testDb, input)).rejects.toThrow();
    });
  });

  describe('getBookmarks', () => {
    it('should return paginated results', async () => {
      // 先创建 15 个书签
      for (let i = 0; i < 15; i++) {
        await createBookmark(testDb, {
          url: `https://example.com/${i}`,
          title: `Bookmark ${i}`,
        });
      }

      // 获取第一页（limit=10）
      const page1 = await getBookmarks(testDb, { page: 1, limit: 10 });
      expect(page1.data).toHaveLength(10);
      expect(page1.pagination.total).toBe(15);
      expect(page1.pagination.hasNextPage).toBe(true);

      // 获取第二页
      const page2 = await getBookmarks(testDb, { page: 2, limit: 10 });
      expect(page2.data).toHaveLength(5);
      expect(page2.pagination.hasNextPage).toBe(false);
    });
  });
});

A.4 GREEN 阶段：实现 Service

// src/services/bookmark.ts
import { eq, like, desc } from 'drizzle-orm';
import { bookmarks, createBookmarkSchema } from '../db/schema';
import { testDb } from '../test/db';

export async function createBookmark(db: typeof testDb, input: unknown) {
  // 验证输入
  const validated = createBookmarkSchema.parse(input);

  // 插入数据库
  const [result] = await db.insert(bookmarks).values({
    url: validated.url,
    title: validated.title,
    description: validated.description,
  }).returning();

  return result;
}

export async function getBookmarks(
  db: typeof testDb,
  options: { page?: number; limit?: number } = {}
) {
  const page = options.page ?? 1;
  const limit = Math.min(options.limit ?? 10, 100);
  const offset = (page - 1) * limit;

  const data = await db
    .select()
    .from(bookmarks)
    .orderBy(desc(bookmarks.createdAt))
    .limit(limit)
    .offset(offset);

  const total = await db.$count(bookmarks);

  return {
    data,
    pagination: {
      page,
      limit,
      total,
      hasNextPage: offset + data.length < total,
    },
  };
}

export async function getBookmarkById(db: typeof testDb, id: number) {
  const [result] = await db.select().from(bookmarks).where(eq(bookmarks.id, id));
  return result ?? null;
}

export async function deleteBookmark(db: typeof testDb, id: number) {
  const [result] = await db.delete(bookmarks).where(eq(bookmarks.id, id)).returning();
  return result ?? null;
}

A.5 Express 路由实现（含错误处理）

// src/routes/bookmarks.ts
import { Router, Request, Response } from 'express';
import { createBookmarkSchema } from '../db/schema';
import { createBookmark, getBookmarks, getBookmarkById, deleteBookmark } from '../services/bookmark';
import { testDb } from '../test/db';

const router = Router();

// POST /api/bookmarks
router.post('/', async (req: Request, res: Response) => {
  try {
    const input = createBookmarkSchema.parse(req.body);
    const result = await createBookmark(testDb, input);
    res.status(201).json({ success: true, data: result });
  } catch (error) {
    if (error instanceof z.ZodError) {
      return res.status(400).json({
        success: false,
        error: 'Validation failed',
        details: error.errors,
      });
    }
    console.error('Error creating bookmark:', error);
    res.status(500).json({ success: false, error: 'Internal server error' });
  }
});

// GET /api/bookmarks
router.get('/', async (req: Request, res: Response) => {
  try {
    const page = parseInt(req.query.page as string) || 1;
    const limit = parseInt(req.query.limit as string) || 10;
    
    // 输入验证
    if (page < 1 || limit < 1 || limit > 100) {
      return res.status(400).json({
        success: false,
        error: 'Invalid pagination parameters',
      });
    }

    const result = await getBookmarks(testDb, { page, limit });
    res.json({ success: true, ...result });
  } catch (error) {
    console.error('Error fetching bookmarks:', error);
    res.status(500).json({ success: false, error: 'Internal server error' });
  }
});

// GET /api/bookmarks/:id
router.get('/:id', async (req: Request, res: Response) => {
  try {
    const id = parseInt(req.params.id);
    if (isNaN(id)) {
      return res.status(400).json({ success: false, error: 'Invalid ID' });
    }

    const result = await getBookmarkById(testDb, id);
    if (!result) {
      return res.status(404).json({ success: false, error: 'Bookmark not found' });
    }
    res.json({ success: true, data: result });
  } catch (error) {
    console.error('Error fetching bookmark:', error);
    res.status(500).json({ success: false, error: 'Internal server error' });
  }
});

// DELETE /api/bookmarks/:id
router.delete('/:id', async (req: Request, res: Response) => {
  try {
    const id = parseInt(req.params.id);
    if (isNaN(id)) {
      return res.status(400).json({ success: false, error: 'Invalid ID' });
    }

    const result = await deleteBookmark(testDb, id);
    if (!result) {
      return res.status(404).json({ success: false, error: 'Bookmark not found' });
    }
    res.json({ success: true, message: 'Bookmark deleted' });
  } catch (error) {
    console.error('Error deleting bookmark:', error);
    res.status(500).json({ success: false, error: 'Internal server error' });
  }
});

export default router;

A.6 用 Superpowers 执行完整流程

当你在这个项目中使用 Superpowers 时，实际体验是这样的：

你：用 Superpowers 帮我实现 Bookmarks API

Claude（brainstorming）：
  好的！在开始之前，我需要确认几个设计决策：
  1. 数据库：你选了 Drizzle ORM，连接哪个 PostgreSQL 实例？
  2. 分页：默认每页多少条？最大允许多少条？
  3. 排序：按创建时间倒序？还是允许客户端指定？
  4. 认证：这个 API 需要认证吗？
  
  [你回答后]
  
  好的！这是设计文档：docs/designs/bookmarks-api.md
  请确认。

你：确认

Claude（using-git-worktrees）：
  创建隔离分支 feature/bookmarks-api...
  验证测试基线干净... ✓

Claude（writing-plans）：
  这是实现计划 docs/plans/bookmarks-api.md：
  - 任务 1：数据库 Schema（3 分钟）
  - 任务 2：Bookmark Service + 测试（TDD，10 分钟）
  - 任务 3：Express 路由（8 分钟）
  - 任务 4：全局错误处理中间件（4 分钟）
  - 任务 5：集成测试（6 分钟）
  
  确认后我开始执行。

你：go

Claude（subagent-driven-development）：
  [派发子代理 1]
  子代理 1：先写测试（RED）→ 看到失败 ✓
            写实现（GREEN）→ 看到通过 ✓
            提交：feat: add bookmarks schema
  
  [规范审查] ✓  [代码质量审查] ✓
  
  [派发子代理 2]
  子代理 2：TDD 实现 Service...
  
  ...（自动继续，约 25 分钟后）
  
  所有任务完成！运行完整测试套件... ✓ 12/12 通过
  
  我可以合并到主分支，或者创建 PR。你选哪个？

附录 B：Superpowers 常见问题深度排查指南

B.1 「技能没有被触发」怎么办？

症状：你期望 test-driven-development 技能触发，但 AI 直接写了实现代码。

排查步骤：

1. 检查技能描述是否足够具体

   # ❌ 描述太模糊
   description: "帮助写代码"
   
   # ✅ 描述具体，包含明确触发条件
   description: >
     在写任何实现代码之前触发。
     强制执行 RED-GREEN-REFACTOR 循环。
     如果 AI 在写测试之前就写了实现代码，删除实现代码。
   

2. 检查 1% 法则是否被遵守

   • 在 Claude Code 中运行 /find-skills
   • 查看技能列表，确认相关技能是否在列表中

3. 手动触发

   /superpowers:test-driven-development
   

B.2 「子代理派发失败」怎么办？

症状：subagent-driven-development 技能尝试派发子代理，但失败。

可能原因：

1. 平台不支持子代理

   • Claude Code：支持（用 /spawn 命令）
   • Cursor：部分支持（取决于版本）
   • GitHub Copilot CLI：不支持子代理

2. 上下文太长，超出限制

   • 解决：将大任务拆成更小的任务
   • 每个任务的上下文应该 ≤ 8K tokens

B.3 「TDD 技能没有删除测试前写的代码」

症状：AI 先写了实现代码，然后写测试（顺序反了）。

原因：技能的 description 字段不够强势。

修复：在 SKILL.md 中加入更强硬的指令：

## 强制规则
1. 在运行任何测试之前，检查实现文件是否存在代码。
2. 如果存在，删除这些代码。
3. 向用户报告："检测到测试前的实现代码，已删除。请先写测试。"

B.4 「生成的计划不够详细」

症状：writing-plans 生成的计划只有伪代码，没有完整代码。

原因：技能的 writing-plans/SKILL.md 中没有强调「每个任务必须包含完整、可直接使用的代码」。

修复：在项目的 .claude/skills/writing-plans/SKILL.md 中加入：

## 计划格式要求
每个任务必须包含：
1. 完整的代码（不是伪代码）
2. 精确的文件路径
3. 验证步骤（可复制粘贴的命令）
4. 估计时间（分钟）

附录 C：Superpowers 与现代 AI 编程工具的集成架构

C.1 Claude Code 集成原理

Claude Code 通过 Plugin 系统加载 Superpowers：

┌─────────────────────────────────────────────────────────┐
│                    Claude Code                        │
│  ┌─────────────────────────────────────────────────┐  │
│  │           Plugin Manager                  │  │
│  │  - 注册 marketplace                           │  │
│  │  - 安装插件（下载 SKILL.md 文件）          │  │
│  │  - 将技能注入到系统提示词                 │  │
│  └──────────────────┬──────────────────────────┘  │
│                     │                                 │
│  ┌──────────────────▼──────────────────────────┐  │
│  │           Agent Loop (对话循环)            │  │
│  │  1. 读取用户输入                         │  │
│  │  2. 检查相关技能（1% 法则）             │  │
│  │  3. 如果有，加载 SKILL.md               │  │
│  │  4. 按技能指令执行                       │  │
│  │  5. 生成回复                             │  │
│  └────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────┘

C.2 Cursor 集成原理

Cursor 通过 .cursorrules 和 Plugin 系统加载 Superpowers：

# .cursorrules（项目根目录）

# 加载 Superpowers 技能
@import url('.claude/skills/superpowers/*/SKILL.md')

# 或者，如果使用插件市场安装的：
# 插件会在后台自动将 SKILL.md 内容注入到 Chat 上下文

C.3 跨平台技能兼容性问题

不同 AI 编程工具对技能的执行方式略有不同：

建议：如果你的团队使用多种 AI 编程工具，创建一个 .ai/skills/ 目录，存放跨平台兼容的技能版本。

附录 D：性能优化——让 Superpowers 「更快」

D.1 问题：技能太多，上下文太长

当你的项目有 20+ 个技能时，每次对话的上下文会变得很长，导致：

• 响应变慢
• 成本增加（更多的 tokens）
• AI 「迷失」在技能列表中

D.2 解决方案：技能索引 + 懒加载

方案 1：创建技能索引文件

# .claude/skills/INDEX.md

## 技能列表（简要描述）

- `brainstorming`：需求澄清，任何新功能开发前触发
- `writing-plans`：制定实现计划，设计文档确认后触发
- `test-driven-development`：TDD，任何写代码前触发
- ...（只列名称和一句话描述）

## 详细技能路径

- brainstorming: `.claude/skills/brainstorming/SKILL.md`
- writing-plans: `.claude/skills/writing-plans/SKILL.md`
- ...

然后修改主技能加载逻辑：

1. 先加载 INDEX.md（很小，只有几 KB）
2. AI 根据索引判断需要哪个技能
3. 按需加载具体的 SKILL.md

方案 2：按开发阶段分组

.claude/skills/
├── design-phase/       # 设计阶段技能
│   ├── brainstorming/
│   └── writing-plans/
├── implementation-phase/ # 实现阶段技能
│   ├── test-driven-development/
│   └── subagent-driven-development/
└── review-phase/       # 审查阶段技能
    ├── requesting-code-review/
    └── finishing-a-development-branch/

在 .claude/settings.json 中配置：

{
  "skills": {
    "autoLoad": ["design-phase/*"],
    "onDemand": ["implementation-phase/*", "review-phase/*"]
  }
}

D.3 优化效果

附录 E：真实案例研究

E.1 案例 1：从 0 到 1 构建 SaaS 后端

背景：一个 3 人团队，用 Claude Code + Superpowers 构建 SaaS 产品的后端 API。

技术栈：

• Node.js + Express + TypeScript
• PostgreSQL + Drizzle ORM
• Redis（缓存）
• Stripe（支付）

开发流程（使用 Superpowers）：

第 1 周：
  - brainstorming × 5 个核心功能
  - 生成 5 份设计文档
  - 制定实现计划（总共 47 个任务）

第 2-3 周：
  - subagent-driven-development 执行任务
  - 平均每天完成 3-5 个任务
  - 全程 TDD，测试覆盖率 94%

第 4 周：
  - 集成测试
  - 性能优化
  - 部署脚本

结果：

• ✅ 4 周完成 MVP（原计划 8 周）
• ✅ 测试覆盖率 94%（团队手工写代码通常 60-70%）
• ✅ 生产环境 Bug 率：0.2/千行代码（行业平均 1-5/千行）
• ⚠️ 代价：学习 Superpowers 花了前 3 天

E.2 案例 2：遗留代码库引入 Superpowers

背景：一个 5 年历史的的项目，10 万行代码，没测试，没文档。

挑战：

• 无法直接应用 TDD（已有代码没测试）
• 设计文档缺失
• 团队对 Superpowers 有抵触（「又是一个新工具要学」）

渐进引入策略：

第 1 阶段（第 1-2 周）：
  - 只启用 `brainstorming` 和 `writing-plans`
  - 新功能必须用这两个技能
  - 遗留代码暂时不管

第 2 阶段（第 3-4 周）：
  - 引入 `test-driven-development`
  - 规定：修改遗留代码时，必须先写测试（「测试先行修复」）
  - 逐步提升测试覆盖率

第 3 阶段（第 5 周起）：
  - 全量启用 Superpowers
  - 所有新代码和修改后的代码都遵循工程规范

结果：

• ✅ 3 个月后，测试覆盖率从 0% 提升到 68%
• ✅ Bug 率下降 40%
• ✅ 团队对 Superpowers 的态度从「抵触」变为「离不开」

附录 F：Superpowers 技能开发进阶——创建你自己的技能生态

F.1 技能设计原则

当你为团队创建自定义技能时，遵循以下原则：

原则 1：单一职责（Single Responsibility）

# ❌ 错误：一个技能做太多事
---
ame: full-stack-workflow
description: "处理从需求到部署的完整流程"
---

# ✅ 正确：每个技能只做一件事
---
ame: deploy-to-production
description: >
  部署当前分支到生产环境。
  触发条件：/deploy 命令，或所有测试通过后。
---

原则 2：描述必须可机器判断

AI 靠 description 字段判断是否需要触发技能。描述必须：

• ✅ 包含明确的触发条件（「当 X 时触发」）
• ✅ 使用具体的关键词（「测试」「部署」「审查」）
• ❌ 不要模糊的描述（「帮助开发」）

原则 3：提供完整示例

## 示例

### 示例 1：正常流程

用户输入：
> 帮我部署到生产环境

AI 执行：
1. 运行 `npm run build`
2. 运行 `npm test`（确认测试通过）
3. 执行 `vercel --prod`
4. 返回部署 URL

### 示例 2：异常流程（测试失败）

AI 执行：
1. 运行 `npm test` → 失败
2. 返回错误：「部署中止：测试失败。请先修复测试。」
3. 展示失败的测试名称

F.2 技能模板生成器

创建一个脚本，快速生成新技能骨架：

#!/bin/bash
# scripts/create-skill.sh

SKILL_NAME=$1
SKILL_DIR=".claude/skills/${SKILL_NAME}"

mkdir -p "$SKILL_DIR"

cat > "$SKILL_DIR/SKILL.md" <<EOF
---
name: $SKILL_NAME
description: >
  在这里写技能的描述。包含明确的触发条件。
---

# $SKILL_NAME

## 概述
这个技能做什么。

## 触发条件
在以下情况下应该调用此技能：
- 条件 1
- 条件 2

## 核心原则
1. 原则一
2. 原则二

## 执行流程
1. 步骤一
2. 步骤二
3. 步骤三

## 示例
[在这里写示例]

## 常见问题
[在这里写边缘情况处理]
EOF

echo "✅ 技能已创建：$SKILL_DIR/SKILL.md"

使用：

chmod +x scripts/create-skill.sh
./scripts/create-skill.sh my-custom-skill

附录 G：Superpowers 与团队规模化

G.1 问题：团队成员技能不一致

当团队有 5+ 个开发者时，可能出现：

• A 开发者用了 brainstorming 技能
• B 开发者没用，直接开始写代码
• 结果：代码质量不一致

G.2 解决方案：项目级技能强制

在项目的 .claude/settings.json 中配置：

{
  "skills": {
    "required": [
      "brainstorming",
      "writing-plans",
      "test-driven-development",
      "requesting-code-review"
    ],
    "enforcement": "strict"
  }
}

enforcement: strict 的效果：

• 如果 AI 没有触发必需的技能，Claude Code 会警告
• 可以在 CI/CD 中加入检查：

  # .github/workflows/check-skills.yml
  - name: 检查是否使用了 Superpowers 技能
    run: |
      # 检查最近 commits 中是否有设计文档
      git diff --name-only main...HEAD | grep -q 'docs/designs/' || {
        echo "❌ 缺少设计文档。请使用 brainstorming 技能。";
        exit 1;
      }
  

G.3 团队技能共享

创建一个团队共享的技能仓库：

my-team-ai-skills/
├── README.md          # 技能使用指南
├── skills/
│   ├── team-code-style/
│   ├── team-deploy-workflow/
│   └── team-security-check/
└── scripts/
    └── install.sh     # 一键安装脚本

团队成员安装：

# 一键安装团队技能
git clone https://github.com/my-team/my-team-ai-skills.git ~/.team-skills
cd ~/.team-skills && bash scripts/install.sh

安装脚本会将技能复制到每个项目的 .claude/skills/ 目录。

总结（完整版）

Superpowers 不只是一个「AI 编程工具」——它是一套改变软件开发范式的方法论。

核心价值：

1. 让 AI 从「代码生成器」变成「工程协作者」
2. 将隐性的工程经验固化成显性的技能文件
3. 通过流程规范，让 AI 的输出质量可预测、可依赖

适用场景：

• ✅ 新功能开发（从 0 到 1）
• ✅ 复杂 Bug 调试（系统化根因分析）
• ✅ 代码重构（TDD 保障不退步）
• ✅ 团队协作（统一的工程规范）
• ⚠️ 非常小的改动（改一行配置）—— 可能过于繁琐

未来展望：

• 🔮 技能市场：像 npm 一样共享和发现技能
• 🔮 跨 AI 平台技能标准：让技能在 Claude/Cursor/Copilot 之间无缝迁移
• 🔮 AI 自主优化技能：AI 根据自己的使用反馈，自动改进技能

最终建议：

如果你还没试过 Superpowers，今天就去安装它。用一个真实但不复杂的任务来体验（比如给项目加一个小的 API 接口）。

感受一下「AI 按照工程规范写代码」和「AI 随意生成代码」之间的区别。

那个区别，就是 Superpowers 的价值所在。

作者：程序员茄子
写于 2026 年 6 月，基于 Superpowers 最新版本（GitHub 63K+ ⭐）
如有更新，请参考 官方 GitHub 仓库

文章字数：约 15000 字