7 min read

告别「聪明但偷懒」的实习生:superpowers 高效开发实战指南

Source: http://x.com/i/article/2019121471214530560
为什么你的 Claude Code 总是写出带 Bug 的代码? 因为你把它当成对话框,而高手把它当成「操作系统」。 剥夺 AI 随意写代码的权利,强制其遵循工程契约。拆解一套将 AI 锁死在资深工程师标准下的强制框架。

1. 项目简介与核心理念

obra/superpowers

是由 Jesse Vincent (obra) 创建的一个代理技能框架(Agentic Skills Framework)及完整的软件开发方法论。它是专为 Claude Code、Cursor、Codex 等 AI 编码代理打造的「操作系统」。

它的核心目标是将 AI 代理从一个「随心所欲写代码的聪明实习生」,转变为一个**「严格遵守工程规范、可预测的资深工程师团队」**。通过一系列可组合的、Markdown 格式的强制工作流(技能/Skills),强制 AI 遵循最佳工程实践。

核心哲学 (Philosophy)

  • TDD(测试驱动开发)永不妥协:永远先写测试,写错的代码直接删除重来。
  • 系统化优先于随意性 (Systematic over ad-hoc):遵循严谨的流程,而非依靠猜测。
  • 降低复杂度 (Complexity reduction):以简单为首要目标(YAGNI + DRY)。
  • 证据优先 (Evidence over claims):所有的修复和完成声明必须提供测试通过的实际证据。

2. 安装与环境配置 (通用技能生态与框架的区别)

最佳实践: 安装技能时,必须区分目标库是「完整的代理框架(Framework)」还是「纯技能合集(Pure Skills)」。

对于 obra/superpowers 主框架: 由于它深度依赖 hooks/session-start 来在会话启动时强制注入 using-superpowers 的检查逻辑,以及包含各种 commands/ 扩展。

必须使用插件商店模式(完整版):

/plugin marketplace add obra/superpowers-marketplace /plugin install superpowers@superpowers-marketplace

❌警告:绝对不要用 npx skills add https://github.com/obra/superpowers.git 来安装主框架。npx skills add 只会拷贝 skills/ 目录下的纯文本内容,会导致最关键的 session-start hook 丢失,从而 AI 无法在会话开始时自动触发规范!

网络要求(重要):插件采用 "strict": true 模式,每次 Claude Code 启动时都会尝试从 GitHub 重新 clone 最新版本(自动更新机制)。这意味着:

  • 必须能访问github.com:443,否则插件 commands(/brainstorm、/write-plan、/execute-plan)将全部加载失败(Total plugin commands loaded: 0)
  • session-start hook 不受影响(它直接读取本地缓存文件),所以技能(Skills)仍然正常工作
  • 在无法访问 GitHub 的网络环境下,slash commands 不可用是预期行为,重装插件也无法解决

3. 核心铁律:如何让 AI 听话

using-superpowers 是整个项目的入口技能。要想真正发挥威力,必须遵守以下使用红线:

技能检查是强制性的 (Mandatory):即使只有 1% 可能适用,也必须先调用 Skill 工具检查。

永远先调用技能,再做任何事:包括阅读文件、跑命令或澄清问题之前。

大声宣告法则:每次调用技能前,AI 会宣告:Using [skill name] to [purpose]。用户应当习惯并监督这种模式。

过程技能 > 实现技能:当多个技能冲突时,决定「怎么做」的技能(如 systematic-debugging、writing-plans)优先级永远高于决定「具体写什么代码」的技能(如 test-driven-development)。

🚫 禁止以下“红旗信号”:

❌「这只是个小改动,我直接写了。」—— 停!必须先调用 Skill。

❌「我先快速看下代码。」—— 停!严禁在 Plan 之前 Read。

❌「这个技能太繁琐,跳过吧。」—— 停!规程大于直觉。

4. 核心工作流与技能矩阵

Superpowers 将开发流程强制划分为严密的阶段(Brainstorm → Plan → Implement):

Image

5. 黄金开发流:Writing-plans + Subagent-Driven

这是官方高度推崇、效果最佳的开发路径。它极大地提升了代码质量并防止了大上下文污染,尤其适合具有一定复杂度的逻辑(如 Web3 智能合约、套利脚本、大型系统的重构)。

为什么选择这个组合?

  • 自动引入双重隔离审查(Spec 符合性审查 + 代码质量审查)。
  • 每一个任务都由「新鲜无污染」的子代理承接,避免幻觉。
  • 自动化的 git worktree 分支隔离与全流程严苛 TDD。
  • 虽然会消耗较多 Token,但节约的是无数小时的人类 Debug 时间。

实战演示(以 Web3 Uniswap V3 套利机器人为例)

1. 需求发起(Brainstorming 自动介入)

  • 用户:「帮我做一个 Uniswap V3 价格偏差检测器,当多个池子价格偏差 > 0.5% 时产生报警。」
  • AI 动作:不会写代码。它会发起苏格拉底式提问(「报警推送哪里?」、「是否全链扫描?」、「使用 viem 还是 ethers?」),最终形成一份架构文档存入 /docs/plans/,要求你批准。

2. 环境与规划(Worktrees & Writing-plans 介入)

  • AI 动作:开启新分支。分析架构文档,切分出 8-12 个微观任务。
  • Task 1 范例:创建 utils/price.ts,写入具体的测试预期,预期产出与验证。

3. 子代理执行(Subagent-Driven 介入) 你选择「在当前会话使用子代理由(Subagent-Driven)」:

  • 子代理 1 领取任务 1。
  • 强制遵循 test-driven-development:撰写失败的测试 (RED) → 跑测试失败 → 写最小业务代码做实现 → 跑测试成功 (GREEN) → 重构并 Commit。
  • Spec 审查子代理验证需求是否吻合。
  • 质量审查子代理进行 Code Review(例如建议魔法数字转为常量)。
  • 审查全部通过,自动进入下个微任务...

4. 完美收尾

  • 12 个微任务打完,系统跑全量测试,AI 询问:「所有任务完成且 100% 验证通过。选项:1. 并入 Main 2. 保留分支 3. 丢弃分支。请选择?」

6. 高级进阶技巧

把 Superpowers 当操作系统的「系统调用」:不能绕过技能去开发。哪怕是修一个 5 行代码的极小 Bug,也应该使用完整的小流程,防止隐患。

构建多 Agent 共享的本地第三方技能库 (.agents/skills/):技能管理正朝着通用化协议迈进。不要将好用的业务最佳实践闲置!只针对纯技能文档(无隐式 hook 和特殊 command 的库),可直接使用 npx skills add--skill跨 Agent 挂载能力(例如你实操安装的 obsidian-bases 纯技能包)。 对于团队日常工作的专属规范,也应该建立一个中心化的纯概念 skills git 仓库,然后下发全团队统一挂载。

像写代码一样用 TDD 开发团队规范 (writing-skills 核心奥义):写文档也是在做 TDD (Skill Creation IS TDD applied to documentation)!这是Superpowers 进阶的最深层理念。 绝不该凭空脑补写说明书。正确做法是:开个子代理 → 给它布置任务并不给它技能,记录它在哪里找借口犯错(RED 阶段) → 填写能封杀它刚刚那些借口的条款(GREEN 阶段) → 继续施加极端压力测试并打补丁(REFACTOR 阶段)。 未经失败测试(Failing test)的技能文档一律视同垃圾代码,直接删除重写。

灵活技能 vs 刚性技能:在编写技能 frontmatter 的 description 时,必须以 "Use when..." 开头。同时明确标注该技能是 Rigid(必须一字不差执行,例如 TDD)还是 Flexible(可随上下文调整,如样式微调)。绝不在description 里概括工作流,这会导致 AI 为了「抄近路」而拒绝阅读具体的技能内容。

你是否愿意为了 100% 的代码正确率,支付 3 倍的 Token 成本?

#Claude

#Cursor

#TDD

#superpowers