Superpowers 方法论提炼 — 从洞察到实践操作指南

基于对 Superpowers 项目的深度分析，提炼可落地的工程方法论与个人实践操作指南。

一、Superpowers 核心洞察总结

Superpowers 是一套完整的 AI 编码代理软件开发方法论，由可组合的 Skills（技能）和初始指令构成。其核心洞察是：AI 编码代理不应该直接写代码，而应该遵循一套严格的人类协作式工程流程。

架构总览

用户意图 → 头脑风暴(Brainstorming) → 设计文档(Spec) → 实施计划(Plan) → 子代理驱动开发(SDD) → 代码审查(Review) → 完成分支(Finish)

14 个核心技能及其定位

二、提炼的方法论（5 大核心原则）

原则 1：意图先行，设计必审（Intent-First, Design-Approved）

洞察： 代理不应直接跳入写代码。第一步是理解用户真正想做什么。

方法论：

• 任何项目（无论多简单）都必须先经过设计阶段
• 反模式：“这太简单了不需要设计” — 简单项目恰恰是未审视假设造成最多浪费的地方
• 设计可以很短（几句话），但必须呈现并获得用户批准
• 硬门控（HARD-GATE）：在用户批准设计前，禁止任何实现动作

原则 2：任务原子化，独立可测（Atomic Tasks, Independently Testable）

洞察： 计划必须细到"一个热情但判断力差、没有项目上下文、厌恶测试的初级工程师"也能独立完成。

方法论：

• 任务是最小可独立测试的单元
• 折叠 setup、配置、脚手架到需要它们的任务中
• 仅在审查者可以有意义地拒绝一个任务而批准相邻任务时才拆分
• 每个任务产出可独立测试的交付物
• 遵循 YAGNI（你不需要它）和 DRY（不要重复自己）

原则 3：子代理隔离，上下文纯净（Subagent Isolation, Clean Context）

洞察： 主代理是协调者，不是实现者。子代理不应继承主代理的会话历史。

方法论：

• 每个任务派发一个全新子代理，精确构造其所需上下文
• 子代理永远不继承主代理的会话历史或上下文
• 任务完成后子代理上下文即丢弃，主代理只接收审查结果
• 这保护了主代理的上下文窗口用于协调工作
• 连续执行：不暂停询问用户，除非真正被阻塞

原则 4：铁律不可违，证据优先（Iron Laws, Evidence-First）

洞察： 三个不可违反的铁律构成了质量底线。

方法论 — 三大铁律：

1. TDD 铁律： 没有失败测试，不写生产代码。先写代码再写测试？删掉重来。
2. 调试铁律： 没有根因调查，不提修复方案。症状修复就是失败。
3. 验证铁律： 没有新鲜验证证据，不声称完成。"应该可以了"不是证据。

反理性化表： 每个铁律都配有详细的"借口 vs 现实"对照表，防止代理自我合理化绕过规则。

原则 5：技能即代码，TDD 验证（Skills Are Code, TDD-Validated）

洞察： 技能文档不是散文 — 它是塑造代理行为的代码，必须用 TDD 方法开发和验证。

方法论：

• 写压力场景（测试）→ 看代理在没有技能时失败（RED）→ 写技能文档 → 验证代理合规（GREEN）→ 找新漏洞并修复（REFACTOR）
• 如果没有看到代理在没有技能时失败，你不知道技能是否教了正确的东西
• 技能变更需要对抗性压力测试和评估证据

三、你的具体实践操作指南

第一步：安装 Superpowers 到你的编码代理

根据你使用的编码代理，选择对应的安装方式：

第二步：理解自动触发机制

关键： 你不需要手动做任何事。Superpowers 的技能会自动触发。

• 当你说"Let’s build X"，brainstorming 技能自动触发
• 当你说"Fix this bug"，systematic-debugging 技能自动触发
• 技能在代理看到你开始构建东西的那一刻就介入

验证安装成功： 打开一个新会话，发送 Let's make a react todo list。如果 brainstorming 在写任何代码前自动触发，安装成功。

第三步：按流程使用 — 你的日常操作手册

场景 A：开发新功能

你：我想做一个用户认证系统

代理自动执行：
1. [brainstorming] 先不写代码，问你：
   - 需要支持哪些登录方式？
   - 有没有现有的用户模型？
   - 安全要求是什么？
2. [brainstorming] 提出 2-3 个方案及权衡
3. [brainstorming] 呈现设计，等你批准
4. [writing-plans] 拆解为 bite-sized 任务
5. [subagent-driven-development] 逐任务派发子代理实现
6. [requesting-code-review] 每个任务完成后自动审查
7. [verification-before-completion] 全部验证通过才声称完成
8. [finishing-a-development-branch] 呈现合并/PR/保留选项

你只需要：回答问题、批准设计、说"go"

场景 B：修复 Bug

你：这个登录页面点击提交后没有反应

代理自动执行：
1. [systematic-debugging] Phase 1：根因调查
   - 读取错误信息
   - 复现问题
   - 检查最近变更
   - 多组件系统：逐层加诊断
2. [systematic-debugging] Phase 2：假设验证
3. [systematic-debugging] Phase 3：修复实施（用 TDD）
4. [systematic-debugging] Phase 4：防御加固
5. [verification-before-completion] 验证修复

你只需要：描述问题，代理会系统性地找到根因

场景 C：审查代码

你：帮我审查一下这个 PR

代理执行：
1. [requesting-code-review] 派发独立审查子代理
2. 审查子代理返回：Critical / Important / Minor 分级
3. [receiving-code-review] 你看到的是技术评估，不是表演性赞美
4. Critical 立即修，Important 继续前修，Minor 记录后续

第四步：掌握铁律 — 你作为人类的监督要点

作为人类伙伴，你需要知道代理可能试图绕过规则的信号：

第五步：创建你自己的技能

当你发现反复出现的模式时，用 Superpowers 的 writing-skills 方法论创建自己的技能：

1. 识别模式：某个技巧不是直觉上显而易见的，且会跨项目复用
2. 写压力场景：构造一个没有技能时代理会失败的测试
3. 运行基线：看代理在没有技能时如何失败，记录它的合理化借口
4. 写技能文档：针对那些具体的失败行为编写 SKILL.md
5. 验证合规：确认有技能时代理行为改变
6. 迭代加固：找新的合理化借口 → 堵住 → 重新验证

技能文件结构：

skills/
  my-skill/
    SKILL.md          # 核心文档（YAML frontmatter + Markdown body）
    references/       # 参考文档
    scripts/          # 辅助脚本
    templates/        # 模板文件

第六步：适配到你的项目 — 实操检查清单

• [ ] 安装 Superpowers 到你常用的编码代理（第一步的表格）
• [ ] 验证自动触发：新会话发送简单构建请求，确认 brainstorming 先于代码触发
• [ ] 信任流程：不要催促代理跳过设计阶段，这是最核心的价值
• [ ] 监督铁律：当代理试图绕过规则时，参照第四步的表格纠正
• [ ] 积累技能：当你发现项目特有的模式时，按第五步创建自定义技能
• [ ] 审查而非信任：代理说"完成"时，要求看验证证据（测试输出、构建结果）

四、Superpowers 设计理念深度解读

1. 行为塑造 > 功能堆叠

Superpowers 不提供新功能，它塑造代理的行为模式。技能是"行为代码"——不是描述代理能做什么，而是规定代理应该怎么做。这就是为什么技能变更需要评估证据——你修改的是行为逻辑，不是文档。

2. 铁律 + 反合理化 = 行为保证

每条铁律都配有详细的"借口 vs 现实"对照表。这不是装饰——这是核心设计。AI 代理最擅长合理化绕过规则，反合理化表是专门设计的防御机制。

3. 上下文隔离 = 质量保证

子代理驱动开发的核心不是"并行加速"，而是"上下文纯净"。每个任务在一个干净的上下文中实现，不受之前任务的历史污染。主代理保留协调能力，子代理专注执行。

4. 人类是决策者，代理是执行者

整个流程中，人类只在关键决策点介入：批准设计、选择方案、确认合并。其余时间代理自主执行。这不是减少人类参与，而是让人类参与集中在高价值决策上。

5. 零依赖哲学

Superpowers 是零依赖插件。所有核心逻辑都是纯文本技能文档 + 钩子脚本。这使得它可以跨平台（Claude Code、Cursor、Codex、Gemini 等）运行，无需任何外部工具或服务。

五、与华为云/码道生态的映射参考

六、华为云/码道用户的专属实践路径

针对使用华为云 CodeArts（码道）的用户，以下是直接可操作的落地路径。

路径 A：在码道中应用 Superpowers 方法论

1. 码道技能开发遵循"意图先行"原则

   • 创建技能前，先用 brainstorming 方式明确：这个技能解决什么问题？目标用户是谁？成功标准是什么？
   • 不要直接写 SKILL.md，先写设计文档（哪怕只有 5 行）

2. 技能拆解遵循"任务原子化"原则

   • 一个技能只做一件事，做好一件事
   • 如果技能描述中出现"和"、“以及”、“并且”，考虑拆分
   • 每个技能必须有可独立验证的交付物

3. 技能验证遵循"铁律"原则

   • 技能写完后，必须用对抗性场景测试
   • 没有看到技能在没有指导时失败，你不知道技能是否有效
   • 验证证据 = 实际运行结果，不是"看起来没问题"

路径 B：将 Superpowers 技能模式迁移到 Hermes Agent

Hermes Agent 已内置类似的技能体系，可以直接映射：

路径 C：日常开发中的实操检查清单

每次开始新任务时：

□ 我是否先描述了意图，而不是直接要求写代码？
□ 我是否批准了设计，然后才让代理开始实现？
□ 代理说"完成"时，我是否要求了验证证据？
□ 代理跳过步骤时，我是否纠正了它？
□ 我是否在积累可复用的技能/模式？