技术笔记

主题

For future Claude ​

本文档是对 Superpowers 技能体系的结构化分析笔记，来源是与 mt 的对话学习。包含：核心工作流、各 skill 的契约关系、学习路径建议。适用于希望在生产项目中引入规范化 AI 编程流程的场景。

概述 ​

Superpowers 是一套为 AI 编程代理设计的开发方法论，通过多个可组合的 skill 在代码编写前/后自动触发，形成规范化的开发流程。由 Jesse Vincent (obra) 开发，遵循 MIT 协议。

官网： https://github.com/obra/superpowers

核心工作流 ​

用户需求 → brainstorming → spec文档 → writing-plans → plan文档 → 执行 → verification → 完成
阶段Skill作用
设计前brainstorming在写代码前先理解需求、探索方案、展示设计
规划writing-plans把设计拆成 2-5 分钟的小任务，每个任务含完整代码
执行subagent-driven-development每个任务派一个新 subagent 做两阶段 review
收尾verification-before-completion声称完成前必须运行验证命令，不能"我觉得OK"

Skill 契约详解 ​

brainstorming ​

  • 触发条件： 用户要创建/修改功能
  • 输入： 粗糙需求
  • 输出： docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md + 用户批准
  • 退出条件： 用户明确说"可以"了才停
  • HARD-GATE： 设计没批准绝对不能写代码

writing-plans ​

  • 触发条件： 设计被批准
  • 输入： 设计文档
  • 输出： docs/superpowers/plans/YYYY-MM-DD-<feature>.md
  • 要求： 每个任务必须包含精确文件路径、完整代码块、运行命令、预期输出
  • 禁止： "TBD"、"TODO"、"类似Task N" 等 placeholder

subagent-driven-development ​

  • 触发条件： 开始执行 plan
  • 输入： plan 文档
  • 行为： 每个任务派一个 fresh subagent，做两阶段 review（spec合规 → 代码质量）
  • 输出： 实现好的代码

verification-before-completion ​

  • 触发条件： 任何声称完成时
  • 要求： 声称"测试通过了"必须是刚运行完且输出显示 0 failures
  • 禁止： "应该没问题"、"上次跑过了"、"看起来OK"

关键设计原则 ​

1. 铁律（Iron Law） ​

每条 skill 都有不可违背的声明，如：

  • "NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE"
  • "NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST"
  • "NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST"

2. 反 Rationalization 表 ​

明确列出"别找借口"的念头：

  • "太简单不需要测试"
  • "已经花了很多时间删除浪费"
  • "应该可以了"

3. 决策优先级 ​

User instructions > Superpowers skills > Default system prompt

4. Red Flags（停止思考信号） ​

ThoughtReality
"This is just a simple question"Questions are tasks. Check for skills.
"I'll just do one thing first"Check BEFORE doing anything.
"I know what that means"Knowing the concept ≠ using the skill. Invoke it.

TDD（测试驱动开发）核心流程 ​

RED → 写失败测试 → 看 fail → GREEN → 写最小代码 → 看 pass → REFACTOR → 重复

关键规则：

  • 写代码在测试之前？删除重写
  • 不能说"先这样，之后再补测试"
  • 测试必须先 fail 证明它真的在测试正确的东西

Systemmatic Debugging（四阶段调试） ​

Phase活动成功标准
1. Root Cause读错误信息、复现、检查最近改动、收集证据理解 WHAT 和 WHY
2. Pattern找类似工作的代码、对比差异识别差异
3. Hypothesis形成理论、最小改动验证确认或新假设
4. Implementation创建失败测试、修复、验证Bug 解决、测试通过

重要规则： 3次 fix 失败后要停下来质疑架构，而不是继续尝试

学习路径建议 ​

第一阶段：理解骨架（1-2天） ​

  • 用小项目完整走一遍全流程
  • 记录每个阶段的输入和输出
  • 观察 skill 之间的交接条件
  • 验收标准： 能画出完整流程图，标注每个节点的输入/输出

第二阶段：理解每个skill的契约（3-5天） ​

  • 对照 skill 文档检查：是否完成了所有 checklist 项目
  • 特别注意 HARD-GATE：设计批准前不碰代码
  • 验收标准： 能说出自己哪个步骤做了、哪个没做

第三阶段：建立 baseline（1-2周） ​

  • 连续3个项目，每个 skill 的 checklist 100% 完成
  • 记录自己在哪一步容易"偷懒"或"跳过"

第四阶段：debug自己的执行（持续） ​

  • 每次项目完成后复盘
  • 对照 Red Flags 表检查思考

相关笔记 ​