[TOC]

概述

你有没有遇到过这种情况：让 AI Agent 帮你写代码，它二话不说就开干，写出来的东西要么偏离需求，要么结构混乱，改来改去反而越改越烂？Superpowers 就是来治这个毛病的。

Superpowers 是一套面向 AI 编码 Agent 的软件开发方法论。它不是一个代码框架，也不是一个 SDK，而是一组用 Markdown 编写的「技能文件」，能让 Claude Code、Cursor、Codex、Gemini CLI 等主流 AI 编码工具按照工程纪律来干活。

这是本系列的第一篇，带你从全局视角看清 Superpowers 到底在做什么，以及它为什么值得你花时间了解。

AI Agent 写代码的三个老毛病

在聊 Superpowers 之前，先看看没有它的时候，AI Agent 通常是怎么工作的。

毛病一：拿到需求就开写，不验证不设计。 你说「帮我加个用户设置页面」，Agent 立刻开始噼里啪啦写 React 组件，压根不问你要什么字段、状态怎么管理、和现有路由怎么集成。写完一看，一半需要推倒重来。

毛病二：调试靠猜，改一行试一下。 遇到 bug，Agent 的第一反应是「让我试试把这行改了」。不看日志、不做假设、不缩小范围，就是反复猜。运气好能蒙对，运气不好越改越乱。

毛病三：上下文越来越脏。 一个会话里做了太多事，之前的代码片段、错误信息、废弃方案全堆在上下文里。Agent 开始把早就放弃的思路混进新代码，产出质量断崖式下跌。

Superpowers 的创建者 Jesse Vincent（obra）把这类行为总结为一句话：Agent 在做「reactive code generation」（被动式代码生成）——收到指令就反应，缺乏系统性工程思维。

Superpowers 是什么

简单说：Superpowers 把 AI 编码 Agent 从「随意的代码生成器」改造成「有纪律的工程伙伴」。

实现方式可能比你想的朴素——就是一堆 Markdown 文件。每个文件叫一个 Skill（技能），存放在 skills/ 目录下，通过 YAML 头部声明名称和触发条件，正文写的是 Agent 必须遵循的工作流程。

superpowers/
├── skills/
│   ├── using-superpowers/     # 元技能：建立规则的规则
│   │   └── SKILL.md
│   ├── brainstorming/         # 头脑风暴技能
│   │   └── SKILL.md
│   ├── writing-plans/         # 写实现计划
│   │   └── SKILL.md
│   ├── subagent-driven-development/  # 子代理驱动开发
│   │   └── SKILL.md
│   ├── test-driven-development/      # 测试驱动开发
│   │   └── SKILL.md
│   └── ...更多技能
├── hooks/                     # 会话启动钩子
│   ├── hooks.json
│   └── session-start
└── .claude-plugin/            # 平台注册文件
    └── plugin.json

但别被「Markdown 文件」这个词骗了——这些技能文件是强制要求，不是建议。Superpowers 通过一个叫 using-superpowers 的元技能，在每次会话启动时注入规则，告诉 Agent：「如果有哪怕 1% 的可能性某个技能适用，你就必须先调用它，再做任何事情。」

一句话概括设计意图：工作流不是可选建议，而是不可绕过的纪律。

四条核心原则

所有技能围绕四条原则展开：

原则	对应技能	解决的问题
测试驱动开发	test-driven-development	强制 RED-GREEN-REFACTOR 循环：先写失败测试，再写最少代码让它通过，最后重构
系统化调试	systematic-debugging	用 4 阶段结构化流程替代「猜一下试一下」：收集证据 → 形成假设 → 验证假设 → 修复
复杂度控制	complexity-reduction	强调 YAGNI（你不会需要它）和 DRY（别重复自己），防止 Agent 过度工程化
工作区隔离	using-git-worktrees	所有实现工作在独立的 git worktree 中进行，保持主分支干净，防止上下文污染

每条原则都对应一个 Skill 文件，里面写死了 Agent 要走的步骤、不准跳的检查点，甚至列出了 Agent 常见的偷懒借口和对应纠正。

六大平台支持

同一套技能文件可以在六个 AI 编码环境下运行：

平台	安装方式	子代理支持
Claude Code	插件市场（.claude-plugin/plugin.json）	原生 Task 工具
Cursor	hooks 注入（hooks-cursor.json + polyglot 包装器）	有限
OpenCode	JavaScript 插件（.opencode/plugins/superpowers.js）	原生支持
Codex	镜像同步（sync-to-codex-plugin）	spawn_agent
Gemini CLI	扩展安装（gemini extensions install）	@generalist 语法
Copilot CLI	插件市场	task 工具

不同平台的工具名不一样（比如 Claude Code 叫 Skill，Gemini CLI 叫 activate_skill，Codex 叫原生发现），但 Superpowers 内部维护了一套工具映射表，让技能文件可以用统一的 Claude Code 工具名编写，运行时自动翻译成当前平台的等价工具。

关键概念速览

后续文章会逐个深入，这里先把几个概念理清楚。

Skill（技能）

一个 Skill 就是一个文件夹，里面放着 SKILL.md 和可选的辅助文件。SKILL.md 分两部分：

---
name: brainstorming
description: "Use when the user wants to design, plan, or architect something..."
---
# brainstorming 技能正文
...（Agent 必须遵循的详细流程）

• YAML 头部（frontmatter）：name 和 description，用于技能发现
• Markdown 正文：具体的工作流程、检查清单、常见陷阱

和普通文档的区别在于：Skill 不是放在那儿等人翻的参考资料，Agent 每次做事前都要主动检查有没有对应的 Skill，找到了就必须照着做。

using-superpowers 元技能

这个技能比较特殊，它管的不是某个具体任务，而是建立规则的规则。每次会话启动时通过 session-start 钩子自动注入上下文，负责：

• 建立 1% 规则（见下文）
• 定义指令优先级：用户指令 > Superpowers 技能 > 系统提示词
• 设立「Red Flag 合理化拦截表」，防止 Agent 找借口跳过技能检查
• 区分「流程技能优先于实现技能」的优先级

1% 规则

整套系统最硬的一条规矩：哪怕只有 1% 的可能性某个技能和当前任务沾边，Agent 就必须先调 Skill 工具检查，然后才能干别的——包括回答问题和翻代码。

元技能里还列了一张「Red Flag 表」，把 Agent 常见的偷懒借口逐条拦住：

Agent 的内心想法	正确做法
「这只是个简单问题」	问题也是任务，先查技能
「我先看看代码再说」	技能告诉你怎么看代码，先查
「这个技能我记得」	技能会更新，读最新版本
「这个技能太重了，没必要」	简单事情会变复杂，用上不会亏
「我先快速做完这一步」	做任何事之前先检查

三段式工作流

从需求到交付，走一条固定的三段流水线：

┌─────────────┐     ┌──────────────┐     ┌─────────────────────────┐
│ brainstorming│────▶│ writing-plans│────▶│ subagent-driven-dev     │
│  （设计）    │     │  （计划）     │     │  （实现）                │
│             │     │             │     │                         │
│ HARD-GATE:  │     │ 禁止占位符   │     │ 每任务一个新鲜子代理      │
│ 设计未批准   │     │ 任务 2-5 分钟 │     │ 两阶段审查：             │
│ 不准写代码   │     │ 粒度         │     │  ① 规格合规 → ② 代码质量 │
└─────────────┘     └──────────────┘     └─────────────────────────┘

阶段一：头脑风暴。 Agent 必须先探索项目上下文、问清需求、提出 2-3 个方案和取舍分析，然后写一份设计文档交给你审核。文档没通过之前，绝对不允许写一行实现代码。这就是所谓的 HARD-GATE（硬门控）。

阶段二：写实现计划。 设计批准后，Agent 把工作拆成若干个小任务（每个 2-5 分钟粒度），列出每个任务涉及的文件、需要的代码、验证方法。计划里不允许出现 “TBD”、“implement later” 这类占位符。

阶段三：实现。 首选方式是 Subagent-Driven Development（SDD）——为计划中的每个任务启动一个全新的子代理。子代理上下文干净，不会被之前的工作污染。做完后还有两轮审查：先查是否符合规格，再查代码质量。

一分钟看懂完整工作流

举个例子。你对 Agent 说：「帮我给这个 CLI 工具加上配置文件支持。」

没装 Superpowers，Agent 八成直接开写 config.js 和命令行参数解析。

装了之后，走的是这条路：

你：帮我给 CLI 工具加上配置文件支持

Agent（检查 1% 规则）：
  → 调用 Skill 工具，发现 brainstorming 技能适用

Agent（进入 brainstorming）：
  → 探索现有代码结构
  → 问你：配置文件用 JSON 还是 YAML？支不支持环境变量覆盖？
  → 提出两个方案，分析取舍
  → 写设计文档，等你审核

你：方案 A 可以，批准

Agent（进入 writing-plans）：
  → 把工作拆成 4 个小任务：
    Task 1: 添加配置文件解析模块
    Task 2: 修改 CLI 入口集成配置
    Task 3: 添加默认配置和配置验证
    Task 4: 写单元测试和集成测试

Agent（进入 SDD）：
  → 为 Task 1 启动子代理 → 实现 → 自审 → 提交
  → 规格合规审查 → 通过
  → 代码质量审查 → 通过
  → 为 Task 2 启动新子代理...（循环）

Agent：全部任务完成，4/4 通过审查

全程没有一次「上来就写代码」。设计不过关不写计划，计划不过关不写代码，代码不过审查不算完成。

Skill 和你可能知道的几个概念有什么区别

概念	特点	和 Superpowers Skill 的区别
提示词模板	一次性文本，塞进对话里	Skill 是可发现、可调用、可测试的结构化文档，有 frontmatter 和触发条件
CLAUDE.md / AGENTS.md	项目级指令文件	Skill 是跨项目通用的工作流，优先级低于项目指令
MCP Server	给 Agent 提供外部工具/数据	Skill 不提供工具，而是告诉 Agent 怎么用已有工具
Agent Skills 标准	Anthropic 官方的技能规范	Superpowers 是独立方法论，有自己的强制协议（1% 规则），但 SKILL.md 格式兼容

总结

Superpowers 干的事情不复杂：用一堆 Markdown 文件给 AI Agent 立规矩。1% 规则逼着 Agent 做任何事之前先查技能，三段式流水线逼着它走完「设计 → 计划 → 实现」才能交付，四条原则（TDD、系统调试、复杂度控制、worktree 隔离）把工程纪律落到具体步骤上。六个平台都能用，靠的是一套工具映射表做翻译。

下一篇动手装——在你的平台上跑起来，看看 1% 规则在真实会话中是什么体验。

参考资料

• obra/superpowers README — 项目主页与安装指南
• DeepWiki: Overview — 项目全景
• DeepWiki: Core Concepts — 核心概念定义（Skill 结构、1% 规则、优先级体系）
• DeepWiki: Complete Workflow Pipeline — 三段式流水线详解
• DeepWiki: Key Skills Reference — 核心技能速查