Superpowers Pro — 工程化工作流增强系统
概述
Superpowers Pro 不是一个"技能"，而是一层工程纪律。它叠加在 WorkBuddy 之上，强制 AI 按照专业工程师的工作方式推进任务——先理解需求，再规划方案，然后测试驱动地实现，最后验证收尾。
> 大多数 AI 编程的问题不是"不会写代码"，而是"乱写代码"——没有需求理解就直接动手，没有测试就交付，没有验证就收工。Superpowers Pro 解决的就是这个根本问题。
这是目前社区中 Star 数最高的 AI 编程行为类技能，其核心理念是 TDD（测试驱动开发）、YAGNI（你不会需要它）和 DRY（不要重复自己）。
核心原则
TDD — 测试驱动开发
先写测试，再写实现。 这不是教条，而是最高效的开发方式：
- 测试定义了"完成"的标准——没有测试通过，就没有完成
- 测试是最精确的需求文档——代码会过时，测试不会
- 测试给了重构的勇气——有测试保护，才敢大刀阔斧改进
YAGNI — 你不会需要它
只实现当前需要的功能，不预留"未来可能用到"的抽象。
- ❌ "先加个配置项，以后可能需要切换"
- ✅ "当前只有一个场景，直接硬编码"
- 抽象应该在第三次重复时才引入，而非第一次
DRY — 不要重复自己
每个知识必须有单一、明确、权威的表示。
- 重复的代码 → 提取函数
- 重复的配置 → 提取常量
- 重复的逻辑 → 提取抽象
- 但 WET（Write Everything Twice）优于过早抽象——允许重复两次，第三次才 DRY
计划优先
在写任何代码之前，必须先输出可审阅的执行计划。 这避免了"prompt-first 乱写"导致的频繁返工。
工作流阶段
Superpowers Pro 将每个任务分为四个阶段，每个阶段都有质量门禁：
阶段一：澄清 — 理解需求
WorkBuddy 在动手之前，会主动澄清需求：
用户："帮我实现用户注册功能"
WorkBuddy 的澄清流程：
1. "注册需要哪些字段？"（用户名/邮箱/密码？手机号？）
2. "需要邮箱验证吗？"
3. "密码强度有要求吗？"
4. "需要防刷机制吗？（验证码/限流）"
5. "支持第三方登录吗？（OAuth）"
→ 所有疑问澄清后，进入规划阶段
澄清清单模板：
- [ ] 功能边界：做什么？不做什么？
- [ ] 输入输出：输入什么？输出什么？
- [ ] 边界条件：异常情况如何处理？
- [ ] 性能要求：并发量？响应时间？
- [ ] 兼容性：需要兼容哪些环境？
- [ ] 安全性：有哪些安全约束？
阶段二：规划 — 输出执行计划
需求澄清后，WorkBuddy 输出结构化执行计划，等待用户审批后才动手：
$super-plan "用户注册功能"
# WorkBuddy 输出：
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
执行计划：用户注册功能
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
## 影响范围
- 新增文件：src/auth/register.py, tests/auth/test_register.py
- 修改文件：src/models/user.py, src/api/routes.py
- 新增依赖：bcrypt, pyjwt
## 任务分解
1. 【测试】编写注册 API 的测试用例（先写测试）
- 测试正常注册流程
- 测试重复用户名
- 测试无效邮箱格式
- 测试弱密码拒绝
- 测试 SQL 注入防护
2. 【模型】扩展 User 模型，添加 password_hash 字段
3. 【实现】实现注册 API
- 密码加密（bcrypt）
- 输入验证（email format, password strength）
- 唯一性检查（username, email）
- 错误处理和响应格式
4. 【集成】注册路由挂载到 API
5. 【验证】运行全部测试，确保通过
## 风险评估
- ⚠️ 密码加密可能影响现有用户登录（需向后兼容）
- ⚠️ 数据库迁移需要停机（建议使用后台迁移）
确认执行此计划？(yes/no/edit)
用户可以选择：
- yes → 按计划执行
- no → 取消，重新讨论
- edit → 修改计划后执行
阶段三：实现 — TDD 驱动
计划批准后，进入实现阶段。严格遵循 Red-Green-Refactor 循环：
循环 1：正常注册流程
🔴 Red：编写测试 → 运行 → 失败（功能未实现）
🟢 Green：编写最小实现 → 运行测试 → 通过
🔵 Refactor：优化代码 → 运行测试 → 仍通过
循环 2：重复用户名检查
🔴 Red：编写测试 → 运行 → 失败
🟢 Green：实现唯一性检查 → 运行测试 → 通过
🔵 Refactor：提取验证逻辑 → 运行测试 → 通过
... 每个测试用例都走一遍循环
子 Agent 并行执行：
对于独立的子任务，WorkBuddy 可以派出多个子 Agent 并行处理：
$super-execute
# WorkBuddy 分析任务依赖关系：
# 任务 1（测试用例）→ 阻塞任务 3（实现）
# 任务 2（模型扩展）→ 阻塞任务 3（实现）
# 任务 4（路由挂载）→ 依赖任务 3
#
# 并行执行计划：
# ┌─ Agent A：任务 1（编写测试用例）
# └─ Agent B：任务 2（扩展模型）
# ↓ 汇合
# 主 Agent：任务 3（实现 API）
# ↓
# 主 Agent：任务 4（路由挂载）
# ↓
# 主 Agent：任务 5（验证）
阶段四：验证 — 收尾检查
实现完成后，WorkBuddy 执行全面验证：
$super-verify
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
验证报告
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
## 测试结果
✅ 全部 15 个测试通过
✅ 覆盖率 92%（目标 80%）
✅ 无跳过的测试
## 代码质量
✅ 无重复代码（DRY 检查通过）
✅ 无未使用的代码（YAGNI 检查通过）
✅ 函数复杂度均在阈值内
⚠️ register.py:42 行较长，建议拆分
## 安全检查
✅ 密码已加密存储
✅ 输入已验证
✅ SQL 注入防护到位
✅ 无硬编码密钥
## 文档
✅ 函数有 docstring
✅ README 已更新
❌ API 文档未更新 → 正在补充...
## 与计划对比
- 计划任务：5/5 完成
- 计划外发现：1 个（补充了密码强度提示功能）
TDD 指南
测试编写规范
# tests/auth/test_register.py
import pytest
from src.auth.register import register_user
from src.models.user import User
class TestUserRegistration:
"""用户注册功能测试"""
def test_register_with_valid_data(self, db_session):
"""正常注册流程应成功"""
# Given
user_data = {
"username": "testuser",
"email": "test@example.com",
"password": "SecurePass123!"
}
# When
result = register_user(db_session, user_data)
# Then
assert result.success is True
assert User.query.filter_by(username="testuser").first() is not None
def test_register_with_duplicate_username(self, db_session, existing_user):
"""重复用户名应被拒绝"""
user_data = {
"username": existing_user.username,
"email": "new@example.com",
"password": "SecurePass123!"
}
result = register_user(db_session, user_data)
assert result.success is False
assert "用户名已存在" in result.error
def test_register_with_weak_password(self, db_session):
"""弱密码应被拒绝"""
weak_passwords = ["123", "password", "abc123"]
for pwd in weak_passwords:
user_data = {
"username": "testuser",
"email": "test@example.com",
"password": pwd
}
result = register_user(db_session, user_data)
assert result.success is False
测试金字塔
/\
/E2E\ ← 少量，验证完整用户流程
/------\
/集成测试\ ← 适量，验证模块间协作
/----------\
/ 单元测试 \ ← 大量，验证单个函数/类
/--------------\
测试命名
test_<行为>_<条件>：test_register_with_valid_datatest_<行为>_<条件>_should_<期望>：test_login_with_wrong_password_should_fail- 测试方法名就是需求描述——读测试名就能理解功能
质量门禁
每个阶段的通过条件：
| 阶段 | 门禁条件 | 未通过的处理 |
|---|---|---|
| 澄清 | 所有清单项已确认 | 继续提问，不进入下一阶段 |
| 规划 | 用户明确批准计划 | 修改计划后重新审批 |
| 实现 | 所有测试通过 | 修复代码，不进入验证 |
| 验证 | 测试+质量+安全全部通过 | 修复问题后重新验证 |
门禁不可跳过——这是 Superpowers Pro 的核心纪律。
配置
# .superpowers.yaml
superpowers:
# 工作流配置
workflow:
require_clarification: true # 强制需求澄清
require_plan_approval: true # 强制计划审批
require_tdd: true # 强制 TDD
require_verification: true # 强制验证
# TDD 配置
tdd:
min_coverage: 80 # 最低覆盖率
test_naming: "test_<behavior>" # 测试命名规范
parallel_agents: true # 启用子 Agent 并行
# 质量门禁
quality:
max_complexity: 10 # 函数最大复杂度
max_line_length: 100 # 最大行长度
no_duplication: true # DRY 检查
no_dead_code: true # YAGNI 检查
# 并行执行
parallel:
max_agents: 4 # 最大并行子 Agent 数
isolation: worktree # 隔离方式
最佳实践
1. 不要跳过澄清阶段
澄清阶段的 5 分钟，能节省实现阶段的 5 小时返工。如果 WorkBuddy 没有提问，主动触发：
$super-clarify "帮我实现这个功能"
2. 审查计划时关注边界
审查执行计划时，特别关注：
- 错误处理是否覆盖
- 边界条件是否考虑
- 是否有未列出的影响范围
3. 测试先行，永不动摇
即使是最简单的功能，也先写测试。测试是最好的需求文档和回归保护。
4. 信任但验证
子 Agent 并行执行后，主 Agent 必须验证所有子任务的产出，不能盲目信任。
5. 定期回顾
$super-retro --since "7 days ago"
# 回顾本周的计划质量、返工率、测试覆盖率趋势
常见问题
Q: TDD 会不会拖慢开发速度？
A: 短期看多写了测试代码，但长期看大幅减少 Bug 修复时间。研究表明 TDD 项目的 Bug 率降低 40-80%，整体交付速度反而更快。
Q: 可以跳过计划审批直接写代码吗？
A: 可以在 .superpowers.yaml 中设置 require_plan_approval: false，但不推荐。计划审批是防止返工的最有效关卡。
Q: 子 Agent 并行会冲突吗？
A: 每个子 Agent 在独立的 Git worktree 中工作，文件层面不会冲突。但如果多个 Agent 修改同一逻辑模块，可能产生语义冲突——主 Agent 在验证阶段会检查。
Q: 已有项目没有测试怎么办？
A: Superpowers Pro 支持"遗留代码模式"：对已有代码先补特征测试（Characterization Test），再进行重构。使用 $super-legacy start 启动。
Q: 非代码任务也适用吗？
A: 适用。澄清→规划→实现→验证的工作流适用于任何任务——写文档、做架构设计、技术调研等。
Superpowers Pro — 让 AI 像有纪律的工程师一样工作，而不是像实习生一样乱写。
