Superpowers 入门指南：让 AI 编程代理像资深工程师一样工作

时间：2026-3-6 10:48 作者：wanzi 分类： AI Coding

Superpowers 入门指南：让 AI 编程代理像资深工程师一样工作

📌 适合人群：使用 Claude Code / Cursor / Codex 等 AI 编程工具，希望提升代码质量、规范开发流程的开发者
⏱️ 阅读时间：约 15 分钟 | 🛠️ 技术栈：通用（支持多平台）

🎯 一、为什么你需要 Superpowers？

如果你用过 AI 编程工具，可能遇到过这些场景：

❌ "帮我加个用户登录"
→ AI 直接生成代码，没问权限模型、没考虑失败处理、没写测试
→ 上线后发现：短信验证码没对接、密码没加密、并发登录没控制

❌ "修复这个 bug"
→ AI 改了几行代码说"应该好了"
→ 但你不知道它改了什么、为什么这样改、会不会影响其他功能

问题的根源：大多数 AI 代理像"会写代码的实习生"——有技术能力，但缺乏工程思维。

Superpowers 的解法：把资深工程师的最佳实践（TDD、代码审查、系统化调试）编码成可执行的工作流，让 AI 代理自动遵循，而不是靠"自觉"。

💡 一句话理解：
Superpowers 不是另一个"提示词模板"，而是一套强制执行的工程规范系统，让 AI 从"能写代码"升级为"会做工程"。

🔑 二、核心概念：什么是"技能"（Skills）？

2.1 技能的本质

Skill = 一个可组合的"决策流程图" + "触发条件" + "反模式清单"

🗂️ 用 DOT/GraphViz 语法定义决策流程（不是装饰，是 AI 必须遵循的规范）
🎯 通过意图识别自动触发，无需手动调用命令
🚫 明确列出"什么情况下不该用"，防止误用

2.2 技能如何工作？（以 `test-driven-development` 为例）

当你说："加个用户注册接口"

1️⃣ 技能自动激活（检测到"新增功能"意图）
2️⃣ 强制进入 TDD 流程：
   ├─ RED: 先写测试用例（用户名校验、密码强度、重复注册...）
   ├─ 运行测试 → 预期失败 ✅
   ├─ GREEN: 写最小实现让测试通过
   ├─ 再次运行测试 → 全部通过 ✅
   └─ REFACTOR: 优化代码结构、提取公共逻辑
3️⃣ 如果试图跳过测试？技能会拦截并提醒："请先完成测试用例"

🔄 这不是"建议"，而是工作流引擎：流程图中的每个决策点都是强制检查项。

🚀 三、快速安装（按你的环境选择）

3.1 前置检查

# 确认你的 AI 工具版本
claude --version    # Claude Code >= 0.3.0
cursor --version    # Cursor Agent >= 1.5.0

3.2 平台安装指南

▶️ Claude Code（推荐，原生支持最好）

# 1. 添加插件市场
/plugin marketplace add obra/superpowers-marketplace

# 2. 安装 Superpowers
/plugin install superpowers@superpowers-marketplace

# 3. 验证安装
/help
# 看到以下技能即成功：
# - /superpowers:brainstorm    需求澄清
# - /superpowers:write-plan    任务拆解
# - /superpowers:execute-plan  执行计划

▶️ Cursor Agent

# 方式1：命令安装
/plugin-add superpowers

# 方式2：插件市场搜索 "superpowers" → Install

▶️ Codex / OpenCode

# 告诉 Codex 执行远程安装指令：
Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.codex/INSTALL.md

# OpenCode 一键脚本（macOS/Linux）：
curl -fsSL https://raw.githubusercontent.com/obra/superpowers/main/scripts/install-opencode.sh | bash

▶️ 本地开发调试（高级）

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

# 在 Claude Code 中加载本地版本
/plugin link ~/.superpowers

💡 macOS 用户注意：如果遇到权限问题，确保 ~/.config/ 目录可写，或使用 sudo 执行安装脚本。

🔄 四、完整工作流：从想法到上线的 6 个阶段

💡 你的输入："我想给系统加个节点心跳检测功能"
↓
🤖 Superpowers 自动触发工作流

阶段 1️⃣：头脑风暴（Brainstorming）— 先想清楚再动手

AI 不会直接写代码，而是像技术评审一样提问：

❓ 问题1：心跳间隔配置项放在哪里？（环境变量 / 配置文件 / 数据库？）
❓ 问题2：节点离线判定阈值是多少？连续3次超时？还是滑动窗口？
❓ 问题3：故障自修复的触发条件？自动重启？还是告警人工介入？
❓ 问题4：与现有状态管理机制如何集成？[参考用户记忆：状态=注册/注销/心跳离线]

✅ 输出：`docs/superpowers/specs/heartbeat-detection.md`
✅ 每 200-300 字一个小节，需要你确认"这部分对吗？"

阶段 2️⃣：工作区隔离（Git Worktrees）— 开发不污染主线

# AI 自动执行：
git worktree add -b feature/heartbeat-detection ../worktrees/heartbeat
cd ../worktrees/heartbeat

# 优势：
- 主分支代码不受影响
- 多个功能并行开发不冲突
- 随时可丢弃实验性分支

阶段 3️⃣：编写计划（Writing Plans）— 拆解到"无脑执行"级别

❌ 模糊任务："实现心跳检测"
✅ Superpowers 拆解：

[ ] 任务1: 创建 HeartbeatConfig 数据结构
   ├─ 文件：src/Config/HeartbeatConfig.php
   ├─ 字段：interval(秒), timeout_threshold, retry_count
   └─ 验证：phpunit tests/Unit/HeartbeatConfigTest.php

[ ] 任务2: 实现 sendHeartbeat() 基础方法
   ├─ 文件：src/Node/HeartbeatSender.php
   ├─ 依赖：Guzzle HTTP 客户端
   └─ 验证：Mock 服务器接收请求断言

[ ] 任务3: 编写超时检测单元测试（先写测试！）
   ├─ 文件：tests/Unit/HeartbeatTimeoutTest.php
   ├─ 用例：正常响应 / 超时 / 网络异常
   └─ 验证：phpunit --filter HeartbeatTimeoutTest

🎯 关键原则：每个任务必须小到 2-5 分钟能完成 + 有明确验证步骤

阶段 4️⃣：子代理驱动开发（Subagent-Driven）— 专注 + 审查

主代理为每个任务派遣"新鲜"子代理（无上下文污染）：

🔹 执行阶段：
   - 子代理只关注当前任务，不受其他逻辑干扰
   - 严格按计划执行，不"自由发挥"

🔹 两阶段审查（v4.0 核心创新）：
   阶段一：规格符合性
   ├─ 代码是否完全实现需求？
   ├─ 有没有多做/少做？
   └─ 文件路径、函数签名是否匹配计划？

   阶段二：代码质量（仅当阶段一通过）
   ├─ 测试覆盖率是否达标？
   ├─ 是否有重复代码/硬编码？
   └─ 错误处理是否完备？

🔁 审查不通过 → 自动修复 → 重新审查，直到✅

阶段 5️⃣：TDD 强制执行（RED-GREEN-REFACTOR）— 测试先行

这是最容易被跳过的环节，Superpowers 会强制：

🔴 RED: 先写会失败的测试
$ phpunit tests/Feature/HeartbeatTest.php
✓ 预期：1 个失败（因为 sendHeartbeat 还未实现）

⚠️ 如果测试一开始就通过？技能会拦截：
"测试未覆盖新功能，请检查用例设计"

🟢 GREEN: 写最小实现让测试通过
- 不追求完美，先让测试变绿
- 代码可以粗糙，但行为必须正确

🔵 REFACTOR: 重构优化
- 提取公共逻辑
- 添加类型声明
- 优化错误消息
- ✅ 重构后测试必须仍通过

阶段 6️⃣：收尾决策（Finishing）— 合并还是丢弃？

所有任务完成后，AI 呈现选项：

[1] ✅ 合并到主分支（测试全通过 + 审查通过）
[2] 📦 创建 Pull Request（团队协作场景）
[3] 💾 保留 worktree（后续继续开发）
[4] 🗑️  丢弃（实验性功能不满意）

# 选择后自动清理：
git worktree remove ../worktrees/heartbeat
git branch -D feature/heartbeat-detection

🧪 五、实战示例：为你的集群系统添加"节点掉线识别"

🎯 结合你的业务场景（多网络融合系统 + 状态管理 + Docker 部署）

5.1 启动头脑风暴

你输入：
"需要实现节点掉线自动识别，要求：
- 支持自定义超时阈值
- 掉线后触发告警
- 与现有状态机集成"

Superpowers 自动触发 brainstorming 技能，开始提问：

❓ 配置项存储方案？
   A) .env 环境变量（适合 Docker 部署）✅
   B) config/cluster.php 配置文件
   C) 数据库动态配置

❓ 掉线判定逻辑？
   A) 连续 N 次心跳超时（简单可靠）✅
   B) 滑动窗口统计（更精确但复杂）
   C) 结合网络质量动态调整

❓ 告警触发方式？
   A) 写入日志 + 邮件通知
   B) 调用 webhook（对接钉钉/企业微信）✅
   C) 推送 MQTT 消息（IoT 场景）

# 你选择 A + A + B，AI 生成设计文档

5.2 查看生成的计划（节选）

## 任务：实现节点超时检测器

### 前置条件
- [x] HeartbeatConfig 数据结构已存在
- [ ] 需要新增 NodeStatus::OFFLINE 状态

### 实现步骤
1. 创建 HeartbeatMonitor 类
   ```php
   // src/Monitor/HeartbeatMonitor.php
   class HeartbeatMonitor {
       public function checkTimeout(Node $node): bool {
           // 实现连续超时计数逻辑
       }
   }

编写单元测试（先写！）

// tests/Unit/HeartbeatMonitorTest.php
public function test_node_marked_offline_after_threshold() {
   // 模拟连续 3 次超时
   // 断言节点状态变为 OFFLINE
}

集成到状态机
- 修改 Node::updateStatus() 方法
- 添加事件监听：onNodeOffline → 触发告警

5.3 执行中的关键验证点

# 1. 测试必须先失败
$ phpunit --filter test_node_marked_offline
✗ Failed: HeartbeatMonitor::checkTimeout() not implemented

# 2. 实现后测试通过
✓ 1 test passed

# 3. 集成测试验证端到端流程
$ php tests/Integration/NodeOfflineWorkflowTest.php
✓ 节点超时 → 状态更新 → 告警触发 全流程通过

# 4. Docker 环境验证（结合你的部署经验）
$ docker-compose exec app phpunit
✓ 容器内测试同样通过，环境变量配置生效

⚙️ 六、高级技巧 & 避坑指南

6.1 技能触发机制（为什么有时不生效？）

✅ 正确触发方式：
- 使用自然语言描述任务："加个登录验证"、"修复这个超时问题"
- 包含明确意图：新增 / 修改 / 调试 / 优化

❌ 常见误区：
- 直接粘贴代码让 AI"看看哪里错了"（应使用 systematic-debugging 技能）
- 说"随便写个示例"（缺乏明确目标，技能无法匹配）

💡 调试技巧：
如果怀疑技能未触发，输入：
"/superpowers:debug last-intent"
查看 AI 识别到的意图和匹配的技能

6.2 自定义技能（结合你的扩展开发经验）

场景：你想为国标 28181 业务添加"指令签名验证"技能

1️⃣ 创建技能文件：skills/gb28181-signature/SKILL.md
2️⃣ 定义触发条件：

Use when:

用户提到"28181 指令"、"SIP 消息"、"签名验证"
涉及 API 安全、防重放攻击场景

3️⃣ 编写决策流程图（DOT 语法）：

   digraph signature_verify {
     start -> check_timestamp [label="检查时间戳"];
     check_timestamp -> verify_signature [label="时间戳有效"];
     verify_signature -> log_audit [label="签名通过"];
     verify_signature -> reject_request [label="签名失败"];
   }

4️⃣ 添加反模式清单：

   ❌ 不要：在技能描述中写"先检查时间戳再验证签名"
   ✅ 要：只在描述中写触发条件，流程细节放在流程图中

5️⃣ 测试技能触发：

   # 使用项目自带的测试框架
   php tests/SkillTriggerTest.php --skill=gb28181-signature


### 6.3 常见坑点 & 解决方案
| 问题现象 | 可能原因 | 解决方案 |
|---------|---------|---------|
| 技能不触发 | 提示词意图模糊 | 用"动词+名词"明确任务，如"实现用户登录验证" |
| 子代理执行超时 | 任务拆得太大 | 确保每个计划任务 ≤5 分钟可完成 |
| Windows 路径错误 | 单引号转义问题 | 升级到 v5.0.1+，或手动修改钩子脚本 |
| 测试环境不一致 | 本地/容器配置差异 | 在计划中明确指定`phpunit.xml` 配置路径 |
| 技能描述覆盖流程图 | AI 跟随简短描述忽略流程图 | 描述只写触发条件，流程细节放 DOT 图中 |

### 6.4 性能优化建议

🔹 减少上下文污染：

每个子代理任务使用独立 worktree
避免在计划中引用大文件（如完整日志）

🔹 加速测试执行：

在计划中指定--group=unit 只跑单元测试
使用phpunit --stop-on-failure 快速失败

🔹 缓存技能决策：

对于重复模式（如"新增 CRUD"），可复用已验证的计划模板
在docs/superpowers/templates/ 中保存常用方案

📊 七、什么场景推荐使用？（决策矩阵）

✅ 强烈推荐：
┌─────────────────────────────────┐
│ 🔹 新功能开发（需求→设计→实现）  │
│ 🔹 核心业务逻辑重构              │
│ 🔹 需要严格测试覆盖的模块        │
│ 🔹 团队协作时的代码规范统一      │
│ 🔹 学习工程最佳实践的新手        │
└─────────────────────────────────┘

⚠️ 谨慎使用：
┌─────────────────────────────────┐
│ 🔸 紧急 hotfix（流程较重）       │
│ 🔸 纯探索性原型（先用 brainstorm）│
│ 🔸 简单配置修改（杀鸡用牛刀）    │
└─────────────────────────────────┘

❌ 暂不推荐：
┌─────────────────────────────────┐
│ 🔻 无测试基础设施的老项目        │
│ 🔻 需求极度模糊且无法澄清的场景  │
└─────────────────────────────────┘

💡 你的独特优势：
作为全栈工程师 + 安全项目产品经理，Superpowers 能帮你：

保障支付/集群等核心模块的工程基础（幂等性、一致性）[[15]][[16]]

将 Docker 部署经验 [[8]] 融入自动化测试验证

用writing-plans 技能拆解复杂的国标 28181 指令处理逻辑 [[18]]

🎁 八、附：速查清单（保存备用）

安装验证

# Claude Code 检查
/help | grep superpowers

# 技能列表
/superpowers:list

常用技能触发词

💡 需求阶段：
"我想做一个 X" → brainstorming
"这个功能怎么设计更好" → brainstorming

📋 计划阶段：
"把需求拆成可执行任务" → writing-plans
"这个任务怎么验证" → writing-plans

🔧 执行阶段：
"先写测试再实现" → test-driven-development
"修复这个 bug" → systematic-debugging

👀 审查阶段：
"帮我看看这段代码" → requesting-code-review
"这个实现符合要求吗" → subagent-driven-development

紧急跳过流程（不推荐但有时需要）

# 临时禁用某个技能（调试用）
/superpowers:disable test-driven-development

# 强制执行原始指令（绕过工作流）
/raw 直接写代码，不要走流程

⚠️ 注意：用完后记得重新启用，避免污染后续任务

🌟 结语：让工程思维成为 AI 的"肌肉记忆"

Superpowers 的本质，不是增加约束，而是降低认知负荷：

以前：
你 → 想清楚需求 → 写详细提示词 → 监督 AI 不跑偏 → 手动补测试 → 反复审查

现在：
你 → 说"加个登录功能" → Superpowers 自动引导全流程 → 你只需确认关键决策

🔑 核心收益：
把"应该怎么做"的工程知识，变成"必须这么做"的自动化流程，
让你从"监督实习生"升级为"审核资深工程师"。

🔄 GitHub 仓库

Superpowers 入门指南：让 AI 编程代理像资深工程师一样工作

Superpowers 入门指南：让 AI 编程代理像资深工程师一样工作

🎯 一、为什么你需要 Superpowers？

🔑 二、核心概念：什么是"技能"（Skills）？

2.1 技能的本质

2.2 技能如何工作？（以 test-driven-development 为例）

🚀 三、快速安装（按你的环境选择）

3.1 前置检查

3.2 平台安装指南

▶️ Claude Code（推荐，原生支持最好）

▶️ Cursor Agent

▶️ Codex / OpenCode

▶️ 本地开发调试（高级）

🔄 四、完整工作流：从想法到上线的 6 个阶段

阶段 1️⃣：头脑风暴（Brainstorming）— 先想清楚再动手

阶段 2️⃣：工作区隔离（Git Worktrees）— 开发不污染主线

阶段 3️⃣：编写计划（Writing Plans）— 拆解到"无脑执行"级别

阶段 4️⃣：子代理驱动开发（Subagent-Driven）— 专注 + 审查

阶段 5️⃣：TDD 强制执行（RED-GREEN-REFACTOR）— 测试先行

阶段 6️⃣：收尾决策（Finishing）— 合并还是丢弃？

🧪 五、实战示例：为你的集群系统添加"节点掉线识别"

5.1 启动头脑风暴

5.2 查看生成的计划（节选）

5.3 执行中的关键验证点

⚙️ 六、高级技巧 & 避坑指南

6.1 技能触发机制（为什么有时不生效？）

6.2 自定义技能（结合你的扩展开发经验）

📊 七、什么场景推荐使用？（决策矩阵）

🎁 八、附：速查清单（保存备用）

安装验证

常用技能触发词

紧急跳过流程（不推荐但有时需要）

🌟 结语：让工程思维成为 AI 的"肌肉记忆"

2.2 技能如何工作？（以 `test-driven-development` 为例）