Superpowers 深度拆解：日增 900 Star 的「AI 编程方法论」，如何把工程纪律编译进编码代理的大脑
2026 年 7 月的 GitHub Trending 上，有一个项目以每天 900+ Star 的速度持续霸榜——obra/superpowers。它不是模型，不是 IDE，甚至不是一个可以
import的库。它是一堆 Markdown 文件。但就是这堆 Markdown，正在悄悄改变 AI 编程代理的工作方式：从「拿到需求就狂写代码」，变成「先提问、再设计、后拆解、TDD 落地、子代理互审」。这篇文章我们把它拆开，看看一个纯文本项目凭什么值 3 万多 Star，以及它背后那套「Process over Prompt」的方法论对我们意味着什么。
一、背景：AI 编程的「最后一公里」问题
先说一个所有用过 Claude Code、Codex、Cursor 的人都遇到过的场景：
你说「帮我加一个用户导出功能」，AI 立刻开始输出代码。写得飞快，看起来也像那么回事。但十分钟后你发现：
- 它没问你要导出什么格式，自作主张选了 CSV；
- 它顺手「优化」了旁边一个不相关的函数，把别的功能改挂了；
- 它没写测试，或者写了几个永远为真的假测试；
- 你让它修一个 bug，它凭感觉乱改，越改越乱，最后把原来能跑的部分也改坏了。
这不是模型能力问题。2026 年的旗舰模型，单论写代码的「手速」和「知识面」早已超过大多数工程师。问题出在工作方式上：模型被训练成「尽快给出让用户满意的回答」，而软件工程恰恰要求「先慢下来」——澄清需求、评审设计、小步提交、测试先行。
这两者的冲突，就是 AI 编程的最后一公里。模型越强，写错方向的代码越多、越快。
Jesse Vincent（GitHub ID：obra，Perl 社区老兵、Request Tracker 和 K-9 Mail 的作者）给出的答案不是更好的 Prompt，而是一整套可被 AI 代理自动加载和执行的工程流程。他把这个项目叫 Superpowers——给你的编码代理装上超能力。
有意思的是，这个「超能力」的本质，恰恰是限制：限制 AI 不许直接写代码，限制它必须先写测试，限制它每次只做一件小事。
二、核心概念：Skills Framework 到底是什么
2.1 不是 Prompt 模板，是「技能协议」
Superpowers 建立在 Anthropic 的 Agent Skills 机制之上。所谓 Skill，物理形态就是一个目录加一个 SKILL.md 文件：
---
name: test-driven-development
description: Use when implementing any new feature or bugfix.
Enforces strict RED-GREEN-REFACTOR cycle.
---
# Test-Driven Development
## Overview
Write a failing test FIRST. Watch it fail. Then write the minimum
code to make it pass. Then refactor.
## The Iron Law
NO PRODUCTION CODE WITHOUT A FAILING TEST. No exceptions.
## Process
1. RED: Write one failing test that describes the next behavior
2. Verify it fails for the RIGHT reason
3. GREEN: Write minimum code to pass
4. REFACTOR: Clean up while staying green
...
关键在 frontmatter 里的 description 字段——它是技能的触发器。代理启动时只加载所有技能的名字和描述（每个大约几十 token），当对话内容命中某个描述的场景时，才把完整的 SKILL.md 读进上下文。
这就是所谓的渐进披露（Progressive Disclosure）：几十个技能常驻时只占千把 token，用到哪个才展开哪个。相比把所有规则塞进一个巨型系统提示词，这个设计同时解决了两个问题：上下文窗口的经济性，以及规则之间的互相干扰。
2.2 与 MCP 的本质区别
很多人第一反应是：这不就是 MCP 吗？不是。两者解决的是正交的问题：
- MCP 给代理接上外部世界——数据库、浏览器、API，解决「能做什么」；
- Skills 给代理注入做事方式——TDD、调试流程、Git 纪律，解决「该怎么做」。
一个是手脚，一个是肌肉记忆。MCP Server 是运行的进程，Skill 是纯文本；MCP 调用是显式的工具调用，Skill 的「调用」是模型阅读并遵循一段流程文档。Superpowers 甚至不需要任何运行时依赖——这也是它能同时支持 Claude Code、Codex、Cursor、Gemini CLI、Kimi Code、OpenCode 等十来个 harness 的原因：仓库里 .claude-plugin、.codex-plugin、.cursor-plugin、.kimi-plugin 各自一套适配层，核心的 skills/ 目录完全共享。
2.3 强制力从哪来：Hook 机制
纯靠模型「自觉」遵守流程是不可靠的——上下文一长，规则就被稀释遗忘。Superpowers 的解法是在 harness 的生命周期钩子上做文章。
以 Claude Code 为例，插件注册了 SessionStart hook：会话一启动，先把一段引导指令注入上下文，核心内容大意是：
在做任何事之前，检查是否存在与当前任务匹配的技能。如果存在，你必须使用它。「我觉得不用也行」不是可接受的理由。
这段话看似简单，实际是整个系统的「宪法」。它把技能检索从「可选优化」变成「强制前置步骤」。配合技能文档里大量出现的祈使句和「Iron Law（铁律）」式表述——比如 TDD 技能里的「没有失败的测试就不许写生产代码，没有例外」——模型的遵循率会显著高于普通建议式提示。
这里有个值得玩味的工程细节：Superpowers 的技能文档在写作风格上刻意使用了「对抗模型天性」的语言。因为作者很清楚，模型天生倾向于讨好用户、走捷径、宣称任务完成。所以技能里会预先堵死这些退路，比如 verification-before-completion（完成前验证）技能明确要求：宣称「测试通过」之前必须真的运行测试并展示输出，不允许基于「应该没问题」的推断。
这本质上是在用文本工程对抗 RLHF 带来的行为偏差——一个相当反直觉但实践有效的思路。
三、架构分析：一条完整的工程流水线
Superpowers 有 20 多个技能，但它不是技能的松散集合，而是一条有向的工作流。主链路如下：
brainstorming（需求澄清）
↓
writing-plans（实施计划）
↓
subagent-driven-development（子代理执行）
├── test-driven-development（TDD 循环）
├── systematic-debugging（系统化调试）
└── requesting-code-review（代码评审）
↓
finishing-a-development-branch（收尾合并）
逐段拆解。
3.1 brainstorming：苏格拉底式需求拷问
当代理发现你要「构建某个东西」时，第一个激活的技能是 brainstorming。它不许 AI 直接动手，而是要求：
- 一次只问一个问题，通过连续提问把模糊的想法逼成明确的规格；
- 优先问「这个功能给谁用、什么场景触发、失败了怎么办」这类边界问题；
- 把整理出的设计分成短小的块逐段展示给用户确认——因为作者深知没人会认真读两千字的设计文档；
- 用户签字确认前，不进入下一阶段。
这个阶段的产出是一份经过确认的设计文档，会写进 docs/plans/ 目录留档。
很多人第一次用会觉得烦：「我就想加个按钮，你问我八个问题？」但用过几次就会发现，这八个问题里往往有两个你自己都没想清楚。AI 提问的价值不在于 AI 需要答案，而在于逼你把需求想透。
3.2 writing-plans：为「最笨的执行者」写计划
设计确认后，进入计划阶段。Superpowers 对实施计划的质量标准有一句非常精彩的定义：
计划要清晰到「一个热情高涨、但品味差、没有判断力、不了解项目背景、还讨厌写测试的初级工程师」也能照着执行。
这个假想的「最笨执行者」不是别人，就是即将启动的子代理——它们拿不到完整对话历史，只有计划文本本身。所以计划必须把每个任务拆到 2-5 分钟粒度，每一步都写明：改哪个文件、写什么测试、怎么验证成功。
这其实就是软件工程里「文档要经得起新人执行」原则的极端版本。区别在于，人类团队里这条原则常年被嘴上遵守，而在 Superpowers 里它被结构性强制了。
3.3 subagent-driven-development：会互相审查的代理流水线
这是整个系统最有含金量的部分。用户说「go」之后，主代理不再亲自写码，而是变成调度者：
- 为计划里的每个任务派生一个干净上下文的实现子代理；
- 实现子代理严格按 TDD 循环工作：先写失败测试 → 确认失败原因正确 → 写最小实现 → 通过 → 重构；
- 任务完成后，再派生一个评审子代理检查产出——它的上下文同样干净，不会被实现过程中的「自我说服」污染；
- 评审通过才走下一个任务，不通过就打回重做。
为什么这个结构有效？因为它针对性解决了长上下文的两大顽疾：
**其一，上下文污染。**同一个代理连续工作几小时后，早期的错误假设会像滚雪球一样累积。每个任务用新鲜子代理，等于强制「清空缓存」。
**其二，自我评审失效。**让写代码的代理评审自己的代码，就像让学生自己批改作卷——它在实现时已经说服自己方案是对的。独立评审代理没有这层心理包袱（准确说是没有这层上下文包袱），挑错能力显著更强。
实践中，这套流水线可以让代理连续自主工作数小时不跑偏——这在裸奔的编码代理上几乎不可能。
3.4 systematic-debugging：禁止「凭感觉改改看」
调试技能是我个人认为最值得人类工程师也读一遍的一篇。它的第一条规则：
在没有定位根因之前，禁止修改任何代码。
流程是标准的科学方法四步：读错误信息 → 形成假设 → 设计最小实验验证假设 → 确认根因后再修。配套的 root-cause-tracing 技能还要求沿着调用栈向上追溯，找到问题的最初注入点，而不是在症状出现的地方打补丁。
这直接掐死了 AI 调试最恶名昭著的行为模式：跑一次、看报错、瞎改一行、再跑一次、再瞎改——每次迭代都在给代码库里注入新的不确定性。
3.5 Git 纪律：worktree 隔离与收尾流程
using-git-worktrees 技能要求代理在开始一个功能前创建独立的 git worktree，在隔离目录里工作，避免污染主工作区。finishing-a-development-branch 则规定了收尾动作：确认全部测试通过 → 整理提交历史 → 给出合并选项。整个过程中代理频繁做小步提交，每个提交对应一个通过测试的最小改动——出问题时回滚成本极低。
四、代码实战：装上它，再写一个自己的技能
4.1 安装
Claude Code 用户最简单，官方插件市场直接装：
/plugin install superpowers@claude-plugins-official
或者用作者自己的 marketplace：
/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplace
其他 harness 各有入口：
# Gemini CLI
gemini extensions install https://github.com/obra/superpowers
# Factory Droid
droid plugin marketplace add https://github.com/obra/superpowers
droid plugin install superpowers@superpowers
# GitHub Copilot CLI
copilot plugin marketplace add obra/superpowers-marketplace
copilot plugin install superpowers@superpowers-marketplace
装完不需要任何配置。下次会话开始，随便说一句「我想做个 XX」，你会立刻发现代理的行为变了——它开始反问你问题了。
4.2 验证它真的在工作
一个简单的对照实验：分别在裸代理和装了 Superpowers 的代理上执行同一句话——「给这个项目加一个限流中间件」。
裸代理的典型行为：直接生成一个 rateLimiter.js，顺带修改入口文件，全程零提问，零测试。
Superpowers 代理的典型行为：先问你限流算法要令牌桶还是滑动窗口、限流维度是 IP 还是用户、超限返回 429 还是排队；确认后给出分块设计；你点头后生成任务计划；执行时每个任务都先出现一个失败测试的运行记录，然后才是实现代码。
4.3 写一个自己的技能
Superpowers 的技能格式是开放的，你完全可以为自己团队的私有规范写技能。比如强制 API 错误码规范：
---
name: api-error-convention
description: Use when writing or modifying any HTTP API handler.
Enforces the team's unified error response format.
---
# API Error Convention
## The Rule
All error responses MUST use this shape. No inline error strings.
```json
{
"code": "USER_NOT_FOUND", // SCREAMING_SNAKE, from errors/catalog.ts
"message": "human readable",
"traceId": "..." // always from request context
}
```
## Process
1. Before adding a new error, check errors/catalog.ts for an existing code
2. New codes MUST be added to the catalog first, with a test
3. NEVER return raw exception messages to the client
## Red Flags
- `res.status(500).send(err.message)` — leaking internals, rejected
- Inventing error codes inline — rejected
把它放进项目的技能目录（Claude Code 下是 .claude/skills/api-error-convention/SKILL.md），代理写接口时就会自动遵循。写技能的几条经验，来自 Superpowers 自身的文档风格：
- description 决定触发率——写「Use when + 具体场景」，不要写抽象概括；
- 规则用祈使句和 MUST/NEVER，模型对强语气的遵循率明显更高；
- 给出反面示例（Red Flags），模型对「不要做什么」的具体例子比原则性表述敏感得多；
- 一个技能只管一件事，复合流程拆成多个技能互相引用。
顺带一提，Superpowers 里还有一个元技能 writing-skills，专门教代理如何写技能——它会用 TDD 的思路对待文档：先设想代理会在哪些场景误解规则（测试用例），再针对性地把文档写到无法误解（实现）。这个「文档也要测试驱动」的观念相当超前。
五、性能与成本：理性看待开销
工程上没有免费的午餐，Superpowers 的代价要摊开讲清楚。
**Token 成本显著上升。**需求澄清多轮对话、设计文档、任务计划、每个任务的子代理派生和评审——粗略估算，同样一个功能，完整走 Superpowers 流程的 token 消耗是裸写的 2-4 倍。子代理虽然上下文干净，但每次派生都要重新加载相关文件。
**时间成本前置。**以前 30 秒出代码，现在可能要 10 分钟对话才开始写第一行。对于「改个错别字」级别的任务，这套流程纯属杀鸡用牛刀——好在技能触发是场景敏感的，简单任务一般不会拉起完整流水线，但边界判断偶尔会失误，你需要偶尔手动喊停。
**收益在哪里？**在返工率上。裸代理生成的代码，方向错了就是全部推倒重来，而且错误往往在你 review 时才暴露，此时它已经写了两千行。Superpowers 把「发现方向错误」的时机提前到了设计阶段——改一段文档的成本和改两千行代码的成本，差着两个数量级。用软件工程的老话说：缺陷发现得越早，修复成本越低。这条规律对 AI 生成的代码同样成立，甚至更成立，因为 AI 产码速度快，错误累积速度也快。
我的建议是分场景决策：
- 一次性脚本、原型验证、CSS 微调 → 裸代理更划算；
- 要进主干、要长期维护、多人协作的代码 → Superpowers 流程的 token 溢价完全值得；
- 大型重构、跨模块改动 → 不用这类流程框架基本等于赌博。
六、冷思考：方法论框架的边界
夸完了，说几个真实存在的问题。
**第一，强制力仍然是概率性的。**Hook 注入和铁律话术能大幅提升遵循率，但模型偶尔还是会「越狱」——尤其在上下文极长、或用户明确表达不耐烦时，代理可能悄悄跳过评审步骤。文本层面的约束终究不是沙箱层面的约束。真正的硬保证需要 harness 在工具调用层做拦截（比如没有测试文件变更就拒绝提交），这超出了纯 Skill 框架的能力范围。
**第二，方法论有强烈的作者偏好。**TDD、YAGNI、小步提交是 Jesse Vincent 那一代 Perl/极限编程社区的信仰。它们是久经考验的好实践，但不是唯一正确的实践。如果你的团队走的是「原型先行、测试后补」或者研究型代码路线，Superpowers 的铁律会跟你处处顶牛。好在技能是 Markdown，改起来没有门槛——但改完你维护的就是自己的 fork 了。
**第三，生态的碎片化风险。**Skills 这个概念在 2026 年爆发后，出现了 Superpowers、mattpocock/skills、Awesome Claude Skills 等一大批技能库，格式虽然都基于 SKILL.md，但初始指令、目录约定、触发机制各有各的玩法。多个技能库同时安装时的规则冲突（比如两个库对 Git 提交规范的要求不一致），目前没有任何仲裁机制，全靠模型自己「权衡」——结果自然是不可预测的。
**第四，它无法替代你对代码的理解。**这可能是最重要的一条。Superpowers 让 AI 产出的代码在流程上可靠了，但「流程可靠」不等于「你可以不看」。设计确认环节如果你无脑点头，垃圾需求走完全套流程还是垃圾——只是变成了有测试覆盖、提交历史整洁的垃圾。工具把纪律强加给了 AI，但判断力依然只能来自人。
七、总结与展望
Superpowers 值得关注，不只因为它好用，更因为它代表了一个正在成形的判断：
AI 编程的下半场，竞争焦点从模型能力转向了过程控制。
模型每半年换一代，但「先想清楚再动手、测试先行、小步提交、独立评审」这些工程原则四十年没变过。Superpowers 做的事情，本质上是把这四十年的行业共识编译成了模型可执行的格式。它的日增 900 Star 说明市场已经意识到：让 AI 写得更快很容易，让 AI 写得可控才是稀缺能力。
往前看，有几个趋势值得留意：
- 技能标准化：Anthropic 的 Agent Skills 格式事实上已成为通用标准，各家 harness 争相兼容，跨平台技能库会成为新的基础设施层；
- 从文本约束到运行时约束：下一代框架大概率会把「铁律」下沉到工具调用拦截层，文本方法论 + 运行时护栏的双层结构会更可靠；
- 团队级技能资产：私有技能库会像今天的 ESLint 配置一样，成为每个工程团队的标配资产——你的团队规范第一次可以被「执行」而不只是被「宣讲」。
最后给个可操作的建议：哪怕你不打算长期使用 Superpowers，也强烈建议装上跑一周，然后去 skills/ 目录把那二十几个 SKILL.md 通读一遍。它们是我近年读过的最好的软件工程文档之一——简洁、可执行、每条规则都附带「为什么」和反面案例。
毕竟，能把资深工程师的肌肉记忆写成连「没有判断力的初级工程师」都能执行的文档，这件事本身，就是顶级的工程能力。
项目地址：https://github.com/obra/superpowers（MIT 协议）