项目学习洞察：Superpowers

日期： 2026-03-13 基于： 完整阅读所有 Skill 文件、文档、测试、脚本及 Release Notes

项目概览

定位： Superpowers 是一套专为 AI 编程助手设计的完整软件开发工作流框架，支持 Claude Code、Cursor、Gemini CLI、Codex、OpenCode 等平台。通过可组合的 Skill（技能），强制 Agent 先思考、先设计、再实现，防止 AI 在未理解需求的情况下直接写代码。

主要模块：

Skill	职责	类型
using-superpowers	入口守卫，每次消息都检查是否有适用 Skill	Rigid
brainstorming	想法 → 规格文档，HARD-GATE 阻止未审批就写代码	Rigid
writing-plans	规格 → 零上下文可执行的实现计划	Rigid
subagent-driven-development	每个 Task 顺序派发独立子 Agent + 两阶段审查	Rigid
executing-plans	无子 Agent 时的降级执行路径	Rigid
test-driven-development	Iron Law：先写失败测试，再写实现	Rigid
systematic-debugging	4 阶段调试：根因调查→模式分析→假设→修复	Rigid
verification-before-completion	完成前必须运行验证命令，证据先于声明	Rigid
dispatching-parallel-agents	独立问题域并行派发多 Agent	Flexible
requesting-code-review	审查请求的标准化模板和工作流	Flexible
receiving-code-review	技术评估而非情感表演	Rigid
finishing-a-development-branch	4 选项结构化完成 + worktree 清理	Rigid
using-git-worktrees	隔离工作区的系统化创建与验证	Rigid
writing-skills	Skill 编写规范、说服力原则、测试方法	Flexible

技术栈： 纯 Markdown + YAML frontmatter（Skill 定义）、Graphviz DOT（控制流可视化）、JSON + Polyglot CMD 脚本（跨平台 Hook）、Node.js 零依赖 HTTP+WebSocket（可视化协作服务器）。

核心设计思想

1. 完整流水线：控制流的精确定义

每个阶段都有明确的入口条件、执行内容和出口条件，不允许跳步：

想法
  → brainstorming
      → 探索项目上下文（理解现状）
      → [可选] 询问是否启动可视化伴侣（独立消息，不合并其他内容）
      → 逐一澄清问题（每次严格一个问题）
      → 提出 2-3 种方案 + 权衡 + 推荐
      → 分节展示设计，逐节获得审批          ← 用户关卡 #1
      → 写规格文档（docs/superpowers/specs/），git commit
      → Spec Reviewer 子 Agent 循环         ← AI 关卡（最多 5 轮）
      → 用户审阅规格文档                    ← 用户关卡 #2
      ↓（只能转到 writing-plans，禁止任何其他 Skill）
  → writing-plans
      → 映射文件结构（在分解任务前先定义文件职责）
      → 按 chunk 写计划（每块 ≤1000 行）
      → Plan Reviewer 子 Agent（每块完成后）  ← AI 关卡
      → 计划 header 嵌入执行路径指令
      ↓（如有子 Agent 能力，必须用 subagent-driven-development）
  → using-git-worktrees（REQUIRED，在任何实现前）
  → subagent-driven-development
      → 读计划，提取所有 Task 全文，创建 TodoWrite
      → 每个 Task（顺序，禁止并行）：
          ① 派发实现子 Agent（全文直接提供，不让它读文件）
          ② 子 Agent 可在开始前提问（必须回答后再实现）
          ③ 实现 + 自审 + commit
          ④ Spec Compliance Reviewer 子 Agent
             └─ 失败 → 实现子 Agent 修复 → 再审查（循环）
          ⑤ Code Quality Reviewer 子 Agent
             └─ 失败 → 实现子 Agent 修复 → 再审查（循环）
             └─ 注意：质量审查必须在合规审查通过后才能开始
          ⑥ 标记 Task complete
      → 所有 Task 完成 → 最终 code-reviewer（整体审查）
  → finishing-a-development-branch
      → 验证测试通过（失败则停止，不提供选项）
      → 给出精确 4 个选项（合并/PR/保留/丢弃）
      → 选项 4 要求用户手打 "discard" 确认
      → Worktree 清理：选项 1/4 清理，选项 2/3 保留

重要验证事实：

brainstorming 结束后只能调用 writing-plans，连 frontend-design 都被明确禁止
实现子 Agent 是顺序执行，Red Flags 明确禁止并行（"conflicts"）
质量审查必须在合规审查通过后才开始（顺序强制）
计划 header 里直接写明 "REQUIRED: Use superpowers:subagent-driven-development"，是元指令而非建议

2. 文档是上下文切断器，不是归档工具

writing-plans 的受众假设极端清晰：

"Assume the engineer has zero context for our codebase and questionable taste."

计划文档必须包含：精确文件路径、完整代码片段、具体命令、预期输出。

子 Agent 不会"去读计划文件"——控制器把 Task 全文直接粘贴给它（implementer-prompt.md 明确："paste it here, don't make subagent read file"）。好处：

子 Agent 无需读文件（节省 token 和时间）
控制器精确控制子 Agent 看到什么（上下文隔离）
子 Agent 不会被无关历史干扰

3. 双轨验证：顺序固定，不可反转

规格文档的审查顺序：

AI 审查（Spec Reviewer）——检查完整性、TODO、YAGNI、内部一致性
用户审查——检查是否符合真实意图

原因：AI 审查清除技术噪音，用户才能专注判断意图。相同结构在三个层面重复：规格（Spec Reviewer）→ 计划（Plan Reviewer）→ 实现（合规审查在质量审查之前）。

4. Skill 的两种类型：Rigid vs Flexible

using-superpowers 明确定义：

Rigid（TDD、debugging）：字面遵守即精神遵守，不允许"适配"
Flexible（patterns）：适应上下文

这个区分很重要：Rigid Skill 里的 Anti-Rationalization 表和 Iron Law，是针对"我理解了精神，不需要遵循字面"这类逃脱路径的直接反驳。

5. HARD-GATE 的设计原理

不用"应该先设计"，而用 <HARD-GATE> XML 标签 + 在同一文档里预先反驳最常见借口：

"Anti-Pattern: 'This Is Too Simple To Need A Design'" "Every project goes through this process. A todo list, a single-function utility..."

这是结构性拦截，而非建议性引导。区别在于：建议可以被合理化绕过，结构性拦截提前关闭了所有出口。

6. 说服力工程：让 AI 遵守规则的底层原理

基于 Meincke et al. (2025)，N=28,000 次 LLM 对话，合规率从 33% 提升到 72%（p<.001）。Superpowers 有意识地应用了其中 5 个原则：

原则	在项目中的体现	效果
Authority（权威）	"YOU MUST"、"No exceptions"、"Iron Law"、`<EXTREMELY-IMPORTANT>`	消除决策余地
Commitment（承诺）	要求宣布 "I'm using [Skill]"、TodoWrite 跟踪 checklist	公开声明 → 必须兑现
Scarcity（稀缺）	"Before proceeding"、"IMMEDIATELY after X"	防止"稍后再做"
Social Proof（社会证明）	"Every time"、"Checklists without TodoWrite = steps get skipped. Every time."	建立规范感
Unity（归属）	"our codebase"、"we're colleagues"	降低对抗性

明确禁止使用 Liking（讨好）原则——"Conflicts with honest feedback culture. Creates sycophancy."

实现意图（Implementation Intentions）比一般性建议有效得多：

✅ "When you find a skill, you MUST announce: 'I'm using [Skill Name]'"
❌ "Consider letting your partner know which skill you're using"

"When X, do Y" 将合规行为变成条件反射，减少"是否需要这样做？"的认知负担。LLM 从包含这些模式的人类文本训练而来，权威语言之后往往跟着服从行为。

7. 抗合理化设计：关闭所有逃脱路径

每个 Rigid Skill 都有三层防御：

① 预测并命名常见借口（以 TDD 为例）：

借口	反驳
"Tests after achieve the same goals"	Tests-after = "What does this do?" Tests-first = "What should this do?"
"Deleting X hours is wasteful"	Sunk cost fallacy. Keeping unverified code is technical debt.
"Keep as reference, write tests first"	You'll adapt it. That's testing after. Delete means delete.
"TDD is dogmatic, I'm being pragmatic"	TDD IS pragmatic: finds bugs before commit, prevents regressions.
"I already manually tested it"	Ad-hoc ≠ systematic. No record, can't re-run.

② Red Flags：看到就停止的触发器

13 条具体的停止条件，每条对应一个真实逃脱路径
不是"注意这些"，而是"看到这些 → 删除代码 → 重新开始"

③ 铁律（Iron Law）：绝对禁止的最后防线

"Write code before test? Delete it. Start over. No exceptions."
"Delete means delete"——专门针对"我保留一份参考，然后再写测试"这个变种逃脱路径

Skill TDD的发现（testing-skills-with-subagents.md 记录了实际案例）：

TDD Skill 本身经历了 6 次 RED-GREEN-REFACTOR 才达到"bulletproof"
基线测试发现了 10+ 个独特的合理化借口
从"Write code before test? Delete it." 到 "Delete means delete. Don't keep as reference." 是两次迭代的结果

8. 不信任实施者报告原则

spec-reviewer-prompt.md：

"The implementer finished suspiciously quickly. Their report may be incomplete, inaccurate, or optimistic. You MUST verify everything independently."

verification-before-completion 的 Common Failures 表：

"Agent completed → VCS diff shows changes ← NOT: Agent reports success"

这是系统性地对抗 AI 的乐观偏差，把 AI 对 AI 的验证设计为对抗性关系。

verification-before-completion 的"失败记忆"来源真实：

"From 24 failure memories: your human partner said 'I don't believe you' - trust broken; Undefined functions shipped - would crash"

规则不是理论推导的，而是从实际事故中提炼的。

9. 系统性调试：4 阶段 + 架构升级触发器

Phase 1: Root Cause Investigation

在多组件系统中：先加诊断日志在每个组件边界，运行一次收集证据，再分析哪层出错
在深层调用栈：向上追溯直到找到坏值来源（root-cause-tracing.md 的完整流程）

Phase 2: Pattern Analysis

找到可用的类似实现，完整阅读（"Read every line, don't skim"）

Phase 3: Hypothesis & Testing

每次只改一个变量
"If you don't fully understand, say 'I don't understand X'"（不允许不确定地猜测）

Phase 4: Implementation

先写失败测试（调用 TDD Skill）
3 次修复失败 → 停止，质疑架构，不允许第 4 次修复尝试

人工伙伴的信号词（说明你在错误轨道上）：

"Is that not happening?" → 你在假设而非验证
"Stop guessing" → 你在没理解前提出修复
"Ultrathink this" → 质疑根本，而非症状

实际数据（来自调试会话）： 系统性方法 15-30 分钟，随机修复 2-3 小时，首次成功率 95% vs 40%。

10. 模型成本分级：内置在工作流中

subagent-driven-development 显式定义：

便宜模型：1-2 个文件，规格完整，机械实现
标准模型：多文件协调，集成问题，模式匹配
最强模型：架构判断，设计决策，审查任务

这不是建议，是必须执行的成本优化——大量子 Agent 调用，每次都用最强模型会产生显著成本差距。

11. Graphviz 作为流程文档的 DSL

项目为 Skill 里的流程图制定了完整的视觉语法（graphviz-conventions.dot，这个风格指南本身就用 DOT 写成）：

节点类型	形状	含义
决策	diamond（菱形）	是/否或多选
动作	box（矩形）	执行的步骤
命令	plaintext	字面命令（如 `npm test`）
状态	ellipse（椭圆）	当前情况描述
警告/禁止	octagon，红色填充，白色字	STOP / NEVER
入口/出口	doublecircle（双圆）	流程起点和终点

这是一个精确的视觉信息分层：决策（需要判断）vs 动作（执行）vs 命令（抄写）vs 禁止（绝对规则）在图上一眼可辨。

12. 并行 Agent 的独立域分解

dispatching-parallel-agents 的核心判断：

多个失败——是否彼此独立（修复一个不影响另一个）？
能否不共享状态并行工作（没有同时编辑同一文件）？
还是需要全局理解才能看懂问题？

何时不用并行：

探索性调试（还不知道什么坏了）
相关故障（一个修复可能影响另一个）
共享状态（Agent 会互相干扰）

实际案例：6 次失败分布在 3 个文件，3 个并行 Agent 分别处理，全部独立解决，整合时零冲突。

13. Skill Description 是最关键的 1024 个字符

Skill 启动时只有 metadata（name + description）被加载，正文按需加载。description 是触发 Skill 的唯一依据，在 100+ 个 Skill 中进行选择。

硬规则（来自 anthropic-best-practices.md）：

必须用第三人称（"Processes Excel files"，不是 "I can help you" 或 "You can use this"）
必须同时包含：做什么 + 何时用（触发条件）
推荐动名词形式：brainstorming、writing-plans（清楚描述活动）
避免：Helper、Utils、Tools 这类模糊命名

14. 自由度设计谱（Degrees of Freedom）

同一个 Anthropic 文档里的"窄桥"比喻：

窄桥（低自由度）：数据库迁移——只有一条安全路径，给精确指令
开阔地（高自由度）：代码审查——多种路径都有效，给方向即可

三级：

高自由度：文字描述（多路径均可）
中自由度：伪代码模板（有优选模式但允许变化）
低自由度：精确脚本（操作脆弱、必须严格执行）

跨模型的挑战： 对 Opus 正好合适的 Skill 可能对 Haiku 太少细节；如果要跨模型使用，要找到兼容所有模型的指令详细程度。

15. Polyglot 脚本：Windows + Unix 双平台共存

run-hook.cmd 同时对 CMD.exe 和 bash 合法：

cmd

: << 'CMDBLOCK'
@echo off
"C:\Program Files\Git\bin\bash.exe" -l -c "cd \"$(cygpath -u \"%SCRIPT_DIR%\")\" && \"./%SCRIPT_NAME%\""
exit /b
CMDBLOCK

# Unix shell runs from here
"${SCRIPT_DIR}/${SCRIPT_NAME}" "$@"

工作原理：

CMD.exe：: 是 label，<< 'CMDBLOCK' 被忽略；执行 @echo off 和 bash 调用；exit /b 停止
bash：: << 'CMDBLOCK' 是 heredoc，把 CMD 块吃掉；之后才真正执行

跨平台注意事项：

路径必须用双引号（${CLAUDE_PLUGIN_ROOT} 在 Windows 可能含空格）
使用 cygpath -u 将 Windows 路径转为 Unix 格式
使用 bash -l（login shell）确保 PATH 包含 Unix 工具
避免 sed/awk 等外部命令——用纯 bash 内置实现 JSON 转义

16. Skill TDD：对流程文档的测试

RED-GREEN-REFACTOR 精确映射：

TDD 阶段	Skill 测试	做什么
RED	Baseline	不用 Skill，记录 Agent 的失控和借口（verbatim）
Verify RED	捕获合理化	把每个借口逐字写下来
GREEN	写 Skill	针对具体的失控点写规则
Verify GREEN	压力测试	用 Skill，在压力场景下验证合规
REFACTOR	堵漏洞	找新借口，加针对性反驳
Stay GREEN	再验证	确保 REFACTOR 后仍然合规

压力场景的设计原则：

必须组合 3+ 种压力（时间 + 沉没成本 + 疲惫 = 更难抵抗）
强制 A/B/C 选择（防止"我会问 human partner"的逃脱）
用"IMPORTANT: This is a real scenario. Choose and act."防止 Agent 当作学术练习

元测试（Meta-testing）技巧： Agent 违规后，问："这个 Skill 怎么写才能让你清楚 A 是唯一答案？"

回答"Skill 已经很清晰，我选择忽略" → 需要更强的基础原则
回答"Skill 应该说 X" → 加那句话
回答"我没看到 Y 部分" → 改变组织结构，让关键点更显眼

17. 触发率量化测试

tests/skill-triggering/ 的完整测试链路：

向 Claude 发自然语言 prompt（不提 Skill 名）
用 claude -p --plugin-dir --dangerously-skip-permissions --output-format stream-json 运行真实 Session
解析 stream-json，检查 "name":"Skill" 和 "skill":"<skill-name>" 是否出现
列出实际触发了哪些 Skill（用于诊断触发了错误的 Skill）

这是实证验证 prompt engineering 效果的方法，而非依赖直觉。测试文件本身就是"假装不知道 Skill 名的用户"的对话模拟。

18. 平台降级策略

Gemini CLI 没有 Task 工具（子 Agent）：

所有依赖子 Agent 的 Skill（subagent-driven-development、dispatching-parallel-agents）自动降级到 executing-plans
Gemini CLI 有 Claude Code 没有的工具：save_memory、enter_plan_mode/exit_plan_mode（只读研究模式）、tracker_create_task
GEMINI.md 用 @import 语法在 Session 启动时自动注入 Skill 和工具映射表

这揭示了平台能力差异如何影响工作流设计：Superpowers 不是依赖单一平台特性，而是定义工作流，然后针对每个平台选择最合适的实现方式。

19. 条件等待（Condition-Based Waiting）

核心原则： 等待实际条件，而非猜测所需时间

typescript

// ❌ 猜测时间
await new Promise(r => setTimeout(r, 50));

// ✅ 等待条件
await waitFor(() => getResult() !== undefined);

何时允许任意超时： 当你在测试具体的时间行为（如 debounce 间隔），并且：

先等待触发条件
超时值有文档说明（如 "200ms = 2 ticks at 100ms intervals"）

实际数据：15 个 flaky 测试全部修复，通过率 60% → 100%，执行时间减少 40%。

可借鉴的原则

P1：关卡（Gate）比建议（Guideline）更可靠 AI 在压力下会合理化绕过建议。HARD-GATE + 预先反驳借口 = 结构性拦截。

P2：文档的受众应该是零上下文 Agent，而非人类读者 如果文档完整到让零上下文子 Agent 独立执行，它对人类也必然够清晰。这是更高的标准。

P3：AI 审查先，人工审查后 AI 处理可机械验证的技术问题，人工处理需要意图判断的问题。两类问题性质不同，顺序不能倒置。

P4：实现意图格式（"When X, do Y"）比一般性指导有效 触发条件 + 强制动作 = 自动行为。这是研究证实的（Implementation Intention 理论）。

P5：Liking 原则与纪律文化互斥 需要纪律的工作流必须明确禁止讨好行为，否则 AI 会用"Great point!"代替技术评估。

P6：对抗性验证优于信任性验证 "不要信任实施者的报告"是刻意设计，而非默认怀疑。这对抗 AI 的系统性乐观偏差。

P7：3 次失败 → 质疑架构，而非继续修复 当多次修复都揭示出新地方的新问题时，症状治疗已到上限，需要切换到架构讨论。

P8：纵深防御让 bug 结构性不可能 单点修复："我们修了 bug"。多层防御："bug 不可能再发生"。每层捕获不同代码路径的问题。

P9：独立域并行，相关域顺序 判断标准不是"这些任务看起来类似"，而是"修复一个会不会影响对另一个的理解"。

P10：Skill description 的第三人称规则 AI 系统注入到 system prompt 时，视角不一致会破坏 Skill 的选择逻辑。

可借鉴的操作方法

M1：Checklist + TodoWrite = 强制顺序执行 每个 checklist 项目对应一个 TodoWrite task。利用 Commitment 原则：公开声明了就必须完成。

M2：Red Flags 表 不是"注意这些模式"，而是"看到这些 → 立刻停止 → 从头重来"。有具体的停止条件。

M3：Spec/Plan Reviewer 子 Agent 的结构化 prompt 7 维审查标准（完整性、覆盖度、一致性、清晰度、YAGNI、范围、架构）+ 明确的"CRITICAL"重点 + 标准化输出格式。

M4：4 选项结构化决策 永远给出精确 N 个选项，每个选项对状态（worktree、branch）的影响都精确定义。禁止开放式"你想怎么处理？"

M5：Worktree 创建的 3 步优先级 已有目录 > CLAUDE.md 偏好 > 问用户。创建前必须用 git check-ignore 验证已在 .gitignore。

M6：基线测试（开工前先验证状态） 新 worktree 创建后立即运行全量测试，确认基线干净，才能区分新 bug 和已有 bug。

M7：Skill 触发率量化测试 用 stream-json 解析实际 Claude 会话输出，验证在自然语言 prompt 下 Skill 是否被正确触发。

M8：压力场景测试（3+ 种压力） 时间 + 沉没成本 + 疲惫，强制 A/B/C 选择，用"IMPORTANT: This is a real scenario"防学术化。

M9：Meta-testing 定位 Skill 问题根源 Agent 违规后，问它"Skill 怎么写才能让你清楚"，三种回答分别指向：原则强度、内容缺失、组织结构问题。

M10：诊断日志在每个组件边界 调试多组件系统时，先在每层边界加日志，跑一次收集证据，再根据证据定位失败层，最后才修复。

M11：Polyglot CMD+bash 跨平台脚本: << 'CMDBLOCK' 技巧让同一文件在 Windows CMD 和 Unix bash 下走不同分支，无需平台判断。

M12：零依赖工具实现 用语言内置模块（Node.js http、fs、crypto）替代外部依赖，减少安装摩擦和维护负担。手动实现 WebSocket RFC 6455，但获得了完全的控制权和可移植性。

M13：进程生命周期管理 服务器监控父进程 PID，父进程死亡时自动退出。无客户端连接超过 30 分钟自动退出。防止孤儿进程积累。

值得继续深入的方向

brainstorm-server 的 WebSocket RFC 6455 实现细节：手动实现帧格式、ping/pong、close handshake，tests/brainstorm-server/ 有完整测试套件
find-polluter.sh 的测试污染定位机制：二分查找法定位测试间污染，完整可用的工具
Gemini CLI 的 enter_plan_mode 模式：只读研究模式，Claude Code 没有对应工具，但这个模式的设计理念（先研究再修改）值得借鉴
condition-based-waiting-example.ts：来自真实调试会话的完整实现，包含 waitForEvent、waitForEventCount、waitForEventMatch 等域特定辅助函数
CLAUDE_MD_TESTING.md 的完整测试战役：测试了 Skill 发现机制在多种压力场景（生产宕机、沉没成本、权威命令）下的合规率，是完整的 Skill TDD 实战案例

项目学习洞察：Superpowers ​

项目概览 ​

核心设计思想 ​

1. 完整流水线：控制流的精确定义 ​

2. 文档是上下文切断器，不是归档工具 ​

3. 双轨验证：顺序固定，不可反转 ​

4. Skill 的两种类型：Rigid vs Flexible ​

5. HARD-GATE 的设计原理 ​

6. 说服力工程：让 AI 遵守规则的底层原理 ​

7. 抗合理化设计：关闭所有逃脱路径 ​

8. 不信任实施者报告原则 ​

9. 系统性调试：4 阶段 + 架构升级触发器 ​

10. 模型成本分级：内置在工作流中 ​

11. Graphviz 作为流程文档的 DSL ​

12. 并行 Agent 的独立域分解 ​

13. Skill Description 是最关键的 1024 个字符 ​

14. 自由度设计谱（Degrees of Freedom） ​

15. Polyglot 脚本：Windows + Unix 双平台共存 ​

16. Skill TDD：对流程文档的测试 ​

17. 触发率量化测试 ​

18. 平台降级策略 ​

19. 条件等待（Condition-Based Waiting） ​

可借鉴的原则 ​

可借鉴的操作方法 ​

值得继续深入的方向 ​