AI 编程的＂元框架＂:Superpowers 怎样让 Agent 自动跑几小时不出轨

198K Stars，Shell 脚本写成的 AI 编程方法论，为什么比很多重型框架都管用？

痛点：你的 Agent 为什么会"跑偏"

用 AI 编程，最崩溃的时刻不是 AI 写不出代码——而是它写了一堆，然后你发现：

• • 它加的功能根本不是你想要的
• • 它自己生成的东西它自己没测
• • 代码风格跟项目其他部分完全不一致
• • 一个人肉 code review 下来，发现 80% 要重写

问题不在 AI，在于没有"约束框架"。

没有约束的 AI Agent = 没有方向盘的汽车。油门前脚踩下去，后脚就冲进了沟里。

Superpowers 就是那个方向盘。

一、Superpowers 是什么

Superpowers 是由 Jesse Vincent（@obra，GitHub 198K Stars 的顶级开源作者）创建的AI 编程方法论框架，本质上是一套可组合的 Skills（技能模块）+ 触发规则。

官方定义：
"Superpowers is a complete software development methodology for your coding agents, built on top of a set of composable skills and some initial instructions that make sure your agent uses them."

它用 Shell 脚本写成，核心不是代码，是工作流程的编排逻辑。支持 Claude Code、Codex CLI、Cursor、Copilot 等 8 种主流 AI 编程工具。

为什么是 Shell？ 因为 Shell 是所有编程环境里最通用的"胶水"，不依赖特定语言生态，装上就能用。

二、核心架构：Skills 触发系统

Superpowers 的精髓在于"技能自动触发"，不是你来告诉 Agent 该用什么技能，而是 Agent 根据上下文自动选择对应技能。

技能分类地图

Superpowers Skills Library
│
├── Testing（测试）
│   └── test-driven-development  ← RED-GREEN-REFACTOR 全自动循环
│
├── Debugging（调试）
│   ├── systematic-debugging       ← 4 阶段根因分析
│   └── verification-before-completion ← 验证真的修好了
│
├── Collaboration（协作）
│   ├── brainstorming             ← 提问式需求澄清
│   ├── writing-plans             ← 任务拆分（2-5 分钟/个）
│   ├── executing-plans            ← 批量执行 + 检查点
│   ├── dispatching-parallel-agents ← 并行子 Agent
│   ├── requesting-code-review    ← 质量门禁
│   ├── receiving-code-review     ← 反馈处理
│   ├── using-git-worktrees       ← 并行分支隔离
│   ├── finishing-a-development-branch ← 合并决策
│   └── subagent-driven-development ← ⭐ 核心引擎
│
└── Meta（技能创作）
    ├── writing-skills            ← 教你写新技能
    └── using-superpowers         ← 入门引导

触发规则：不是调用，是自动激活

传统 Agent：你 → 告诉它做什么 → 它执行

Superpowers：你在项目里装了它 → Agent 自动识别当前阶段 → 自动触发对应技能

你："帮我加个用户登录功能"
       ↓
Agent 检测到：这是新功能开发
       ↓
自动触发 brainstorming（需求澄清）
       ↓
你确认需求后
       ↓
自动触发 writing-plans（任务拆分）
       ↓
你批准计划后
       ↓
自动触发 subagent-driven-development（执行 + 两阶段审查）
       ↓
完成后
       ↓
自动触发 finishing-a-development-branch（合并决策）

不需要你一句一句指挥，Agent 自己知道现在该干什么。

三、subagent-driven-development：核心引擎拆解

这是 Superpowers 最关键的一个 Skill，也是理解它为什么能让 Agent"跑几小时不出轨"的关键。

设计动机

Jesse Vincent 说过一句话：

"No agent should verify its own work. Fresh context finds what you miss."

自己写的代码自己审查，永远有盲区。

两阶段审查机制

当你对 Agent 说"go"之后，subagent-driven-development 会：

┌─────────────────────────────────────────────────┐
│           Task N: 实现用户登录                   │
└──────────────────┬──────────────────────────────┘
                   │
         ┌─────────▼──────────┐
         │  Stage 1: Spec     │  ← 新的独立 subagent
         │  Compliance Review │    检查实现是否满足 SPEC
         └─────────┬──────────┘
                   │ PASS
         ┌─────────▼──────────┐
         │  Stage 2: Code     │  ← 另一个新的独立 subagent
         │  Quality Review    │    检查代码质量（安全/风格/逻辑）
         └─────────┬──────────┘
                   │ PASS
         ┌─────────▼──────────┐
         │    Task N+1 继续   │
         └────────────────────┘

每个任务结束后，都会有一个全新的 subagent 来审查——不是原来那个。

自动修复循环

如果审查发现问题了？

Reviewer Agent 发现 2 个问题
         ↓
修复 Agent（第三个独立 Agent）收到问题列表
         ↓
修复 Agent 只修这 2 个问题，不改别的
         ↓
重新跑两阶段审查
         ↓
通过 → 继续下一个任务
失败 → 再来一轮（最多 2 次）
         ↓
2 次还失败 → 升级人工处理

最多自动修复 2 轮，2 轮还不行的，直接让人来看。

这样做的好处：不会无限循环修复，也不会让错误累积到最后一个任务才暴露。

四、七步工作流全景图

┌──────────────────────────────────────────────────────────┐
│                     SUPERPOWERS 工作流                     │
└──────────────────────────────────────────────────────────┘

  ① brainstorming          ← "你想做什么？"
  ② using-git-worktrees    ← 创建隔离分支环境
  ③ writing-plans          ← 拆成 2-5 分钟的小任务
  ④ subagent-driven-dev    ← 执行 + 两阶段审查 ⭐核心
  ⑤ test-driven-development ← 红绿重构循环
  ⑥ requesting-code-review ← 关键节点质量门禁
  ⑦ finishing-a-branch     ← 合并/PR/丢弃决策

每一步的触发条件

五、实战案例：给项目加一个功能

场景： 你想让 Agent 给博客系统加一个"文章收藏"功能。

第一步：brainstorming（需求澄清）

你："帮我加一个文章收藏功能"
Agent：自动触发 brainstorming

Agent 提问：
"收藏是针对登录用户还是游客？
  一个用户能收藏同一篇文章多次吗？
  收藏列表需要分页吗？
  需要支持取消收藏吗？"
你：回答这些问题
Agent：生成设计文档，你确认

第二步：任务拆分

Writing-plans 输出示例：

## Task 1: 数据库迁移（3 分钟）
文件: db/migrations/004_add_favorites.sql
- 创建 favorites 表
- 添加 user_id, post_id, created_at 字段
- 验证迁移成功

## Task 2: API 端点（4 分钟）
文件: src/api/favorites.py
- POST /favorites — 创建收藏
- DELETE /favorites/:id — 取消收藏
- GET /favorites — 获取当前用户收藏列表

## Task 3: 前端收藏按钮（5 分钟）
文件: src/components/FavoriteButton.tsx
- 点击切换收藏状态
- 显示收藏数量

## Task 4: 测试（3 分钟）
文件: tests/test_favorites.py
- 集成测试：收藏/取消收藏流程
- 边界测试：重复收藏、游客操作

每个任务 2-5 分钟，任务之间有检查点。你随时可以中断、审查、从任意任务继续。

第三步：自动执行 + 审查

Agent 开始执行 Task 1
         ↓
Task 1 完成 → 新 Subagent（Spec 审查）→ 检查是否满足 SPEC
                              ↓ PASS
                         新 Subagent（代码审查）→ 检查质量问题
                              ↓ PASS
         ↓
Agent 开始执行 Task 2
         ↓
Task 2 完成 → 审查循环...
         ↓
所有任务完成
         ↓
finishing-a-branch：显示测试结果，问你"合并/PR/保留/丢弃？"

六、哲学背后：为什么这样设计

Superpowers 的四条核心哲学：

Test-Driven Development    →  写测试在写代码之前，永远
Systematic over ad-hoc     →  流程优于猜测，有章法才能规模化
Complexity reduction       →  简单是首要目标，不要过度设计
Evidence over claims       →  验证优于声明，不信说的信跑的

这四条不是 Jesse 拍脑袋写的，是几十年软件工程最佳实践的沉淀。

每一条都有具体机制对应：

• • TDD → test-driven-development Skill 强制执行
• • Systematic → 七步工作流自动串联
• • Complexity reduction → 每个任务控制在 2-5 分钟，不给复杂性留空间
• • Evidence → 两阶段审查是"证据"，不是"感觉"

七、怎么安装和使用

安装（以 Claude Code 为例）

# 方式一：官方市场
/plugin install superpowers@claude-plugins-official

# 方式二：Superpowers 市场（包含其他插件）
/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplace

在项目里激活

装好后，进入你的项目目录启动 Claude Code：

cd your-project
claude

Agent 会自动识别 Superpowers 已安装，输出里能看到 skills 列表。之后你的每句指令都会触发对应技能。

查看所有可用技能

/help superpowers

七、Superpowers 的局限与改进方向

现有限制

改进方向

1. 审查 Agent 专业化

当前两阶段审查是通用审查，可以拆成专一角色：

• • 专门的安全审查 Agent（只扫安全漏洞）
• • 专门的风格审查 Agent（只扫代码风格）
• • 专门的架构审查 Agent（只扫设计模式）

2. 状态持久化

当前任务状态存在 .superpowers/ 目录，可以引入 SQLite 或 JSON 文件记录每次运行的检查点，支持断点续跑。

3. Windows 兼容层

用 Python 重写 using-git-worktrees，通过 git worktree 的 HTTP API 或 WSL 兼容层支持 Windows。

4. 审查结果可追溯

每次审查结果应该生成独立的 review-N.md 文件存档，方便回溯："这个 Bug 是哪个任务引入的？"

九、三者横评：Superpowers / Spec Kit / OpenSpec

一句话选型：

• • 想让 Agent 自主跑几小时 → Superpowers
• • 文档规范优先、团队协作 → Spec Kit
• • 快速上手、轻量灵活 → OpenSpec

下期预告

《GitHub 官方 Spec Kit：怎样用 constitution→spec→plan→tasks→implement 把需求变成可交付代码》

本文首发于 Hant.AI极客 微信公众号，转载授权请联系作者。