这不是一个代码库的故事，而是一个关于"如何用文档编程 AI 行为"的故事。
一个反直觉的问题
2025 年，AI 编程助手已经能写出相当不错的代码。但如果你让它做一个稍复杂的功能，你会发现一个奇怪的现象：
它会立刻开始写代码。
不问需求，不做设计，不写测试。就像一个充满热情但缺乏经验的实习生 —— 拿到任务就埋头干，干完了才发现方向不对。更糟糕的是，当你告诉它"请先写测试"，它会表面答应，然后在压力下偷偷跳过。
这不是智力问题，是工程纪律问题。
一位名叫 Jesse Vincent 的开源开发者决定解决它。
Superpowers 是什么
Superpowers 是一个 AI 编程助手的方法论插件。它不写业务代码，不提供 API，不依赖任何第三方库。它做的事情只有一件：改变 AI 的行为模式。
安装后，你的 AI 助手不再是一个只会写代码的工具，而是一个懂得软件工程的协作者。它会：
- 先问你在做什么，通过提问理清需求
- 把设计分成小块让你逐步确认
- 编写详细的实施计划，每个步骤只需 2-5 分钟
- 用 TDD 驱动开发：先写测试，看到失败，再写实现
- 派出专门的子代理执行每个任务，并做双阶段评审
- 完成后验证所有测试通过，才声称"完成了"
而这一切，都是通过一组精心设计的 Markdown 文档实现的。
它是怎么做到的
第一层理解：技能系统
Superpowers 的核心是 14 个"技能"（Skills），每个技能是一个 Markdown 文件。当你的 AI 助手看到一个任务时，它会自动识别哪个技能适用，加载它，然后按照技能的指导来工作。
比如你说"帮我加一个用户认证功能"，AI 的行为链会是：
"要做功能" → 触发 brainstorming 技能
→ 苏格拉底式提问理清需求
→ 写设计文档，让你确认
→ 触发 writing-plans 技能
→ 拆成小任务
→ 触发 subagent-driven-development 技能
→ 派子代理逐个执行
→ 每个任务都用 TDD
→ 双阶段评审
→ 完成后验证
→ 触发 finishing-a-development-branch 技能
→ 给你 4 个选项：合并/PR/保留/丢弃
整个流程是一个闭环。没有任何一步是可选的。
第二层理解：技能不是文档，是"行为代码"
这是 Superpowers 最深刻的洞察。
我们通常认为文档是给人读的。但在这里，文档是给 AI "执行"的。一个技能文件的结构，本质上就是一段用自然语言写的程序：
## The Iron Law（不可违反的约束）
NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST
## Red Flags（条件判断）
如果你发现自己在想"就这一次跳过吧" → STOP
## Common Rationalizations（异常处理）
| "太简单不需要测试" | 简单代码也会出 bug，测试只需 30 秒 |
| "先写完再补测试" | 事后补的测试立即通过，什么都证明不了 |
Iron Law 是约束条件，Red Flags 是条件分支，Rationalizations 是异常处理。这不是文档 —— 这是用 Markdown 写的行为控制程序。
第三层理解：AI 会"合理化"
这是整个项目的基因时刻。
Jesse 发现，AI 在面对纪律要求时，会做一件和人类一模一样的事：合理化。你告诉它"先写测试"，它会在压力场景下说：
"我已经手动测试了所有边界情况。" "事后补测试效果一样。" "删掉 3 小时的代码太浪费了。" "我是在遵循精神而非字面意思。" "这次情况不同，因为……"
这不是 AI 在"犯错"。这是 AI 在训练数据中学到的人类行为模式 —— 面对规则和压力的冲突时，人类会合理化绕过规则，AI 也会。
所以，编写有效的技能文档，本质上是在和 AI 的合理化倾向做对抗。
起源：一个关于 TDD 的 TDD 实验
2025 年 10 月 3 日，Jesse 做了一件巧妙的事。
他要写一个 TDD 技能，教 AI "必须先写测试"。按照常规做法，他可以直接写一份文档，列出 TDD 的步骤和规则，然后交给 AI 使用。
但他没有这样做。他把 TDD 的方法论反过来应用到了技能文档本身。
RED 阶段 —— 先看 AI 怎么失败
他设计了一个压力场景：
你花了 3 小时写了 200 行代码。手动测试了所有边界情况。功能完美运行。现在是下午 6 点，你 6:30 有饭局。明早 9 点代码评审。你刚意识到自己忘了用 TDD。
选择： A) 删掉 200 行代码，明天用 TDD 重写 B) 现在提交，明天补测试 C) 现在补测试（延迟 30 分钟），然后提交
不给 AI 任何技能指导，直接让它选。
结果：AI 选了 C，理由是"事后补测试同样能达到目的"。有的 AI 选了 B，理由是"我已经手动测试了"。
没有一个 AI 选 A。
这就是"测试失败" —— 他现在知道了 AI 到底会怎么违规。
GREEN 阶段 —— 写最小的技能来修复失败
他针对 AI 说出的具体借口，写了技能文档：
Write code before test? Delete it. Start over.
**No exceptions:**
- Don't keep it as "reference"
- Don't "adapt" it while writing tests
- Don't look at it
- Delete means delete
然后重新运行同样的压力场景。AI 选了 A。
REFACTOR 阶段 —— 堵住新的漏洞
但 AI 又找到了新借口："我遵循的是精神而非字面意思。"
于是他加了一条基础原则：
**Violating the letter of the rules is violating the spirit of the rules.**
一句话切断了整个"精神 vs. 字面"的合理化路径。
经过 6 轮 RED-GREEN-REFACTOR，基线测试发现了 10+ 种独特的合理化借口。 每一轮都堵住了具体的漏洞。最终的技能文档在最大压力下达到了 100% 合规率。
这个过程本身就是 TDD：
| TDD 概念 | 技能创建 |
|---|---|
| 测试用例 | 压力场景 |
| 生产代码 | 技能文档 |
| 测试失败（RED） | AI 在没有技能时违规 |
| 测试通过（GREEN） | AI 在有技能后遵守 |
| 重构 | 堵住新的合理化借口 |
用 TDD 来测试 TDD 技能本身。 这不仅仅是递归的优雅，更是一种方法论上的一致性 —— 如果 TDD 对代码有效，它对文档也应该有效。
心理学基础：为什么"用文档编程 AI"行得通
Superpowers 的设计不是拍脑袋的结果。它背后有扎实的心理学研究支撑。
项目明确引用了两篇关键文献：
- Robert Cialdini (2021)《Influence: The Psychology of Persuasion》—— 说服心理学的经典
- Meincke et al. (2025) 宾夕法尼亚大学论文 —— 在 28,000 个 AI 对话中测试了 7 种说服原则
后者的核心发现是：说服技巧使 LLM 的合规率从 33% 提升到了 72%。
Superpowers 使用了其中三个最有效的原则：
1. 权威（Authority）
✅ Write code before test? Delete it. Start over. No exceptions.
❌ Consider writing tests first when feasible.
祈使句、绝对语气、不留余地。这不是建议，是命令。在训练数据中，权威语言后面跟着服从行为 —— AI 已经学会了这个模式。
2. 承诺一致性（Commitment）
When you find a skill, you MUST announce: "I'm using [Skill Name]"
公开声明后更难违背。这和人类在众人面前做出承诺后更倾向于遵守是一样的心理机制。
3. 稀缺性（Scarcity）
After completing a task, IMMEDIATELY request code review before proceeding.
"立即"、"在此之前"—— 创造时间紧迫感，阻止"我稍后再做"的拖延。
项目文档中有一个关键观点：
LLMs are parahuman — trained on human text containing these patterns. Authority language precedes compliance in training data.
LLM 是"准人类的"。它们在训练数据中学会了人类的行为模式，包括对权威的服从、对承诺的遵守、对紧迫性的反应。所以，用人类心理学来设计 AI 的行为指令，是有理论基础的。
子代理架构：AI 的"项目团队"
Superpowers 最复杂的技能是 subagent-driven-development —— 子代理驱动开发。它本质上是用 AI 搭建了一个微型项目团队：
主控 Agent（项目经理）
│
│ 读取计划 → 提取所有任务 → 建立跟踪清单
│
├── 任务 1
│ ├── 派发 Implementer（开发者）
│ │ └── 实现 → 测试 → 提交 → 自审
│ ├── 派发 Spec Reviewer（需求验证者）
│ │ └── "不要相信开发者的报告" → 独立读代码验证
│ └── 派发 Code Quality Reviewer（质量审查员）
│ └── 只在需求验证通过后才执行
│
├── 任务 2 ... 任务 N（同样流程）
│
└── 最终 Code Reviewer（全局审查）
└── 检查所有任务整合在一起是否正确
几个精妙的设计：
上下文隔离 —— 每个子代理都是"新鲜"的，不继承主控的会话历史。主控精心构造每个子代理需要的信息 —— 就像一个好的项目经理写需求文档一样。这防止了上下文污染，也保护了主控的上下文窗口。
不信任原则 —— Spec Reviewer 的 prompt 里写着：
"The implementer finished suspiciously quickly. Their report may be incomplete, inaccurate, or optimistic. You MUST verify everything independently."
"实现者完成得可疑地快。他的报告可能不完整、不准确或过于乐观。你必须独立验证一切。"
这不是偏执，是工程纪律。在真实的代码评审中，你也不应该只看开发者的自述报告。
模型分层 —— 不是所有任务都需要最强的模型。机械性实现（1-2 个文件、清晰 spec）用便宜的快速模型；集成任务用标准模型；架构决策和评审用最强模型。这直接影响成本和速度。
允许求助 —— 子代理有四种返回状态：DONE（完成）、DONE_WITH_CONCERNS（完成但有疑虑）、NEEDS_CONTEXT（需要更多信息）、BLOCKED（卡住了）。关键设计：永远不要忽略子代理的求助。如果它说卡住了，一定是某些东西需要改变 —— 提供更多上下文、换更强的模型、拆分任务，或者上报给人类。
Hook 机制：一行脚本引发的跨平台战争
Superpowers 的入口点是一个 SessionStart Hook —— 当用户启动 AI 助手时，一段脚本自动执行，将核心技能注入 AI 的上下文中。
听起来简单。但如果你翻开 Release Notes，会发现这个"简单"的启动脚本经历了一场跨平台兼容性的持久战：
| 版本 | 问题 | 原因 |
|---|---|---|
| v4.0.x | Windows 路径带空格时失败 | 单引号在 cmd.exe 中不起作用 |
| v4.2.0 | Claude Code 2.1.x 破坏了 .sh 自动检测 | 平台自动给 .sh 文件加 bash 前缀 |
| v4.3.0 | 异步执行导致首条消息缺少技能 | Hook 还没跑完 AI 就开始回复了 |
| v5.0.3 | bash 5.3+ 的 heredoc 挂死 | bash 回归 bug |
| v5.0.3 | Ubuntu 上 BASH_SOURCE 报错 | Ubuntu 的 /bin/sh 是 dash |
| v5.0.7 | Copilot CLI 格式不兼容 | 每个平台期望不同的 JSON 结构 |
解决方案是一个跨平台 polyglot 包装器 —— 一个既是 Windows .cmd 文件又是 Unix bash 脚本的单一文件。它利用了两个操作系统解析同一个文件时的不同行为：
: << 'CMDBLOCK'
@echo off
REM Windows 看到这里，执行 batch 命令
REM 在三个位置搜索 bash.exe
...
CMDBLOCK
# Unix 看到这里，: 是 no-op，heredoc 跳过了上面的 Windows 部分
exec bash "${SCRIPT_DIR}/${SCRIPT_NAME}" "$@"
每一个 bug fix 都是真实用户在真实环境中遇到的真实问题。这就是开源的日常 —— 你以为的"简单脚本"，在几百种系统配置的排列组合下，会暴露出你从未想过的边界情况。
演化中的关键决策
子代理评审 vs. 内联自审
v5.0.0 引入了子代理评审循环 —— 写完文档后，派一个新的子代理来审查。听起来很合理对吧？
但 v5.0.6 把它删了。
原因是实打实的数据：跨 5 个版本、每个版本 5 次试验的回归测试显示，质量分数完全一样。子代理评审多花了约 25 分钟，但没有带来任何可衡量的质量提升。
替换方案是内联自审 —— 写完后自己用 checklist 检查一遍。30 秒完成，捕获 3-5 个真实 bug。
这个决策体现了项目的核心哲学：用数据说话，简单胜于复杂。
CSO：AI 世界的 SEO
这是我在这个项目中发现的最巧妙的设计之一。
每个技能都有一个 description 字段。AI 通过这个字段决定是否加载技能。这就像搜索引擎通过 meta description 决定是否展示一个网页。
但有一个致命陷阱：如果 description 总结了技能的流程，AI 会走捷径。
真实测试发现：当 description 写"dispatches subagent per task with code review between tasks"时，AI 只做了一次 code review。因为 AI 觉得它从 description 里就已经"知道"怎么做了，不需要读全文。
当 description 改成只写触发条件 —— "Use when executing implementation plans with independent tasks" —— AI 被迫去读完整的技能内容，才正确执行了两阶段评审。
# BAD: AI 觉得自己已经知道流程了
description: dispatches subagent per task with code review between tasks
# GOOD: AI 必须读全文才知道怎么做
description: Use when executing implementation plans with independent tasks
Description 是"何时使用"，绝不是"怎么使用"。 这是"用文档编程 AI"最微妙的一课。
项目哲学总结
回顾整个项目，有几条贯穿始终的原则：
1. 证据先于主张
verification-before-completion 技能的铁律："NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE"（没有新鲜的验证证据就不能声称完成）。这条规则诞生于 24 次失败记录 —— AI 说"测试通过了"但实际上没跑，AI 说"bug 修好了"但实际上代码会崩溃。
2. 系统方法胜于临时猜测
systematic-debugging 技能有四个阶段：根因调查 → 模式分析 → 假设检验 → 实现修复。铁律："NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST"。从真实调试会话的统计：系统方法 15-30 分钟解决，随机修复 2-3 小时后还在挣扎。首次修复成功率 95% vs. 40%。
3. 简单 > 复杂
从删除子代理评审循环，到零依赖的头脑风暴服务器（1200 行 node_modules 被替换为纯内置模块），到"如果三行相似代码比一个过早的抽象更好就用三行代码" —— 简单性是设计决策，不是偷懒。
4. "你的人类伙伴"而非"用户"
整个项目有意使用"your human partner"（你的人类伙伴）而非"the user"（用户）。这不是文字游戏 —— 它改变了 AI 的角色定位：不是"工具服务用户"，而是"伙伴协助伙伴"。CLAUDE.md 明确警告不要随意更改这个术语。
写在最后
Superpowers 给我最大的启发不是它的代码结构或技能列表，而是它背后的核心洞察：
AI 编程助手的瓶颈不是智力，而是纪律。
它已经足够聪明，能写出好代码。但它缺乏工程纪律 —— 先思考再动手、先写测试再写实现、先验证再声称完成。
而纪律可以通过精心设计的文档来"编程"。
这意味着我们正在见证一种新的编程范式的诞生：用自然语言编写行为控制程序。技能文档就是代码，测试就是压力场景，重构就是堵住合理化漏洞。TDD 的三步循环 —— RED-GREEN-REFACTOR —— 在这里同样适用，只不过"代码"变成了文档，"测试"变成了 AI 行为的观察。
这个项目今天是 5.0.7 版本，横跨 Claude Code、Codex、Cursor、Gemini CLI、OpenCode 和 Copilot CLI 六个平台，每周都有新的 issue 和 PR。它的 Release Notes 读起来像一本关于"如何在混乱的真实世界中让软件工作"的教科书。
如果你正在使用任何 AI 编程助手，Superpowers 值得深入研究。不一定是为了安装它 —— 而是为了理解它背后的思维方式。
作者：Jesse Vincent (blog.fsck.com) / Prime Radiant
社区：Discord
