Superpowers

📖 Superpowers

Superpowers 是一个智能体技能框架（Agentic Skills Framework），为 AI 编程助手提供结构化的软件开发方法论。它通过一系列预定义的技能（Skills），强制规范开发流程，防止 AI "偷懒" 或跳过关键步骤。

核心理念：

• 确定性流程：不按规矩来，AI 会拒绝执行
• Red Flags 机制：根据需求特征自动匹配对应技能
• 子智能体协作：复杂任务自动拆分给专用子代理

🚀 安装与配置

Claude Code 安装

方式一：官方市场（推荐）

bash
复制
/plugin install superpowers@claude-plugins-official

方式二：社区市场

bash
复制
/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplace

验证安装

bash
复制
/skill list
# 应显示：brainstorming, writing-plans, executing-plans, debugging, test-driven-development, reviewing-changes

其他平台安装

🧠 核心技能详解

Superpowers 包含 6 个核心技能，覆盖软件开发生命周期：

1. Brainstorming（需求澄清）

触发条件（Red Flags）：

• 需求模糊（"做个商城功能"）
• 用户说 "看看"、"试试"、"随便"
• 涉及技术选型未确定

功能：

• 苏格拉底式提问，逐步澄清需求
• 识别隐藏假设和边界条件
• 输出：明确的功能规格（非技术方案）

使用示例：

bash
复制
# 自然语言触发
"我想做个用户登录功能，你看看怎么做"

# 手动触发
/skill brainstorming

# AI 行为
[触发 brainstorming] 
→ "在写代码前，让我们先澄清几个关键问题：
   1. 支持哪些登录方式（邮箱/手机/第三方）？
   2. 需要多因素认证吗？
   3. 用户登出后 Token 如何处理？
   ..."

2. Writing-Plans（规划设计）

触发条件：

• 功能复杂（涉及 3+ 文件修改）
• 需要架构决策（数据库选型、接口设计）
• 未评估实现选项

功能：

• 强制 "设计优先"（Plan First）
• 分析 2-3 种实现方案，对比优缺点
• 识别依赖关系和风险点
• 输出：详细的实现计划文档

使用示例：

bash
复制
用户："帮我设计一个支持实时通知的购物车系统"

AI [触发 writing-plans]：
"这是一个复杂功能，我需要先制定详细计划。

方案对比：
1. **WebSocket 方案**：实时性强，但需维护长连接
2. **Server-Sent Events**：实现简单，单向通信足够
3. **轮询**：兼容性最好，但资源浪费

推荐方案：SSE + Redis Pub/Sub

实施步骤：
1. 设计数据库 Schema（cart_items, notifications 表）
2. 实现 CartService 核心逻辑
3. 搭建 SSE 连接管理器
4. 编写前端事件监听
5. 添加错误重连机制

风险点：并发修改时的数据一致性"

3. Executing-Plans（执行计划）

触发条件：

• 已有详细计划（手动提供或通过 writing-plans 生成）
• 多步骤实现任务
• 涉及跨文件协调

功能：

• 子智能体驱动：为每个子任务创建专门代理
• 严格按计划执行，不偏离
• 实时跟踪进度，处理阻塞点
• 输出：阶段性成果 + 状态报告

使用示例：

bash
复制
用户："按计划执行步骤 1-3"

AI [触发 executing-plans]：
"启动执行模式，创建子智能体...

[Worker-1] 数据库 Schema 设计
- 创建 migration 文件
- 添加索引优化
✅ 完成

[Worker-2] CartService 实现
- 编写 addItem/removeItem/updateQuantity 方法
- 实现库存检查逻辑
⚠️ 遇到阻塞：库存服务接口未定义
建议：先创建接口契约

[Worker-3] 等待 Worker-2..."

4. Debugging（调试）

触发条件：

• 用户说 "报错"、"有 bug"、"运行失败"
• 测试未通过
• 异常堆栈出现

功能：

• 系统化调试流程（复现 → 隔离 → 修复 → 验证）
• 强制写出最小复现代码
• 分析根因而非表面症状
• 输出：问题诊断报告 + 修复方案

使用示例：

bash
复制
用户："这段代码报 NullPointerException"

AI [触发 debugging]：
"进入调试模式。

步骤 1：收集上下文
- 错误堆栈：第 42 行 user.getProfile().getName()
- 可能原因：user 为 null 或 getProfile() 返回 null

步骤 2：构建假设
假设 A：user 对象未正确初始化
假设 B：数据库查询返回了不完整记录

步骤 3：设计验证实验
- 添加 null 检查点
- 打印 user 对象状态

步骤 4：验证修复
修复方案：Optional.ofNullable(user).map(...).orElse("Anonymous")

验证：编写单元测试覆盖边界情况"

5. Test-Driven-Development（TDD）

触发条件：

• 用户说 "实现...功能"（且已有测试框架）
• 明确提到 "测试"
• 重构现有代码

功能：

• 强制遵循 RED-GREEN-REFACTOR 循环
• 先写失败测试，再写实现代码
• 重构阶段不改变行为
• 输出：测试覆盖率报告 + 干净实现

使用示例：

bash
复制
用户："实现一个计算购物车总价的函数，要测试"

AI [触发 test-driven-development]：
"启动 TDD 模式。

🔴 RED：编写失败测试
test_calculate_total_with_single_item()
assert calculate_total([{"price": 10, "qty": 2}]) == 20
结果：失败（函数未定义）

🟢 GREEN：最小实现
def calculate_total(items):
    return sum(item["price"] * item["qty"] for item in items)
结果：测试通过

🔵 REFACTOR：优化
- 添加类型注解
- 处理空列表边界
- 提取折扣计算逻辑

最终：3 个测试用例全部通过，覆盖率 100%"

6. Reviewing-Changes（代码审查）

触发条件：

• 用户说 "审查"、"review"、"看看有没有问题"
• 代码修改完成后
• 准备提交前

功能：

• 两阶段审查：
  1. Read-Only 分析（不改动代码，只读）
  2. Refactor（基于分析结果优化）
• 检查代码异味、安全漏洞、性能陷阱
• 输出：审查报告 + 改进建议（或自动修复）

⚙️ 工作机制

Session Hook 自动注入

安装后，每次开启新会话时，SessionStart Hook 会自动注入 using-superpowers 元技能到你的系统提示中：

<session-start-hook><EXTREMELY_IMPORTANT>
You have Superpowers.

[using-superpowers 内容]
- 可用技能列表
- Red Flags 触发规则
- 调用格式规范
</EXTREMELY_IMPORTANT></session-start-hook>

注意：这不是加载所有技能详情，而是加载"技能目录 + 触发规则"。

按需加载机制

当你表达需求时：

1. AI 检查 using-superpowers 中的 Red Flags
2. 匹配到对应技能 → 实时加载该技能的完整 SKILL.md 内容
3. 执行技能规定的流程
4. 完成后卸载（或保留元技能）

示例流程：

用户输入 → 匹配 Red Flag（需求模糊）→ 加载 brainstorming skill 
→ 执行苏格拉底提问 → 输出澄清后的需求 → 卸载 brainstorming
→ 用户说 "开始实现" → 匹配 Red Flag（有明确需求）→ 加载 writing-plans
...

🎯 实际工作流示例

场景：开发用户认证模块

Round 1：需求澄清

bash
复制
用户："我要做个登录功能"

AI [自动触发 brainstorming]：
"在编码前，让我们澄清需求：
1. 登录方式？（邮箱密码 / 手机验证码 / 微信/GitHub OAuth）
2. 需要记住我吗？
3. 密码加密策略？
4. 失败重试限制？"

用户："邮箱+密码，需要记住我， bcrypt 加密，5次失败锁定"

Round 2：规划设计

bash
复制
用户："基于上面讨论，设计完整方案"

AI [自动触发 writing-plans]：
"设计方案：

架构：JWT + Refresh Token 机制
数据库：users 表（email, password_hash, failed_attempts, locked_until）
API 端点：
- POST /api/auth/login
- POST /api/auth/refresh
- POST /api/auth/logout

安全细节：
- bcrypt cost factor 12
- JWT 有效期 15 分钟，Refresh Token 7 天
- 失败 5 次锁定 30 分钟

文件清单：
1. database/migrations/001_create_users.sql
2. services/auth_service.py
3. api/routes/auth.py
4. tests/test_auth.py"

Round 3：TDD 实现

bash
复制
用户："按这个计划用 TDD 实现步骤 1-3"

AI [自动触发 test-driven-development]：
"RED: 编写测试 test_login_success, test_login_invalid_password...
GREEN: 实现 AuthService.login()
REFACTOR: 提取密码验证逻辑到单独方法

[执行中...]
✅ 所有测试通过（6/6）"

Round 4：代码审查

bash
复制
用户："审查一下刚才的代码"

AI [自动触发 reviewing-changes]：
"两阶段审查完成：

阶段 1 发现：
- 问题：JWT secret 硬编码
- 风险：failed_attempts 可能存在竞态条件

阶段 2 修复：
- 已将 secret 移至环境变量
- 添加了数据库行级锁"

⚠️ 重要注意事项

1. 不是 "全或无" 触发

小需求不会触发 Superpowers：

• "把变量 x 改成 count" → 直接修改，不触发任何技能
• "加一行 console.log" → 普通对话模式

只有命中 Red Flags（如"设计一个..."、"有 bug"、"帮我看看"）才会激活。

2. 新会话才能加载

安装后必须开启新会话（Ctrl+C 退出当前，重新 cc），旧会话不会动态加载技能。

3. 无法并行使用多个技能

同一时间通常只有一个技能处于激活状态（除了 using-superpowers 元技能常驻）。

4. 手动覆盖

如果 AI 误判意图，你可以：

bash
复制
# 强制指定技能
/skill brainstorming

# 或明确告诉 AI 不要过度设计
"直接改就行，不用走 Superpowers 流程"

💡 最佳实践

1. 让流程自然触发

不要一开始就 /skill writing-plans，先描述需求，让 AI 判断是否需要规划：

bash
复制
# ✅ 好：触发自动判断
"我想设计一个购物车系统，支持实时库存检查"

# ❌ 差：跳过需求澄清
/skill executing-plans
[直接写代码，可能遗漏需求]

2. 分阶段使用

复杂项目分多轮对话：

1. 第 1 轮：Brainstorming（只澄清需求，不写代码）
2. 第 2 轮：Writing-Plans（出技术方案）
3. 第 3 轮：TDD + Executing（实现）
4. 第 4 轮：Reviewing（审查）

3. 处理过度设计

如果简单需求触发了复杂流程：

bash
复制
用户："只是个简单的变量重命名"
AI [误判，启动 brainstorming]：

用户打断："太复杂了，直接改就好"
AI："明白，立即执行重命名"

4. 结合 Git 使用

在 Writing-Plans 阶段就规划提交粒度：

bash
复制
AI [writing-plans]：
"建议分 3 个提交：
1. [feat] 添加用户模型和数据库迁移
2. [feat] 实现 JWT 生成和验证服务
3. [feat] 添加登录 API 端点"

🆚 与传统开发的区别

🔧 故障排除

📚 相关资源

• GitHub：https://github.com/obra/superpowers
• 官方文档：随插件安装的 /docs 目录
• 社区：Anthropic Discord #superpowers 频道
• 兼容工具：superpowers-markdown-exporter（导出计划文档为 Markdown）

记住：Superpowers 不是为了让开发变慢，而是为了防止在错误的方向上快速前进。前期的 Brainstorming 和 Planning 能避免后期的重大重构。

Happy Structured Coding! 🚀