Superpowers 深度实战：让 AI 编程从「随意发挥」到「工程化落地」——204K Star 的 AI Agent 软件开发方法论完全指南（2026）
截至 2026 年 6 月，Superpowers 在 GitHub 上已获得超过 204K Stars，Anthropic 官方插件市场安装量突破 68 万次，是 Claude Code 生态中增长最快的插件，没有之一。
一、为什么需要 Superpowers？
1.1 AI 编程的「实习生困境」
2025 年到 2026 年，AI 编程工具（Claude Code、Cursor、GitHub Copilot、Codex）经历了爆发式增长。但一个核心问题始终没有解决：
AI 写代码很快，但写得「对」吗？
你肯定遇到过这些情况：
- 你让 AI 「帮我做个用户登录功能」，它噼里啪啦一顿输出，代码能跑，但没考虑密码哈希、没做输入校验、没写单元测试，更没考虑过 Session 安全
- 你让它「重构一下这个函数」，它改完之后，相关性依赖全崩了，还得你手动修复
- 你让它「修复这个 Bug」，它改了一个地方，却在另一个地方引入了新 Bug
这种现象，我称之为 「实习生困境」：AI 像一个刚入职的实习生，热情高涨、执行迅速，但缺乏软件工程的「纪律感」——不清楚什么时候该停下来思考，不知道什么时候该写测试，更不知道什么时候该主动发起代码评审。
1.2 Vibe Coding 的兴起与局限
2025 年底，Andrej Karpathy 提出了 Vibe Coding 概念——用自然语言「氛围编程」，让开发者专注于意图表达，AI 负责实现细节。这确实降低了编程门槛，让更多人能快速实现想法。
但 Vibe Coding 有个先天缺陷：它依赖开发者的经验和自律。如果你本身就是资深工程师，你知道什么时候该停、该测、该审；但如果你经验不足，Vibe Coding 会放大你的盲区，产出的代码能跑，但经不起生产环境的考验。
Superpowers 的作者 Jesse Vincent（GitHub @obra）看到了这个问题。他的解决方案是：
Process over Prompt（流程大于提示词）
不给 AI 更多「能力」，而是给 AI 套上软件工程的「纪律与护栏」，让它像资深工程师一样：先思考 → 再规划 → 后编码 → 必验证。
二、Superpowers 是什么？
2.1 核心定位
Superpowers 是一套完整的 AI 编程 Agent 软件开发方法论框架，基于一组可组合的「技能（Skills）」构建。它不是一个代码库，而是一套用 Shell 和 Markdown 编写的「职业技能包」，通过插件机制注入到 Claude Code、Cursor、Codex 等 AI 编程工具中。
核心设计哲学：
- 可组合的技能系统：每个技能是一个独立的能力模块，可以单独使用，也可以组合成完整工作流
- 流程强制：通过 Hook 机制，强制 AI 在特定阶段执行特定技能（比如：编码前必须先做头脑风暴）
- 方法论优先：不依赖模型的推理能力，而是用明确的工程流程来约束 AI 的行为
- 工具无关：通过插件机制支持 Claude Code、Cursor、Codex、OpenCode 等多个 AI 编程工具
2.2 架构概览
┌─────────────────────────────────────────────────────────┐
│ AI 编程工具层 │
│ (Claude Code / Cursor / Codex / OpenCode) │
└────────────────────┬────────────────────────────────────┘
│ 插件注入
┌────────────────────▼────────────────────────────────────┐
│ Superpowers 技能框架 │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ 开发流程 │ │ 质量保证 │ │ 调试元 │ │
│ │ 类技能 │ │ 类技能 │ │ 技能 │ │
│ └──────────┘ └──────────┘ └──────────┘ │
│ ┌──────────────────────────────────────────────┐ │
│ │ Hook 机制（流程强制） │ │
│ └──────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
三、14 个核心技能深度解析
截至 2026 年 6 月，Superpowers v5.1.0 包含 14 个核心技能，分为三大类。
3.1 开发流程类技能（6 个）
3.1.1 brainstorming —— 需求澄清与方案探索
触发时机：任何新功能开发之前（强制）
核心作用：防止 AI 「想当然」地直接写代码。它会通过提问帮你澄清需求、探索技术方案、识别潜在风险，并生成设计文档。
工作流程：
- 理解意图：AI 会读取你的初始需求，识别出模糊、不完整或可能引发歧义的地方
- 提出澄清问题：AI 会主动提问，比如：
- 「用户登录是用 Session 还是 JWT？」
- 「需要考虑第三方账号登录（OAuth）吗？」
- 「密码找回流程要做吗？」
- 探索技术方案：AI 会分析多种实现路径的优劣（比如：用现成的 Auth0 vs 自研）
- 生成设计文档：将讨论结果整理成结构化文档，保存到项目目录（默认
.superpowers/design.md）
实际案例：
# 用户需求：「帮我做个博客系统的评论功能」
## AI 通过 brainstorming 提出的澄清问题：
1. 匿名评论还是登录后评论？（涉及身份验证）
2. 需要评论审核机制吗？（防止垃圾评论）
3. 支持嵌套回复吗？（楼中楼结构）
4. 需要@提及功能吗？（涉及通知系统）
5. 评论支持 Markdown 吗？（需要渲染和安全过滤）
6. 需要防刷机制吗？（Rate Limiting）
## 生成的设计文档片段：
### 技术方案对比
| 方案 | 优点 | 缺点 | 推荐场景 |
|------|------|------|----------|
| 自研评论系统 | 完全可控、无第三方依赖 | 需要自己处理反垃圾、通知等 | 对定制化要求高 |
| 接入 Disqus | 快速上线、自带反垃圾 | 国外服务、加载慢、数据不在自己手里 | 快速 MVP |
| 使用 Giscus（GitHub Discussions） | 免费、无广告、数据在 GitHub | 需要 GitHub 账号才能评论 | 技术博客 |
3.1.2 writing-plans —— 任务拆解与执行计划
触发时机：设计文档确认后，编码开始前（强制）
核心作用：将模糊的需求转化为可执行的、有序的任务清单，每个任务都有明确的验收标准。
计划结构：
# 执行计划：博客评论功能
## Phase 1：数据模型设计（预估：1h）
### Task 1.1：设计 Comment 数据表
- [ ] 确定字段：id, post_id, user_id, content, parent_id, created_at, status
- [ ] 确定索引：post_id + created_at（查询优化）
- [ ] 确定状态枚举：pending / approved / spam
### Task 1.2：编写 Migration
- [ ] 使用 ORM（Prisma / TypeORM）编写 schema
- [ ] 生成并提交 migration 文件
## Phase 2：API 开发（预估：2h）
### Task 2.1：GET /api/comments?post_id=xxx
- [ ] 实现分页查询
- [ ] 支持按创建时间排序
- [ ] 返回嵌套结构（若有 parent_id）
### Task 2.2：POST /api/comments
- [ ] 校验用户身份（JWT / Session）
- [ ] 校验内容长度（1-2000 字符）
- [ ] XSS 过滤（使用 DOMPurify）
- [ ] Rate Limiting（同一用户 60s 内最多 5 条）
- [ ] 存入数据库，初始状态为 pending（需审核）
...
关键特性：
- 粒度控制：每个 Task 不应超过 2 小时工作量，确保可频繁提交和验证
- 依赖标注：用
depends_on: [Task 1.1]明确任务依赖关系 - 验收标准：每个 Task 都有明确的「完成定义」（Definition of Done）
3.1.3 executing-plans —— 按计划执行编码
触发时机：计划确认后
核心作用：严格按计划编码，不允许 AI 跳过任务或擅自修改计划。如果 AI 发现计划有问题，必须先更新计划，再继续执行。
执行规则：
- 逐任务执行：完成一个 Task，验证一个 Task，再进入下一个
- 实时同步进度：每完成一个 Task，更新计划文件（标记
[x]） - 遇到问题先停：如果某个 Task 无法实现（比如发现依赖的库有 Bug），立即停止，通知用户，更新计划
代码示例（AI 执行 Task 2.2 的伪代码流程）：
# AI 执行 POST /api/comments 时的思考过程（由 Superpowers 引导）
# Step 1：校验用户身份
# ✅ 检查 JWT token 是否有效
# ✅ 从 token 中解析 user_id
# Step 2：校验输入
# ✅ content 长度 1-2000
# ✅ post_id 必须存在（先查数据库）
# Step 3：安全过滤
# ✅ 用 bleach 或 DOMPurify 过滤 HTML 标签
# ✅ 禁止 <script> 标签
# Step 4：Rate Limiting
# ✅ 用 Redis 记录 user_id 的请求时间戳
# ✅ 60s 内超过 5 次 → 返回 429
# Step 5：存入数据库
# ✅ status = 'pending'（需要审核）
# ✅ 返回 201 + comment_id
3.1.4 subagent-driven-development —— 子 Agent 并行开发
触发时机：计划中有多个独立任务时
核心作用：利用 AI 的并行能力，同时启动多个「子 Agent」，分别处理不同的 Task，最后合并结果。
适用场景：
- 前后端可以并行开发（比如：后端写 API，前端写页面组件）
- 多个独立功能模块（比如：用户系统、评论系统、标签系统）
- 测试代码编写（可以与主代码编写并行）
工作流程：
主 Agent（项目经理角色）
├── 子 Agent A：负责后端 API（Task 2.1, 2.2, 2.3）
├── 子 Agent B：负责前端组件（Task 3.1, 3.2）
└── 子 Agent C：负责测试用例（Task 4.1, 4.2）
注意事项：
- 子 Agent 之间需要通过共享设计文档来保持接口一致
- 主 Agent 负责最终集成和冲突解决
3.1.5 using-git-worktrees —— Git 工作区隔离
触发时机：开始执行计划时
核心作用：为每个 Task 或 Phase 创建独立的 Git Worktree，避免不同任务之间的代码互相干扰。
为什么需要 Worktree？
传统做法是：一个功能分支，连续提交。但 AI 编程速度快，经常出现「写到一半发现方向不对，要回退」的情况。用 Worktree 可以：
- 每个 Task 在独立的目录中开发
- 随时可以放弃某个 Task 的改动，不影响其他 Task
- 最后用
git merge或git worktree merge合并
命令示例：
# Superpowers 会自动执行类似下面的命令
# 基于 main 分支，为 Task 2.1 创建独立工作区
git worktree add ../my-project-task-2.1 task-2.1-start
# AI 在 ../my-project-task-2.1 中工作
# 完成后，合并回主分支
git merge --no-ff task-2.1-start
3.1.6 finishing-a-development-branch —— 分支收尾与提交规范
触发时机：所有 Task 完成后，准备合并到主分支时
核心作用：确保提交历史清晰、commit message 规范、分支可以安全删除。
检查清单：
- 所有 Task 都已标记完成
- 代码通过了 Linter（ESLint / Prettier / gofmt）
- 所有测试通过（
npm test/pytest/go test） - 没有硬编码的敏感信息（用
grep -r "SECRET\|PASSWORD\|API_KEY"检查） - Commit message 符合规范（Conventional Commits）
- 删除了调试代码（
console.log/print()/# TODO: remove）
自动生成的 Commit Message 示例：
feat(comments): implement comment API with moderation support
- Add Comment model and migration
- Implement GET /api/comments with pagination
- Implement POST /api/comments with XSS protection
- Add rate limiting (5 requests per 60s per user)
- Add unit tests for comment service
Closes #123
3.2 质量保证类技能（5 个）
3.2.1 test-driven-development —— TDD 强制执行
触发时机：每个 Task 编码前
核心作用：强制 AI 先写测试，再写实现代码（Test-Driven Development）。
为什么 AI 需要 TDD？
AI 写代码时，往往会「乐观主义」——假设输入都是合法的、边界情况不会发生。TDD 可以强制 AI 考虑：
- 边界条件（空输入、超长字符串、负数、null）
- 异常情况（网络超时、数据库锁定、文件不存在）
- 并发问题（多个请求同时修改同一资源）
TDD 执行流程：
# Task：实现 POST /api/comments
# Step 1：先写测试（AI 必须先完成这一步）
def test_create_comment_success():
response = client.post("/api/comments", json={
"post_id": 1,
"content": "这是一条测试评论"
}, headers={"Authorization": f"Bearer {valid_token}"})
assert response.status_code == 201
assert response.json()["content"] == "这是一条测试评论"
assert response.json()["status"] == "pending"
def test_create_comment_unauthorized():
response = client.post("/api/comments", json={
"post_id": 1,
"content": "未授权评论"
})
assert response.status_code == 401
def test_create_comment_xss():
response = client.post("/api/comments", json={
"post_id": 1,
"content": "<script>alert('XSS')</script>"
}, headers={"Authorization": f"Bearer {valid_token}"})
# 内容应该被过滤
assert "<script>" not in response.json()["content"]
# Step 2：再写实现代码（让测试通过）
def create_comment(post_id, content, user_id):
# 实现代码...
pass
# Step 3：运行测试，确保全部通过
# pytest tests/test_comments.py
3.2.2 requesting-code-review —— 发起代码评审
触发时机：一个 Task 完成后（可选，但推荐）
核心作用：让 AI 以「资深工程师」的视角，对自己的代码进行评审，输出改进建议。
评审维度：
- 正确性：逻辑是否正确？边界情况是否处理？
- 安全性：有没有 SQL 注入、XSS、CSRF 等漏洞？
- 性能：有没有 N+1 查询？有没有不必要的全表扫描？
- 可维护性：变量命名是否清晰？函数是否过长？有没有重复代码？
- 测试覆盖：测试是否覆盖了关键路径？有没有遗漏的边界情况？
评审输出示例：
# Code Review：POST /api/comments 实现
## ✅ 做得好的地方
1. 使用了参数化查询，防止 SQL 注入
2. Rate Limiting 实现正确，用了 Redis 的 sorted set
3. XSS 过滤用了白名单策略（只允许 <b>, <i>, <code> 等安全标签）
## ⚠️ 需要改进的地方
1. **性能问题**：
- 在 `create_comment` 中，先 INSERT，再 SELECT 完整记录（两次数据库查询）
- 建议：用 `RETURNING *`（PostgreSQL）或 `LAST_INSERT_ID()`（MySQL）一次性获取
2. **安全问题**：
- Rate Limiting 的 Redis key 用了 `user_id`，但 `user_id` 是 JWT 中的 payload，可以被客户端伪造
- 建议：用 JWT 的 JTI（JWT ID）或 Session ID 作为 Rate Limiting 的 key
3. **测试覆盖不足**：
- 没有测试「评论内容包含 Emoji」的情况（数据库字符集可能不支持）
- 没有测试「并发创建评论」的情况（Race Condition）
## 🔴 必须修复
1. **SQL 注入风险**：
- 在 `get_comments_by_post` 函数中，用了 f-string 拼接 `ORDER BY {sort_field}`
- 如果 `sort_field` 来自用户输入，可以导致 SQL 注入
- 建议：用白名单校验 `sort_field in ["created_at", "likes_count"]`
3.2.3 receiving-code-review —— 处理评审意见
触发时机：requesting-code-review 完成后，或人类发起了代码评审
核心作用：AI 根据评审意见，逐一修复问题，并回复评审者。
处理流程：
- 理解评审意见：AI 会逐条分析评审意见，区分「必须修复」和「建议优化」
- 制定修复计划：对于多条意见，AI 会制定修复顺序（先修安全问题，再修性能问题）
- 执行修复：修改代码，并运行相关测试，确保没引入新问题
- 回复评审者：用礼貌、专业的语言回复每一条意见（如果是人类评审）
回复示例：
Thanks for the review! I've addressed all the issues:
1. ✅ **性能问题**：改用 `RETURNING *`，减少一次数据库查询（commit abc123）
2. ✅ **安全问题**：Rate Limiting 的 key 改为 JWT 的 JTI（commit abc124）
3. ✅ **SQL 注入风险**：用白名单校验 `sort_field`（commit abc125）
4. ⏳ **测试覆盖不足**：Emoji 和并发测试的添加我在 #124 中跟踪，这次先不加入（评论功能已经够复杂了）
All tests pass. PTAL (Please Take Another Look).
3.2.4 verification-before-completion —— 完成前验证
触发时机：所有 Task 完成后，准备合并时
核心作用：最后一次全面检查，确保代码质量、安全性、性能都没有明显问题。
验证清单（比 finishing-a-development-branch 更严格）：
- 功能验证：手动测试所有用户场景（Happy Path + Edge Cases）
- 安全扫描：用
bandit（Python）/npm audit（Node.js）/cargo audit（Rust）扫描依赖漏洞 - 性能基准：对关键 API 做压力测试（用
wrk/ab/hey） - 代码覆盖率：运行
coverage report，确保核心逻辑的覆盖率 > 80% - 文档完整性：API 文档（OpenAPI / Swagger）是否更新？README 是否需要修改？
3.2.5 using-git-bisect —— Git 二分调试（调试与元技能）
触发时机：发现了一个 Bug，但不知道是哪个提交引入的
核心作用：自动化 git bisect 流程，快速定位引入 Bug 的提交。
工作流程：
- 标记已知好的提交：
git bisect good <commit-hash> - 标记已知坏的提交：
git bisect bad HEAD - 运行测试：AI 会自动在每个二分提交上运行测试，标记 good 或 bad
- 定位结果：
git bisect会输出第一个引入 Bug 的提交
自动化脚本示例：
# Superpowers 会生成类似下面的脚本
git bisect start
git bisect bad HEAD
git bisect good v1.2.0
# 运行自动化测试
git bisect run pytest tests/test_comment_api.py -k "test_create_comment"
# 输出：
# Bisecting: 5 revisions left to test
# [abc123] Implement comment API
# Bisecting: 2 revisions left to test
# [def456] Add rate limiting to comment API
# Bisecting: 0 revisions left to test
# [789012] Fix XSS in comment content
# def456 is the first bad commit
3.3 调试与元技能类（3 个）
3.3.1 debugging-with-systematic-method —— 系统化调试方法
核心思想：不搞「瞎试」，而是用科学方法调试：
- 观察现象：准确描述 Bug 的表现（什么操作、什么输入、什么输出）
- 提出假设：可能的原因有哪些？（比如：缓存未更新、数据库事务未提交、Race Condition）
- 设计实验：如何验证假设？（比如：加日志、用调试器单步执行、写最小化复现脚本）
- 执行实验：运行实验，收集数据
- 分析结果：假设是否成立？如果不成立，回到步骤 2
3.3.2 asking-high-quality-questions —— 提问的艺术
当你（人类）或 AI 遇到无法解决的问题时，如何提问才能最快得到答案？
高质量提问模板：
## 问题标题：用一句话描述问题（包含关键信息）
### 环境
- OS：macOS 15.0 / Ubuntu 24.04
- 语言 / 框架版本：Python 3.13, FastAPI 0.115
- 相关依赖及版本：SQLAlchemy 2.0, Redis 7.2
### 预期行为
描述你期望发生什么
### 实际行为
描述实际发生了什么（附错误日志、截图）
### 最小复现步骤
1. 克隆仓库 xxx
2. 运行 `python main.py`
3. 访问 `http://localhost:8000/api/comments`
4. 看到 500 错误
### 我已尝试的解决方案
- 方案 A：无效，原因是...
- 方案 B：部分有效，但引入了新问题...
### 相关代码（最小化）
（粘贴关键代码片段，不超过 50 行）
3.3.3 managing-context-window —— 上下文窗口管理
为什么重要？ AI 模型（包括 Claude）有上下文窗口限制（比如 200K tokens）。当项目变大，单个会话的上下文会迅速耗尽，导致 AI 「失忆」。
管理策略：
- 定期压缩上下文：完成一个 Phase 后，让 AI 生成「阶段总结」，然后开启新会话
- 用文件代替上下文：把设计文档、执行计划、API 文档保存到文件，AI 需要时再读取（用
@filename引用） - 分离子任务：用
subagent-driven-development把大任务拆成小任务，每个子 Agent 只关注自己的上下文
四、安装与配置实战
4.1 Claude Code 安装（最推荐）
方式一：Anthropic 官方插件市场（最简单）
# 注册插件市场（只需一次）
/plugin marketplace add obra/superpowers -marketplace
# 安装 Superpowers
/plugin install superpowers@superpowers -marketplace
# 验证安装
/help
# 应该能看到 Superpowers 相关命令
方式二：从 GitHub 手动安装（适合定制）
# 克隆仓库到 Claude Code 的 plugins 目录
cd ~/.claude/plugins
git clone https://github.com/obra/superpowers.git
# 在 Claude Code 中加载本地插件
/plugin install ../superpowers
4.2 Cursor 安装
Cursor 的插件机制与 Claude Code 不同。Superpowers 通过 .cursor-plugin 目录提供支持。
# 在项目根目录中
git clone https://github.com/obra/superpowers.git .superpowers-temp
cp -r .superpowers-temp/.cursor-plugin ./
rm -rf .superpowers-temp
# 重启 Cursor，Superpowers 技能会自动加载
4.3 配置文件详解
安装完成后，Superpowers 会在你的项目目录中生成 .superpowers/ 配置目录：
.superpowers/
├── config.json # 全局配置（哪些技能启用、执行顺序）
├── design.md # 设计文档（brainstorming 输出）
├── plan.md # 执行计划（writing-plans 输出）
├── skills/
│ ├── brainstorming.md
│ ├── writing-plans.md
│ └── ... # 每个技能的详细提示词
└── hooks/
├── pre-encoding.json # 编码前强制执行的 Hook
└── post-task.json # 任务完成后强制执行的 Hook
config.json 示例：
{
"version": "5.1.0",
"enabled_skills": [
"brainstorming",
"writing-plans",
"executing-plans",
"test-driven-development",
"requesting-code-review"
],
"skill_order": {
"pre_encoding": ["brainstorming", "writing-plans"],
"during_encoding": ["executing-plans", "test-driven-development"],
"post_task": ["requesting-code-review", "verification-before-completion"]
},
"hooks": {
"enforce_brainstorming_before_coding": true,
"auto_update_plan_on_completion": true
}
}
五、完整实战：用 Superpowers + Claude Code 从零开发「JWT 认证中间件」
为了让你真正理解 Superpowers 的威力，我用一个完整实战案例来演示：从零开发一个 Express.js 的 JWT 认证中间件。
5.1 第一步：启动 Brainstorming
人类输入：
我想做一个 Express.js 的 JWT 认证中间件，支持：
- 从 Authorization header 提取 token
- 验证 token 合法性（签名、过期时间）
- 把解码后的 payload 挂载到 req.user
- 支持可选的白名单路径（比如 /health 不需要认证）
Claude Code（被 Superpowers 引导）：
🤔 我来帮你澄清需求并探索方案。
## 澄清问题
1. **JWT 签名算法**：你打算用 HS256（对称加密，共享密钥）还是 RS256（非对称加密，公钥/私钥对）？
- HS256 更简单，适合单体应用
- RS256 更安全，适合微服务（认证服务和资源服务分离）
2. **Token 过期处理**：Token 过期后，是直接返回 401，还是支持 Refresh Token 机制？
3. **白名单配置方式**：是用数组硬编码，还是支持从配置文件 / 数据库读取？
4. **错误处理**：认证失败时，返回的错误格式是什么？（统一的 JSON 错误格式？）
## 技术方案对比
### 方案 A：用现成的库（推荐）
- 库名：`express-jwt`（Auth0 官方维护）
- 优点：经过生产验证、支持 RS256/HS256、社区活跃
- 缺点：定制性稍弱（但满足你的需求）
### 方案 B：自己实现 JWT 验证
- 优点：完全可控、可以深度定制
- 缺点：容易出安全漏洞（比如：忘记校验 `alg` 字段，导致 `none` 算法攻击）
## 我的建议
用 **方案 A**（express-jwt），但自己封装一层，方便后续扩展。
要不要我写一个设计文档，详细列出 API 接口、配置方式、测试用例？
人类输入：「好的，用方案 A，帮我写设计文档」
（Superpowers 的 brainstorming 技能会将讨论结果保存到 .superpowers/design.md）
5.2 第二步：Writing Plans
Claude Code（被 Superpowers 引导）：
📝 设计文档已保存。现在我来制定执行计划。
# 执行计划：JWT 认证中间件
## Phase 1：项目初始化（预估 30min）
### Task 1.1：初始化 Express 项目
- [ ] npm init -y
- [ ] 安装依赖：express, express-jwt, jsonwebtoken, dotenv
- [ ] 配置 .env（JWT_SECRET 密钥）
- [ ] 配置 .gitignore
## Phase 2：核心中间件开发（预估 1.5h）
### Task 2.1：创建基础中间件函数
- [ ] 从 Authorization header 提取 Bearer token
- [ ] 处理 missing token → 返回 401
- [ ] 用 jsonwebtoken.verify() 验证签名
- [ ] 处理 TokenExpiredError → 返回 401 + "Token expired"
- [ ] 处理 JsonWebTokenError → 返回 401 + "Invalid token"
- [ ] 把 payload 挂载到 req.user
### Task 2.2：支持白名单配置
- [ ] 接受配置对象：{ whitelistedPaths: ["/health", "/public/*"] }
- [ ] 路径匹配逻辑（支持通配符）
- [ ] 白名单路径跳过认证
### Task 2.3：统一错误格式
- [ ] 定义错误响应格式：{ error: true, message: "..." }
- [ ] 用 next(error) 传递错误，由全局错误处理中间件统一响应
## Phase 3：测试（预估 1h）
### Task 3.1：单元测试
- [ ] 测试有效 token → req.user 正确挂载
- [ ] 测试过期 token → 401
- [ ] 测试无效 token → 401
- [ ] 测试白名单路径 → 跳过认证
### Task 3.2：集成测试
- [ ] 用 supertest 测试完整请求流程
## Phase 4：文档与发布（预估 30min）
### Task 4.1：编写 README
- [ ] 安装说明
- [ ] 使用示例
- [ ] 配置说明
### Task 4.2：发布到 npm（可选）
- [ ] 配置 package.json（name, version, main）
- [ ] npm publish
---
计划已保存到 `.superpowers/plan.md`。
是否开始执行？
5.3 第三步：Executing Plans + TDD
人类输入：「开始执行，先写测试」
Claude Code（被 test-driven-development 技能强制）：
✅ 好的，我先写测试（TDD）。
# tests/jwt-middleware.test.js
const request = require('supertest');
const express = require('express');
const jwt = require('jsonwebtoken');
const { authMiddleware } = require('../middleware/auth');
describe('JWT 认证中间件', () => {
let app;
let validToken;
beforeEach(() => {
app = express();
app.use(express.json());
app.use(authMiddleware({ secret: 'test-secret', whitelistedPaths: ['/health'] }));
app.get('/protected', (req, res) => res.json({ user: req.user }));
app.get('/health', (req, res) => res.json({ status: 'ok' }));
validToken = jwt.sign({ userId: 123, role: 'admin' }, 'test-secret');
});
test('有效 token → req.user 正确挂载', async () => {
const response = await request(app)
.get('/protected')
.set('Authorization', `Bearer ${validToken}`);
expect(response.status).toBe(200);
expect(response.body.user.userId).toBe(123);
expect(response.body.user.role).toBe('admin');
});
test('缺少 token → 401', async () => {
const response = await request(app)
.get('/protected');
expect(response.status).toBe(401);
expect(response.body.error).toBe(true);
});
// ... 更多测试
test('白名单路径 → 跳过认证', async () => {
const response = await request(app)
.get('/health');
expect(response.status).toBe(200);
expect(response.body.status).toBe('ok');
});
});
（然后 Claude Code 才会开始写实现代码，确保测试通过）
六、Superpowers 与其他 AI 编程工具的对比
| 工具 / 方法 | 核心思路 | 优点 | 缺点 | 适用场景 |
|---|---|---|---|---|
| Superpowers | 流程纪律 + 可组合技能 | 强制工程化、防止 AI 「瞎写」、支持多工具 | 学习曲线稍陡、需要初期配置 | 生产级项目、团队协作 |
| 裸用 Claude Code | 纯提示词驱动 | 简单、灵活 | 容易写出低质量代码、缺乏约束 | 快速原型、个人脚本 |
| Cursor Tab | 实时代码补全 | 速度快、无缝集成 | 只管补全、不管架构和测试 | 日常编码辅助 |
| GitHub Copilot | 类似 Cursor | 生态好、支持多 IDE | 同上 | 日常编码辅助 |
| Aider | Git 集成的 AI 编程 | 对 Git 友好、支持多种模型 | 缺乏系统化的工程流程 | 命令行爱好者 |
| Vibe Coding（纯自然语言） | 意图驱动 | 门槛低、适合非程序员 | 依赖个人经验、容易失控 | 快速 MVP、学习编程 |
七、进阶技巧：如何定制 Superpowers 技能
Superpowers 的技能是用 Markdown 编写的，位于 .superpowers/skills/ 目录。你可以直接编辑这些文件，定制技能的行为。
7.1 定制 brainstorming 技能（加入你的团队规范）
# .superpowers/skills/brainstorming.md
（原有内容...）
## 团队定制：我们的技术规范
在我们团队，以下功能点是强制要求的：
1. **身份验证**：必须用 JWT + RS256（用 Auth0 颁发的密钥）
2. **日志**：必须用 Winston，日志级别 DEBUG / INFO / WARN / ERROR
3. **错误处理**：必须用我们封装的 `AppError` 类（不要用普通的 Error）
4. **数据库操作**：必须用 Prisma，不准写原始 SQL（防止 SQL 注入）
5. **API 响应格式**：必须统一为 `{ success: boolean, data?: any, error?: string }`
当我在 brainstorming 阶段，如果用户的方案违反了以上规范，我必须主动指出，并提供符合规范的替代方案。
7.2 创建自定义技能
假设你团队有一个特殊的流程：「每次提交代码前，必须运行安全扫描」。你可以创建一个自定义技能：
# .superpowers/skills/security-scan.md
# Skill: security-scan
## 触发时机
每次准备 commit 之前（通过 Git Hook 触发）
## 执行步骤
1. 运行 `npm audit` 检查依赖漏洞
2. 运行 `snyk test` 做深度安全扫描
3. 用 `grep -r "TODO\|FIXME\|SECRET\|PASSWORD"` 检查硬编码敏感信息
4. 如果发现问题，阻止 commit，输出报告
然后在 config.json 中注册这个技能：
{
"enabled_skills": [
"brainstorming",
"writing-plans",
"security-scan" // 新增
],
"hooks": {
"pre_commit": ["security-scan"]
}
}
八、常见问题与解决方案
Q1：Superpowers 会不会让 AI 变慢？
A：会稍微增加响应时间（因为 AI 需要先执行技能流程），但换来的是代码质量的巨大提升。而且，Superpowers 支持「技能开关」，你可以对简单任务关闭部分技能。
Q2：如果我的项目和 Superpowers 的默认流程不符怎么办？
A：Superpowers 是完全可定制的。你可以：
- 编辑
.superpowers/skills/中的技能文件 - 在
config.json中禁用不需要的技能 - 创建自定义技能，加入你们的团队规范
Q3：Superpowers 支持哪些 AI 模型？
A：Superpowers 是一个「方法论框架」，不绑定特定模型。只要你的 AI 编程工具支持插件机制（Claude Code、Cursor、Codex 都支持），就可以用 Superpowers。
Q4：如果 AI 不遵守技能流程怎么办？
A：Superpowers 通过 Hook 机制强制流程。比如：pre_encoding Hook 会确保 AI 在执行任何编码任务之前，必须先完成 brainstorming 和 writing-plans。如果 AI 试图跳过，Hook 会拦截并提示。
九、总结与展望
Superpowers 的出现，标志着 AI 辅助编程从 「Vibe Coding（氛围编程）」走向 「Agentic Engineering（智能体工程化）」。
核心收获：
- 流程大于提示词：与其花时间调 Prompt，不如给 AI 套上工程化流程
- 强制纪律：AI 需要「护栏」，防止它写出能跑但低质量的代码
- 可组合技能：不同项目、不同团队，可以按需启用 / 定制技能
- 方法论优先：Superpowers 不是「另一个 AI 工具」，而是一种新的软件开发方法论
未来展望：
- 2026 年下半年：Superpowers 计划支持「技能市场」——开发者可以分享自己的定制技能，社区投票选出最佳实践
- 与 IDE 深度集成：未来的 Claude Code / Cursor 可能会原生集成 Superpowers，不需要手动安装插件
- 多 Agent 协作：
subagent-driven-development会更加成熟，支持跨项目的 Agent 协作（比如：后端 Agent 和前端 Agent 自动协商 API 接口）
参考资源
- GitHub 仓库：https://github.com/obra/superpowers（204K Stars）
- Anthropic 插件市场：在 Claude Code 中运行
/plugin marketplace add obra/superpowers - 作者 Twitter：@obra（Jesse Vincent）
- 社区 Discord：https://discord.gg/superpowers（活跃用户 2 万+）
本文撰写于 2026 年 6 月，基于 Superpowers v5.1.0。如有更新，请参考官方 GitHub。
作者注：作为一个每天和 AI 编程工具打交道的开发者，我强烈建议你在下一个生产级项目中试试 Superpowers。它不会让你「写得更快」，但会让你「写得更好」——而这，才是 AI 辅助编程的真正价值。