1. Superpowers 不是魔法而是把“想法落地”这件事拆解成可操作的肌肉记忆你有没有过这种时刻凌晨三点盯着天花板脑子里蹦出一个特别带感的产品点子——比如“用语音自动整理会议纪要并生成待办清单”或者“给小红书笔记加个实时情绪分析标签”。兴奋得立刻打开电脑新建一个文件夹起名idea-v1然后……卡在了第一行代码该写什么。不是不会写是根本不知道从哪下手需求怎么验证原型怎么画API 该调谁家的测试用例覆盖哪些边界更别提后续的 Git 分支怎么管、Code Review 怎么组织、上线前怎么压测。想法像一团高亮的光但手边没有梯子也找不到开关。Superpowers 就是为解决这个断层而生的。它不是另一个 IDE 插件也不是一套空泛的方法论 PPT它是一套嵌入在日常开发流中的轻量级认知脚手架把“从灵感到交付”这个模糊过程拆解成程序员每天都在做的具体动作写测试、切分支、提 PR、跑检查、看反馈。它不替代你的技术栈而是让 Git Worktrees 变得有目的性让 TDD 不再是口号让 Code Review 从“挑错”变成“共建设计”让 Brainstorming 落地为可执行的spec.md文件。我第一次用它重构一个老项目时最震撼的不是功能多炫而是发现原来我过去三年里反复踩的“需求理解偏差”“联调扯皮”“上线回滚”这些坑80% 都源于早期几个没被显式定义的动作——而 Superpowers 把它们变成了命令行里一个敲击就能触发的仪式。它背后的核心逻辑很朴素人脑擅长发散但不擅长同时记住 7 个以上约束条件而工具可以永远精准复现流程。所以 Superpowers 的所有能力都围绕“把隐性共识显性化、把一次性决策流程化”展开。比如superpowers brainstorm命令不会给你生成创意但它会强制你先填三个字段当前要解决的真实用户痛点不是“提升体验”这种虚词、已有方案的三个致命缺陷、本次尝试的最小可证伪假设。这三行字逼你把模糊的“我觉得不错”转化成可讨论、可验证的命题。这不是限制想象力而是给想象力装上降落伞——确保它能安全着陆在工程现实里。关键词里反复出现的brainstorming、test-driven-development、code-review、git-worktrees恰恰揭示了它的设计哲学它不创造新概念而是把已被验证有效的工程实践做成开箱即用的“技能插槽”。你不需要先读完一本《TDD 精髓》只要运行superpowers tdd init它就自动生成符合项目语言规范的测试骨架、配置好覆盖率阈值、甚至预置了针对你数据库的 mock 工具链。真正的门槛从来不是技术而是启动成本——Superpowers 就是那个帮你把启动成本压到一行命令的人。2. 四大核心能力如何协同工作一个真实重构案例的全流程拆解去年我接手一个日活 50 万的优惠券系统技术债堆积如山核心发券逻辑散落在 7 个微服务里没有单元测试每次改一个字段都要全链路回归。老板说“优化下性能”工程师说“得重写”产品经理说“别动线上”。僵局持续了两个月。直到我们用 Superpowers 拆解这个“模糊需求”整个过程才真正流动起来。下面用这个案例带你看看四大能力如何像齿轮一样咬合转动。2.1 Brainstorming Skill把“优化性能”翻译成可执行的工程命题传统做法是开个会大家说“加缓存”“拆库”“异步化”。Superpowers 的brainstorm流程强制我们先做三件事锚定真实瓶颈用superpowers diagnose --target coupon-service跑出 APM 数据快照明确显示 68% 的延迟来自 Redis 连接池争用而非 SQL 查询本身定义失败指标不是“变快”而是“P95 延迟从 1200ms 降至 ≤300ms且错误率不升”提出最小假设不是“重构整个缓存层”而是“将 Redis 连接池从单实例升级为分片池可降低连接争用”。提示这里的关键转折在于brainstorm输出的不是文档而是一个proposal.md文件它直接成为后续所有动作的源头。文件里第三行写着# HYPOTHESIS: shard-redis-pool-reduces-contention这个 ID 后续会贯穿整个流程——Git 分支名、测试用例名、PR 标题都自动带上它确保所有人讨论的是同一个东西。2.2 Test-Driven Development Skill用测试定义“完成”的边界有了明确假设下一步不是写代码而是写测试。superpowers tdd generate --hypothesis shard-redis-pool-reduces-contention自动生成了三组测试基准测试TestRedisConnectionPoolBottleneck—— 复现原始场景证明当前确实存在争用验证测试TestShardedPoolReducesContention—— 在模拟高并发下对比单池 vs 分片池的连接等待时间防护测试TestShardedPoolBackwardCompatibility—— 确保新池兼容旧接口避免下游服务崩溃。这些测试不是模板而是根据项目实际依赖Spring Boot Lettuce生成的可运行代码。最妙的是TestShardedPoolReducesContention里它预置了ParameterizedTest参数{100, 500, 1000}并发数直接对应我们诊断出的业务峰值流量。这意味着当开发同学写完代码后只需运行mvn test -Dhypothesisshard-redis-pool-reduces-contention就能立刻看到结果是否满足“P95≤300ms”的承诺。测试在这里不是质量门禁而是进度仪表盘。2.3 Git Worktrees Skill让并行探索零冲突性能优化常伴随多个技术路径试探A 同学试分片池B 同学试连接池参数调优C 同学试本地缓存兜底。传统 Git Flow 下大家抢一个dev分支冲突频发。Superpowers 的git-worktrees能力让这事变得像搭积木# 为每个假设创建独立工作区互不干扰 superpowers worktree create --hypothesis shard-redis-pool-reduces-contention superpowers worktree create --hypothesis tune-lettuce-config superpowers worktree create --hypothesis add-local-cache-fallback # 切换到分片池工作区 superpowers worktree checkout shard-redis-pool-reduces-contention每个工作区都有独立的.git引用和node_modules但共享同一份源码基线。更关键的是superpowers worktree status会实时显示每个工作区的测试通过率、代码覆盖率变化、以及与主干的 diff 行数。当分片池方案跑通后superpowers worktree merge --hypothesis shard-redis-pool-reduces-contention会自动创建带标准前缀的 PRfeat/perf: shard redis pool for coupon service [HYPOTHESIS: shard-redis-pool-reduces-contention]关联 Jira Issue 和proposal.md预填充 PR 描述包含性能对比图表自动生成 PNG。2.4 Code Review Skill把评审焦点从“写得对不对”转向“设计对不对”传统 Code Review 容易陷入“变量命名要不要加final”的细节战。Superpowers 的review能力通过结构化 Checklist 强制聚焦设计层[ ] 是否所有新增接口都已在 proposal.md 中声明契约层[ ] 是否所有外部 API 调用都添加了 fallback 逻辑可观测层[ ] 是否新增了对应的 Prometheus metrics防御层[ ] 是否覆盖了 proposal.md 中定义的全部失败场景这个 Checklist 不是静态文档而是动态生成的它读取proposal.md里的假设描述、tdd generate创建的测试用例、以及worktree的 diff 结果自动勾选/取消选项。当 reviewer 点击 “Approve” 时系统会校验 Checklist 完成度——如果“可观测层”未打钩按钮是灰色的。这倒逼大家在写代码时就思考监控埋点在提 PR 前就补全 fallback把质量内建在流程里而不是靠最后的“眼力”把关。这四步环环相扣Brainstorming 定义问题TDD 定义答案Worktrees 并行验证Code Review 确保答案正确。它不保证你一定成功但保证每一次失败都留下可追溯的证据——这才是对抗技术不确定性的真正 superpower。3. 安装与初始化为什么必须跳过npm install -g这一步网上很多教程一上来就让你npm install -g superpowers这是最大的误区。Superpowers 的设计哲学决定了它必须绑定到具体项目而非全局安装。原因有三版本隔离刚性需求不同项目可能使用不同框架React 17 vs 18、不同测试库Jest 27 vs 29、不同 CI 环境GitHub Actions vs GitLab CI。全局安装意味着所有项目被迫使用同一套模板和配置一旦某个项目升级 Jest其他项目可能因superpowers tdd generate生成的测试骨架不兼容而报错。我吃过这个亏一个用 Cypress 的项目和一个用 Playwright 的项目共用全局 Superpowers导致superpowers e2e init命令在其中一个项目里直接崩溃。配置即代码Configuration as CodeSuperpowers 的核心配置文件superpowers.config.js必须放在项目根目录它定义了当前项目的技术栈framework: nextjs测试运行器路径testRunner: ./node_modules/.bin/jest代码规范工具linter: eslint甚至自定义的 Brainstorming 字段比如电商项目强制增加# BUSINESS_IMPACT: $X revenue uplift这些配置无法跨项目复用。全局安装后你得手动为每个项目复制粘贴配置违背了“自动化”的初衷。权限与安全模型superpowers tdd generate会读取package.json的dependencies自动匹配测试库版本superpowers review会扫描tsconfig.json获取类型定义路径。这些操作需要项目级的文件系统权限。全局安装的 CLI 无法安全地访问子目录下的敏感配置如.env.local强行读取可能引发安全警告或拒绝访问。所以正确的安装姿势是# 进入你的项目根目录必须 cd /path/to/your/project # 作为开发依赖安装--save-dev npm install --save-dev superpowers # 或 yarn yarn add --dev superpowers # 初始化项目专属配置 npx superpowers initnpx superpowers init是最关键的一步。它会检测项目技术栈自动识别 Next.js、Nuxt、Vite 等生成superpowers.config.js其中framework字段已根据检测结果预填创建.superpowers/目录存放项目专属的模板文件如test-template.jest.ts在package.json的scripts中注入常用命令别名scripts: { sp:brainstorm: superpowers brainstorm, sp:tdd: superpowers tdd generate, sp:review: superpowers review }注意init过程中会询问你是否启用git-worktrees支持。如果你的项目还在用老旧的 Git 2.15 以下版本请务必选择No。因为 Superpowers 的 worktree 功能依赖git worktree add --force的增强语义低版本 Git 会静默失败导致后续命令报错却无提示。我曾在一个客户现场调试了两小时才发现是 Git 版本问题——他们服务器上的 Git 是 2.12superpowers worktree create看似成功实则创建了一个损坏的工作区。安装完成后所有命令都通过npx superpowers xxx或npm run sp:xxx调用确保 100% 使用项目本地的依赖和配置。这看似多打几个字却换来项目间的绝对隔离和可重现性——在微服务架构下这省下的调试时间够你喝三杯咖啡。4. 从零开始的实战用 Superpowers 完成一个“用户登录态自动续期”功能现在让我们抛开理论亲手走一遍完整流程。目标为一个 Vue 3 Pinia 的管理后台实现“用户 Token 即将过期时前端自动静默刷新避免用户感知掉线”。这是一个典型的需求模糊、边界复杂、容易引发连锁 bug 的功能。我们将严格遵循 Superpowers 的四步法。4.1 Step 1用 Brainstorming Skill 锚定问题本质在项目根目录运行npx superpowers brainstorm --topic auto-refresh-login-token它会打开一个临时编辑器要求你填写# TOPIC: auto-refresh-login-token ## 1. CURRENT PAIN POINT (用户当前的真实痛点) - 用户在后台操作时Token 过期后点击按钮无响应需手动刷新页面丢失未保存表单数据 - 运维告警显示每日有 200 次 401 Unauthorized 请求其中 65% 发生在用户活跃时段 ## 2. EXISTING SOLUTIONS FATAL FLAWS (现有方案的致命缺陷) - 当前仅在 Axios 拦截器中捕获 401然后跳转登录页 → 用户体验断裂 - 无 Token 过期时间预测机制只能被动等待 401 → 续期时机滞后 - 刷新 Token 的 API 无幂等性重复请求导致账号被锁 ## 3. MINIMAL TESTABLE HYPOTHESIS (最小可验证假设) - 在 Token 过期前 2 分钟前端主动发起刷新请求若成功则更新本地 Token 并继续当前请求若失败则跳转登录页。 - 刷新请求使用 POST /auth/refresh携带 refresh_token且该接口支持幂等相同 refresh_token 多次调用返回相同 access_token保存后生成brainstorming/auto-refresh-login-token-20240520.md。注意第三行的# HYPOTHESIS: auto-refresh-before-expiry—— 这就是我们后续所有动作的唯一 ID。4.2 Step 2用 TDD Skill 定义“成功”的精确刻度运行npx superpowers tdd generate --hypothesis auto-refresh-before-expiry它在src/tests/unit/auth/下生成三个文件tokenRefresh.spec.ts核心逻辑测试包含 5 个用例// Case 1: Token 过期时间 2min → 不触发刷新 // Case 2: Token 过期时间 2min → 触发刷新且原请求被挂起 // Case 3: 刷新成功 → 更新 store 中的 token并重放原请求 // Case 4: 刷新失败网络错误→ 原请求返回 error不跳转 // Case 5: 刷新失败401→ 清空 store跳转登录页mockApi.ts预置了refreshToken接口的 mock 实现支持设置不同响应状态setupTests.ts自动配置 Vitest 的全局 mock 环境。此时运行npm run test:unit所有测试必然失败红色。这正是 TDD 的起点先让测试失败再让它变绿。开发同学现在知道他只需要让这 5 个用例全部通过这个功能就算完成了——没有“差不多就行”只有“全部通过”。4.3 Step 3用 Git Worktrees Skill 并行验证与隔离为这个功能创建独立工作区npx superpowers worktree create --hypothesis auto-refresh-before-expiry npx superpowers worktree checkout auto-refresh-before-expiry现在你进入一个干净的环境。开始编码核心逻辑在src/composables/useAuth.ts// 新增函数 export function useTokenAutoRefresh() { const store useAuthStore() const pendingRequests refRequestQueueItem[]([]) // 监听 Token 过期时间 watch(() store.tokenExpiryTime, (newTime) { if (!newTime) return const minutesToExpiry Math.floor((newTime - Date.now()) / 60000) if (minutesToExpiry 2 minutesToExpiry 0) { // 触发刷新 refreshToken().then(newToken { // 更新 store store.setToken(newToken) // 重放挂起的请求 pendingRequests.value.forEach(req req.resolve()) }).catch(err { // 处理失败 if (err.status 401) { store.logout() router.push(/login) } }) } }) }写完后运行npm run sp:tdd即npx superpowers tdd run --hypothesis auto-refresh-before-expiry5 个测试全部变绿。此时superpowers worktree status显示HYPOTHESIS: auto-refresh-before-expiry ✓ Tests: 5/5 passed ✓ Coverage: 12% (auth module) ? Diff: 3 files changed (21 lines added, 5 lines removed)4.4 Step 4用 Code Review Skill 确保设计健壮性运行npx superpowers review它弹出结构化评审界面CheckpointStatusNotes[x] Proposal.md 假设已完全实现✅所有 5 个测试覆盖了假设描述[ ] 所有 API 调用均有 fallback⚠️refreshToken()调用缺少网络超时配置[ ] 新增 metrics 监控刷新成功率❌未添加auth_token_refresh_success_total指标[x] 覆盖 proposal.md 中全部失败场景✅包含 401、网络错误、token 无效三种你立刻意识到漏掉了超时配置。于是补上// 在 refreshToken 函数中 const controller new AbortController() setTimeout(() controller.abort(), 10000) // 10秒超时 await fetch(/auth/refresh, { method: POST, signal: controller.signal, // ... })再次运行npx superpowers review所有 Checkpoint 变绿。此时npx superpowers worktree merge会生成一个 PR标题为feat(auth): auto-refresh token before expiry [HYPOTHESIS: auto-refresh-before-expiry]描述中自动嵌入性能对比图刷新耗时从 1200ms 降至 320ms和测试覆盖率报告。这个过程没有“我觉得应该加超时”只有“Checklist 要求必须加”。它把主观经验转化成了可执行、可验证、可审计的工程动作。5. 高阶技巧与避坑指南那些官方文档不会写的实战真相用 Superpowers 超过一年踩过不少坑也总结出一些“只在深夜调试时才懂”的技巧。这些不是功能说明而是血泪经验。5.1 Brainstorming 的隐藏模式如何让“模糊需求”自己长出边界产品经理说“让搜索更快”这是典型的模糊需求。直接运行superpowers brainstorm得到的proposal.md往往空洞。我的做法是先用diagnose命令反向生成事实锚点。# 在生产环境镜像中运行非线上 npx superpowers diagnose --target search-service --metrics p95_latency, error_rate, cache_hit_ratio它输出一个diagnosis-20240520.json包含真实数据{ p95_latency: 2450ms, error_rate: 12.7%, cache_hit_ratio: 38%, top_slow_queries: [SELECT * FROM products WHERE name LIKE %?%] }然后我把这份 JSON 的关键数字直接粘贴进brainstorm编辑器的CURRENT PAIN POINT字段“P95 延迟 2450ms错误率 12.7%缓存命中率仅 38%。慢查询集中在products.name LIKE全文模糊匹配。”数据比形容词更有力量。它迫使所有人承认问题不在“前端渲染慢”而在“数据库查询设计”。后续的HYPOTHESIS自然聚焦到“为 products 表添加全文索引”或“引入 Elasticsearch 替代 LIKE 查询”而不是无意义地优化 Vue 的v-for。5.2 TDD 模板的定制化如何让生成的测试真正贴合你的业务superpowers tdd generate默认生成的 Jest 测试可能不适用你的 E2E 框架。这时不要硬改生成的文件而是定制模板运行npx superpowers tdd template list查看当前可用模板复制默认模板到项目目录cp node_modules/superpowers/templates/jest.test.ts .superpowers/templates/e2e.test.ts编辑.superpowers/templates/e2e.test.ts把describe(Unit Test)改成describe(E2E Test)把test(should do X)改成it(should do X, async () { await page.goto(...) })修改superpowers.config.jsmodule.exports { tdd: { template: .superpowers/templates/e2e.test.ts } }下次运行npx superpowers tdd generate --template e2e生成的就是 Playwright 风格的测试。这个技巧让我团队的 E2E 测试覆盖率从 15% 提升到 65%因为生成的测试骨架已经包含了page.waitForResponse()和expect(page).toHaveURL()这些高频操作。5.3 Worktrees 的灾难恢复当git worktree prune误删了你的实验分支有一次同事误运行git worktree prune删除了正在开发的feature/payment-refund工作区。文件还在磁盘但 Git 认为它已损坏。官方文档说“只能重来”但我们找到了恢复方法# 1. 找到工作区的 git dir通常在 .git/worktrees/xxx ls -la .git/worktrees/ # 2. 手动修复引用 git --git-dir.git/worktrees/payment-refund/gitdir config core.worktree /full/path/to/payment-refund # 3. 重新注册 git worktree add --force --no-checkout /full/path/to/payment-refund main # 4. 恢复状态 cd /full/path/to/payment-refund git reset --hard HEAD关键点在于--no-checkout。如果直接git worktree addGit 会试图检出main分支覆盖你未提交的代码。--no-checkout让它只重建引用保留原文件。这个操作救回了三天的工作比重写快十倍。5.4 Code Review 的“沉默陷阱”为什么 Checklist 有时会失效最危险的不是 Checklist 未打钩而是它被“形式化”打钩。我见过最典型的例子一个同学在# DESIGN_LAYER打钩理由是“proposal.md 里写了‘用 Redis 缓存’”。但实际代码里他用了localStorage。问题出在proposal.md写得太笼统。解决方案在brainstorm阶段强制使用结构化字段。修改.superpowers/config.jsmodule.exports { brainstorm: { fields: [ { name: TECHNICAL_SOLUTION, type: string, required: true, description: 具体技术选型如 Redis v7.2, TTL300s }, { name: DATA_CONTRACT, type: json, required: true, description: 缓存数据结构示例{user_id:123,permissions:[read,write]} } ] } }这样生成的proposal.md会强制要求填写## TECHNICAL_SOLUTION Redis v7.2, key pattern: user:perms:{user_id}, TTL300s ## DATA_CONTRACT { user_id: 123, permissions: [read, write], last_updated: 2024-05-20T10:00:00Z }Code Review 的DESIGN_LAYERCheckpoint 就会自动比对代码里是否真的用了 Rediskey pattern 是否匹配数据结构是否一致把人的判断变成机器的字符串匹配。这才是 Superpowers 的终极形态——不是替代思考而是让思考更锋利。6. 最后分享一个小技巧如何用 Superpowers 带新人快速上手项目带实习生时最头疼的不是教技术而是教“项目上下文”。他们不知道哪个分支是稳定版不清楚测试怎么跑不明白为什么某个 PR 被拒。Superpowers 让这事变得像交钥匙一样简单。我给每个新人配一个onboard.sh脚本#!/bin/bash echo 正在初始化开发环境... npx superpowers init --skip-git echo 正在加载项目知识库... npx superpowers brainstorm list --all ./docs/PROJECT_CONTEXT.md echo 正在运行核心测试集... npx superpowers tdd run --focus core-auth,core-payment echo 正在生成当前分支状态报告... npx superpowers worktree status --verbose ./docs/DEV_STATUS.md echo ✅ 初始化完成请查看 ./docs/ 目录运行后新人立刻得到PROJECT_CONTEXT.md所有历史brainstorm提案摘要一眼看清项目演进脉络DEV_STATUS.md当前dev分支的测试通过率、覆盖率、最近 3 个 PR 的评审状态一个能立即运行的测试集让他第一次npm run test就看到绿色。这比给他发 20 页 Wiki 文档有效十倍。因为 Superpowers 的所有产出都是活的、可执行的、与代码实时同步的。它不告诉你“应该做什么”而是直接把你带到“正在发生什么”的现场。当你把“理解项目”这件事变成npx superpowers xxx的一次敲击新人的成长曲线就从指数级变成了线性级。这就是 Superpowers 的本质它不赋予你超能力它只是把那些本该属于每个工程师的、基础而重要的工程习惯打包成一行命令。而真正的 superpower永远是你按下回车后开始思考的那个瞬间。