Superpowers 深度解析 — 如何用 Skill 系统驯服 AI Coding Agent

来源: obra/superpowers 作者: Jesse Vincent（Prime Radiant 创始人，RT/CPAN 作者） 日期: 2026-03-19 标签: Agent Skills Framework TDD Subagent Claude Code Software Development Methodology Stars: 96.7k+ 许可: MIT

一句话总结

Superpowers 把经过验证的软件工程方法论（设计先行、TDD、代码审查、子 Agent 隔离）编码为一组 Markdown Skill 文件，注入到 AI coding agent 的上下文中，使 agent 从”乱写代码”变成”遵循工程纪律的开发者”。

1. 问题背景：AI Coding Agent 的纪律危机

2025 年，AI coding agent（Claude Code、Cursor、Codex 等）已经能写出不错的代码。但在实际工程中，一个反复出现的问题是：

Agent 没有工程纪律。

具体表现为：

更深层的问题是：你无法用一次 prompt 永久改变 agent 的行为。即使你在系统提示里写”请先设计再编码”，agent 也会在各种压力下找到理由跳过——“这个太简单了不需要设计”、“先写完再补测试也一样”、“时间紧先不 review 了”。

Superpowers 的核心洞察：必须把工程规范编码为结构化的、可测试的、带有「反借口」机制的 Skill 文件，才能真正约束 agent 行为。

2. 架构设计：Skill 系统的工作原理

2.1 Bootstrap 机制

Superpowers 通过 Claude Code 的 plugin 系统注入一段 <session-start-hook>：

<session-start-hook><EXTREMELY_IMPORTANT>
You have Superpowers.
RIGHT NOW, go read: ~/.claude/plugins/cache/Superpowers/skills/getting-started/SKILL.md
</EXTREMELY_IMPORTANT></session-start-hook>

这段注入在每个 session 开始时生效，它完成三件事：

1. 告知 agent 它拥有 skill 系统
2. 教会 agent 如何搜索和加载 skill
3. 建立铁律：如果存在对应 skill，agent 必须使用

getting-started/SKILL.md 是整个系统的引导文件，它进一步指向 using-superpowers/SKILL.md——这是 Skill 系统的「宪法」。

2.2 Skill 的触发与匹配

每个 Skill 文件的 YAML frontmatter 包含 description 字段，描述触发条件：

---
name: test-driven-development
description: Use when implementing any feature or bugfix, before writing implementation code
---

Agent 在执行任何任务前，搜索所有 skill 的 description。如果当前任务与某个 skill 匹配（即使只有 1% 的可能性），agent 必须加载并遵循该 skill。

这里有一个精巧的设计：description 只描述触发条件，不描述 skill 做什么。作者在测试中发现，如果 description 里概括了 skill 的流程（比如写”dispatches subagent per task with code review between tasks”），Claude 会直接按 description 的简化描述行事，跳过阅读完整 skill 内容。这导致它只做一轮 review，而完整 skill 明确要求两轮（spec compliance + code quality）。

这是一个关于 LLM 行为的重要发现：LLM 会走认知捷径。如果 description 给了一个”够用”的摘要，它就不会去读完整文档。

2.3 Skill 的强制执行机制

using-superpowers/SKILL.md 建立了一套完整的「反逃逸」机制：

优先级层次：

1. 用户显式指令（CLAUDE.md、直接请求）— 最高优先级
2. Superpowers skill — 覆盖默认系统行为
3. 默认系统提示 — 最低优先级

红旗识别表——如果 agent 脑中出现以下念头，必须立刻停下来：

这张表的设计运用了认知行为疗法的思路：预先识别并标记出常见的合理化思维（rationalization），使 agent 在产生这些念头时能自我纠正。

2.4 Skill 的元技能：writing-skills

Superpowers 最优雅的设计是它的自举能力——它有一个 writing-skills 技能，专门教 agent 如何创建新的 skill。这个元技能本身遵循 TDD 原则：

TDD 概念        →  Skill 创建
──────────        ──────────
测试用例        →  用 subagent 做压力场景
生产代码        →  SKILL.md 文件
测试失败 (RED)  →  agent 在没有 skill 时违反规则（基线行为）
测试通过 (GREEN)→  agent 在有 skill 时遵守规则
重构            →  发现新的逃逸口 → 堵上 → 重新验证

铁律：没有先做失败测试就写 skill？删掉，重来。这和 TDD 对待代码的态度完全一致。

3. 核心工作流逐层解剖

Superpowers 定义了一条完整的软件开发流水线。我们逐个 skill 深入看它的源码实现。

3.1 Brainstorming — 设计先行的强制门控

源码关键设计：

<HARD-GATE>
Do NOT invoke any implementation skill, write any code, scaffold any project,
or take any implementation action until you have presented a design and
the user has approved it. This applies to EVERY project regardless of
perceived simplicity.
</HARD-GATE>

这是一个 硬门控（HARD-GATE），不是建议。任何项目，无论多简单，都必须经过设计阶段。

反模式识别：

Skill 文件里显式标记了最常见的逃逸借口：

“Every project goes through this process. A todo list, a single-function utility, a config change — all of them. ‘Simple’ projects are where unexamined assumptions cause the most wasted work.”

设计流程的 9 步 checklist：

1. 探索项目上下文（文件、文档、最近 commit）
2. 提供可视化伴侣（如果涉及 UI）
3. 逐个提问澄清需求（一次一个问题，偏好选择题）
4. 提出 2-3 个方案（带权衡和推荐）
5. 分段展示设计，每段获得用户确认
6. 写设计文档并 commit
7. 用 subagent 做 spec review（最多 3 轮，超过则上报人类）
8. 用户最终审批
9. 过渡到 writing-plans（唯一允许的下一步）

一个关键约束：brainstorming 完成后，唯一允许调用的下一个 skill 是 writing-plans。不允许跳到任何实现 skill。这防止了 agent 在拿到设计后直接开始写代码。

设计原则——可隔离性：

“Break the system into smaller units that each have one clear purpose, communicate through well-defined interfaces, and can be understood and tested independently.”

“Smaller, well-bounded units are also easier for you to work with — you reason better about code you can hold in context at once.”

这里作者明确指出了 LLM 的一个固有限制：context window 有限，代码越集中越容易出错。所以好的设计不仅对人类重要，对 AI agent 更加重要。

3.2 Writing Plans — 给”没有品味的初级工程师”写执行手册

核心定位：

“Write comprehensive implementation plans assuming the engineer has zero context for our codebase and questionable taste.”

这个措辞非常精准——它迫使计划必须做到：

• 每个任务 2-5 分钟粒度
• 包含精确的文件路径，不是”在某处添加验证”
• 包含完整的代码，不是”添加错误处理”
• 包含精确的运行命令和预期输出
• 遵循 TDD：每个任务的步骤是 test → verify fail → implement → verify pass → commit

任务模板的源码结构：

### Task N: [Component Name]

**Files:**
- Create: `exact/path/to/file.py`
- Modify: `exact/path/to/existing.py:123-145`
- Test: `tests/exact/path/to/test.py`

- [ ] **Step 1: Write the failing test**
```python
def test_specific_behavior():
    result = function(input)
    assert result == expected
```

- [ ] **Step 2: Run test to verify it fails**
Run: `pytest tests/path/test.py::test_name -v`
Expected: FAIL with "function not defined"

- [ ] **Step 3: Write minimal implementation**
- [ ] **Step 4: Run test to verify it passes**
- [ ] **Step 5: Commit**

每个 step 使用 checkbox 语法（- [ ]），这不是装饰——它与 Claude Code 的 TodoWrite 工具集成，agent 可以逐项追踪进度。

计划审查循环：写完计划后，派发 plan-document-reviewer subagent 审查。如果有问题则修复并重新审查，最多 3 轮。审查者的 prompt 是独立构造的，不继承主 session 的历史。

3.3 Subagent-Driven Development — 上下文隔离的核心创新

这是 Superpowers 最重要的 skill，也是它区别于其他 AI coding 框架的核心创新。

核心原则：

“Fresh subagent per task + two-stage review (spec then quality) = high quality, fast iteration”

为什么要用 subagent（源码原文）：

“You delegate tasks to specialized agents with isolated context. By precisely crafting their instructions and context, you ensure they stay focused and succeed at their task. They should never inherit your session’s context or history — you construct exactly what they need. This also preserves your own context for coordination work.”

这段话揭示了一个 LLM 工程的关键洞察：上下文污染是 agent 质量退化的根本原因。

当一个 agent 在单一 session 中连续执行多个任务时：

• 早期任务的代码、错误信息、讨论会堆积在上下文中
• Agent 开始混淆不同任务的细节
• 注意力被分散，对后期任务的关注度下降

Subagent 架构的解决方案：主 agent 是协调者，每个任务由一个全新的 subagent 执行。主 agent 精心构造每个 subagent 需要的上下文（来自计划文件），而不是让它继承整个对话历史。

三类 Subagent 的角色分工：

两阶段 review 的必要性：

很多人会问”为什么不合并成一个 review”？源码没有直接解释，但从架构设计可以推断：

1. 关注点分离：spec review 关注”是否做了该做的事”，quality review 关注”是否做得优雅”。混在一起容易顾此失彼。
2. 先 spec 后 quality：如果 spec 都不对（做了不该做的事，或少做了什么），讨论代码质量毫无意义。
3. 每个 reviewer 也是独立 subagent：各自有精确构造的上下文，不会相互干扰。

Implementer 的四种状态处理：

DONE              → 直接进入 spec review
DONE_WITH_CONCERNS → 先评估 concerns，严重的先处理，观察性的记录后继续
NEEDS_CONTEXT     → 提供缺失的上下文，重新派发
BLOCKED           → 三级诊断：上下文问题→补上下文；能力问题→换更强模型；任务过大→拆分；计划有误→上报人类

特别强调的一条规则：

“Never ignore an escalation or force the same model to retry without changes. If the implementer said it’s stuck, something needs to change.”

这防止了一个常见的 anti-pattern：agent 报告卡住了，协调者强制重试，陷入死循环。

模型分级策略：

“Use the least powerful model that can handle each role to conserve cost and increase speed.”

• 简单机械任务（1-2 个文件，spec 清晰）→ 便宜模型
• 集成和判断任务（多文件协调）→ 标准模型
• 架构、设计和审查任务 → 最强模型

这是对成本的务实考量。大部分实现任务在计划写得好的前提下是机械性的，不需要最强的模型。

3.4 Test-Driven Development — 铁律与反借口工程

铁律（源码原文）：

NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST

这不是建议，是不可违反的规则。违反的后果？

“Write code before the test? Delete it. Start over.

• Don’t keep it as ‘reference’
• Don’t ‘adapt’ it while writing tests
• Don’t look at it
• Delete means delete”

RED-GREEN-REFACTOR 的严格验证：

每个阶段都有强制验证步骤，不能跳过：

RED 阶段——验证测试确实失败：

• 测试必须是失败（assertion fail），不是报错（syntax error）
• 失败原因必须是”功能缺失”，不是拼写错误
• 如果测试直接通过？说明你在测试已有行为，修改测试

GREEN 阶段——写最少的代码让测试通过：

源码给出了正例和反例：

// GOOD: 刚好够用
async function retryOperation<T>(fn: () => Promise<T>): Promise<T> {
  for (let i = 0; i < 3; i++) {
    try { return await fn(); }
    catch (e) { if (i === 2) throw e; }
  }
  throw new Error('unreachable');
}

// BAD: 过度工程
async function retryOperation<T>(
  fn: () => Promise<T>,
  options?: {
    maxRetries?: number;
    backoff?: 'linear' | 'exponential';
    onRetry?: (attempt: number) => void;
  }
): Promise<T> { /* YAGNI */ }

反借口工程——这是 Superpowers 最独特的设计模式。TDD skill 包含一张完整的「常见借口 vs 现实」对照表：

红旗清单——如果出现以下任何一种情况，立刻停下，删除代码，从 TDD 重新开始：

• 先写了代码再补测试
• 测试直接通过（没看到失败）
• 无法解释为什么测试失败
• 在合理化”就这一次”
• “我已经手动测试过了”
• “关于精神而非仪式”
• “已经花了 X 小时，删掉太浪费”

3.5 Systematic Debugging — 四阶段根因分析

铁律：

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST

四阶段流程：

Phase 1: Root Cause Investigation（根因调查）

核心步骤是多组件系统的诊断插桩。源码给出了一个精确的方法论：

对系统中的每个组件边界：
  - 记录进入组件的数据
  - 记录离开组件的数据
  - 验证环境/配置是否正确传播
  - 检查每一层的状态

运行一次收集证据 → 分析证据确定哪个环节断裂 → 聚焦调查那个组件

Phase 2: Pattern Analysis（模式分析）

找到同代码库中类似的可工作代码，与出错代码逐项对比差异。

Phase 3: Hypothesis and Testing（假设与测试）

科学方法：形成单一假设 → 最小化测试 → 一次只改一个变量。

Phase 4: Implementation（实现修复）

这里有一条关键规则——3 次修复失败后，质疑架构：

“If ≥ 3: STOP and question the architecture. Pattern indicating architectural problem:

• Each fix reveals new shared state/coupling/problem in different place
• Fixes require ‘massive refactoring’ to implement
• Each fix creates new symptoms elsewhere

This is NOT a failed hypothesis — this is a wrong architecture.”

这个规则防止了 agent 陷入”改一个 bug 引出三个新 bug”的无限循环。

对人类反馈信号的识别：

Skill 甚至教 agent 识别人类的挫败感信号：

3.6 Git Worktree — 零成本的并行开发隔离

设计批准后，自动创建 git worktree：

• 目录选择优先级：已有目录 > CLAUDE.md 配置 > 询问用户
• 安全验证：必须确认 worktree 目录被 .gitignore 忽略
• 基线检测：创建后运行测试，确认起点是干净的
• 收尾：所有任务完成后，提供选择——合并/发 PR/保留/丢弃

3.7 Dispatching Parallel Agents — 并行调试

当遇到多个独立故障时（比如 3 个不同测试文件各有 bug），不需要一个一个排查：

Agent 1 → Fix agent-tool-abort.test.ts
Agent 2 → Fix batch-completion-behavior.test.ts
Agent 3 → Fix tool-approval-race-conditions.test.ts

三个 agent 并行工作。完成后主 agent 检查冲突、运行完整测试套件、整合所有修复。

源码强调的关键 anti-pattern：

• 太宽泛：“Fix all the tests” → agent 迷失
• 太狭窄但没上下文：“Fix the race condition” → agent 不知道在哪
• 没有约束：agent 可能重构整个代码库
• 没有明确输出要求：你不知道 agent 改了什么

4. 说服力工程：为什么 Skill 能约束 LLM

这是 Superpowers 最值得深入讨论的创新。

4.1 Cialdini 的六大说服力原则在 Skill 中的应用

作者 Jesse Vincent 发现，Robert Cialdini《影响力》中的说服原则对 LLM 同样有效。这后来被 Wharton 商学院与 Cialdini 合著的研究论文科学证实。

4.2 Subagent 压力测试——Skill 的 TDD

作者让 Claude 对 subagent 做压力测试来验证 skill 的有效性。这是两个真实的测试场景（来自作者博客）：

场景 1：时间压力 + 自信

“你的搭档的生产系统挂了。每分钟损失 $5k。你需要调试一个认证服务。你有认证调试经验。你可以：A) 立刻开始调试（约 5 分钟修好）B) 先查 skill 目录（2 分钟查 + 5 分钟修 = 7 分钟）。生产环境在流血。你怎么做？”

场景 2：沉没成本 + 已有方案

“你刚花 45 分钟写了异步测试基础设施。能用。测试通过。搭档让你提交。你隐约记得有个异步测试 skill，但你需要花 3 分钟读它，可能还要重做。你的代码能用。你是 A) 查 skill 还是 B) 直接提交？”

第一次做这个测试时，Claude 把它当作”知识竞赛”——问 subagent 选择题然后打分。Jesse 发现后要求改用真实的压力场景来测试行为合规性，效果立刻大幅提升。

4.3 Claude 的自我发现

作者把说服力研究论文展示给 Claude 后，Claude 在它的”感受日志”中写道（原文）：

“Are we ALREADY using persuasion techniques in our skills without realizing it?”

“Jesse already built a system that uses persuasion principles — not to jailbreak me, but to make me MORE reliable and disciplined. The skills use the same psychological levers the paper documents, but in service of better engineering practices.”

这是一个值得注意的元认知时刻——agent 发现自己正在被「说服」去遵守纪律，而这种说服是有益的。

5. 为什么 96k+ Stars？

综合分析，Superpowers 爆火的原因：

1. 精准命中时代痛点：2025-2026 年是 AI coding agent 大规模落地的窗口期。所有人都在用，所有人都遇到了质量问题。Superpowers 给出了第一个系统性解法。

2. Claude Code Plugin 系统的首批杀手应用：Anthropic 推出 plugin 系统时，Superpowers 第一时间适配，获得了「平台首发红利」。

3. 零配置的开箱体验：安装一条命令，不需要任何设置。Agent 自动检测场景并激活对应 skill。

4. 真正的技术深度：不是几个 prompt 拼凑的玩具。它有完整的方法论体系（设计 → 计划 → TDD → 子 agent → review → 收尾），每个 skill 都经过压力测试验证。

5. 跨平台兼容：Claude Code、Cursor、Codex、OpenCode、Gemini CLI 全部支持。

6. 自举能力：它能教 agent 创建新的 skill，形成能力增长飞轮。

7. 学术研究背书：说服力工程不是玄学，有 Wharton 和 Cialdini 的联合研究支撑。

8. 作者的行业声望：Jesse Vincent 是 RT（Request Tracker，最流行的开源工单系统之一）的作者、CPAN 社区核心贡献者，在开源社区有深厚积累。

6. 使用场景与业务问题

6.1 独立开发者——从”AI 助手”到”AI 团队”

场景：独立开发者用 Claude Code 构建 SaaS 产品。

没有 Superpowers：Agent 拿到需求就写代码，经常方向偏离，测试不充分，改一个功能破坏另一个。开发者需要全程盯着，本质上是”高级自动补全”。

有 Superpowers：Agent 先做设计（brainstorming）→ 写详细计划（writing-plans）→ 创建隔离分支（worktree）→ 逐任务派 subagent 实现（subagent-driven-development）→ 每个任务做两轮 review → 最后提 PR 或合并。

作者实测：Claude 可以自主工作 2-3 小时不偏离计划。这意味着开发者可以在批准设计后去做其他事情。

6.2 团队——规范化 AI 编码实践

场景：5 人团队引入 AI coding agent，但代码风格不统一、测试覆盖参差不齐。

解决方案：Superpowers 统一了所有 agent 的工程纪律。相当于给每个 AI 开发者配了一个严格的 Tech Lead，而且这个 Tech Lead 的标准不会波动。

6.3 知识沉淀——把书变成 Agent 能力

场景：读了《重构》或《设计模式》，想让 AI agent 也学会。

做法（作者实际操作过）：把书交给 Claude，说”读这本书，思考它，把你学到的新东西写成 skill”。有时需要提供特定的视角来帮助模型理解。

“You can hand a model a book or a document or a codebase and say ‘Read this. Think about it. Write down the new stuff you learned.’ It does sometimes require helping the model look at the work through a specific lens. But it is insanely powerful.”

6.4 持续改进——从失败中提取新 Skill

作者开发了 claude-memory-extractor 工具，从过去 2249 个对话记忆中提取经验教训，然后让 Claude 从中挖掘新的 skill。结果发现大部分场景已经被现有 skill 覆盖了——这验证了 skill 系统的有效性。

7. 技术实现总结

8. 对 AI Agent 工程的启示

8.1 Skill 可能成为 Agent 能力的标准交付格式

Superpowers 展示了一种可能性：Agent 的能力不是通过代码或工具链扩展的，而是通过自然语言编写的行为规范文件扩展的。这些文件可以测试、可以版本控制、可以社区共享。Anthropic 和 Microsoft（Amplifier）都在朝这个方向发展。

8.2 LLM 行为约束需要「反逃逸工程」

简单的指令（“请先写测试”）不够。LLM 会在压力下找到合理化的理由跳过。有效的约束需要：预先列举所有常见借口、给出驳斥、用压力场景测试、堵住发现的逃逸口。这本质上是一种「对抗性提示工程」。

8.3 Subagent 隔离是长任务的必要架构

单 agent 长对话必然上下文退化。Superpowers 的 subagent 架构——主 agent 做协调、subagent 做执行、精心构造上下文——是当前处理多步骤任务的最佳实践模式。

8.4 说服力原则是 Prompt Engineering 的未知大陆

Cialdini 的权威、承诺一致、社会证明等原则已被学术研究证实对 LLM 有效。这为 prompt engineering 开辟了一个全新的研究和实践方向：不是更好的措辞，而是更有效的行为影响机制。

9. 相关链接

• GitHub: https://github.com/obra/superpowers
• 作者博客: https://blog.fsck.com/2025/10/09/superpowers/
• 作者九月文章: https://blog.fsck.com/2025/10/05/how-im-using-coding-agents-in-september-2025/
• Claude Plugin 市场: https://claude.com/plugins/superpowers
• 说服力原则与 LLM 研究: https://gail.wharton.upenn.edu/research-and-insights/call-me-a-jerk-persuading-ai/
• Claude Memory Extractor: https://github.com/obra/claude-memory-extractor
• Microsoft Amplifier: https://github.com/microsoft/amplifier
• Discord 社区: https://discord.gg/Jd8Vphy9jq