编程 Superpowers 深度解析：当 AI 编程 Agent 终于学会「按规矩办事」——从技能框架到 TDD 强制循环的完全指南（2026）

2026-06-01 12:25:40 +0800 CST views 3

Superpowers 深度解析：当 AI 编程 Agent 终于学会"按规矩办事"——从技能框架到 TDD 强制循环的完全指南（2026）

小编语：AI 写代码不稀奇，但 AI 能像资深工程师一样先想清楚再动手、先写测试再写实现、写完还要自己 Review？obra/superpowers 正在把这套工程纪律"硬编码"进每一个 Coding Agent 的灵魂里。20 万星、席卷 GitHub Trending 榜首——它凭什么？

问题来了：AI 编程的"实习生困境"
Superpowers 是什么？一句话 + 一张图看懂
核心理念：工程纪律 > 码力爆棚
架构解析：Skill 是如何"注入" Agent 行为的？
14 个核心 Skills 逐个数：哪一个是你的真命天子？
TDD 强制循环：让 AI 先红灯、再绿灯、最后重构
代码实战：用 Superpowers 开发一个 REST API
多 Agent 协作：Git Worktree 隔离 + 子 Agent 分工
接入指南：Claude Code、Codex、Cursor 全平台适配
与其它方案的对比：Superpowers vs Aider vase vs OpenSpec
实战踩坑与最佳实践
底层原理：为什么一套 Markdown Skills 能改变 Agent 行为？
社区生态与未来路线图
总结与展望：AI 编程的"工程化元年"已经到来

问题来了：AI 编程的"实习生困境"

你肯定遇到过这种情况：

你：帮我写一个用户登录接口，要支持 JWT，要有单元测试。

AI（实习生模式）：好嘞！
（30 秒后）
AI：写完了！你看一下～

你：……你测试在哪？
AI：哦对，我补一下……（开始胡乱写 assert True == True）

这不是 AI 的智力问题，而是缺少工程约束的问题。

传统 AI 辅助开发的致命缺陷

阶段	实习生式 AI	资深工程师
需求理解	直接开干	先问清楚边界、异常、性能要求
方案设计	无	画架构图、选技术栈、评估风险
代码实现	一口气写几百行	小步迭代、每步可验证
测试	补作业式写测试	TDD：测试先行，驱动设计
提交前	直接 push	自我 Review、跑 CI、检查 Edge Case
完成后	任务结束	写文档、复盘、记录决策原因

Superpowers 做的，就是把右侧的"资深工程师行为模式"，变成左侧 AI 的默认路径。

Superpowers 是什么？一句话 + 一张图看懂

项目地址：https://github.com/obra/superpowers
作者：Jesse Vincent（开源老炮，曾主导多个基础设施项目）
当前 Stars：~198,582（截至 2026 年 5 月，单日最高新增 1,422 星）
适用平台：Claude Code、OpenAI Codex、Cursor、OpenCode 等所有主流 Coding Agent

一句话定义

Superpowers 是一套给 AI Coding Agent 准备的"完整软件开发方法论"，通过 20+ 个可自动触发的 Skill（技能），让 AI 从"会写代码"升级为"懂软件工程"。

它不是模型微调，不是prompt工程的黑魔法，而是一套放在项目目录里的 Markdown 文件——但正是这些文件，让 Agent 在每次动手前，都不得不"三思而行"。

核心架构（文字示意图）

你的问题 / 需求
      │
      ▼
┌─────────────────────────────┐
│   Coding Agent (Claude Code / Codex / Cursor)             │
│                                                             │
│   ┌───────────────┐    │
│   │  Superpowers Skill 注入层                           │    │
│   │  (skills/ 目录下的 14+ 个 Markdown 技能文件)      │    │
│   │                                                     │    │
│   │  clarify-interesting-questions → 需求澄清           │    │
│   │  create-initial-plan      → 初始方案设计           │    │
│   │  create-implementation-plan → 实现计划拆解         │    │
│   │  tdd-cycle                  → TDD 红绿重构循环     │    │
│   │  request-code-review        → 强制代码审查         │    │
│   │  worktree-isolation        → Git Worktree 隔离     │    │
│   │  ...（共 14+ 个 Skills）                          │    │
│   └───────────────┘    │
│                                                             │
│   每个 Skill = 一组强制执行的工程纪律                       │
│   用 Markdown 写成的"高级工程师灵魂注入器"                  │
└─────────────────────────────┘
      │
      ▼
  符合工程规范的代码 + 测试 + 文档 + Git 提交

核心理念：工程纪律 > 码力爆棚

Superpowers 的核心理念可以浓缩为一句话：

"AI 不缺写代码的能力，缺的是知道『什么时候不该写代码』的判断力。"

三大支柱

1. 先想清楚，再动手（Planning-First）

传统 AI 编程：

用户提需求 → AI 立刻写代码 → 边写边改 → 最后发现理解错了

Superpowers 强制流程：

用户提需求
  → clarify-interesting-questions（反向提问，澄清需求）
  → create-initial-plan（形成设计方案，等待人类确认）
  → 人类确认后
  → create-implementation-plan（拆解成可逐条执行的小任务）
  → 才开始写代码

2. 测试先行，实现后行（TDD as First-Class Citizen）

Superpowers 把 TDD 从"建议"升级为"强制"：

每个功能开发循环：
  1. 写一个新的失败测试（RED）
  2. 写最少量的代码让测试通过（GREEN）
  3. 重构（REFACTOR）
  4. 重复，直到所有测试用例通过

AI 无法跳过测试直接写实现——Skill 文件里明确规定了执行顺序，Agent 会严格遵循。

3. 隔离开发，协作合并（Isolation + Review）

使用 Git Worktree 实现多个子 Agent 并行开发，互不干扰：

main 分支（受保护）
  ├── worktree/feature-a  → 子 Agent A 开发功能 A
  ├── worktree/feature-b  → 子 Agent B 开发功能 B
  └── worktree/feature-c  → 子 Agent C 开发功能 C

每个 worktree 独立：
  - 独立的文件副本
  - 独立的 Git 历史
  - 独立的测试运行
  - 完成后通过 request-code-review Skill 自动触发 Code Review

架构解析：Skill 是如何"注入" Agent 行为的？

这是 Superpowers 最精妙的设计：它不需要修改 Agent 的底层代码，而是利用 Agent 自身的"读取项目文件"能力，将工程规范"注入"到上下文里。

注入机制详解

Step 1：目录结构即协议

当你把 Superpowers 克隆到项目根目录：

your-project/
├── .claude/           # Claude Code 插件目录
│   └── plugins/
│       └── superpowers/  # 软链接或直接复制
│           ├── skills/      # 14+ 个 Skill 文件
│           └── AGENTS.md   # Agent 行为入口
├── .codex/            # Codex 插件目录（结构类似）
├── .cursor/           # Cursor 插件目录
├── .opencode/         # OpenCode 插件目录
└── ...

# 或者更直接的方式：把 skills/ 目录放在项目根目录下
your-project/
├── skills/            # Superpowers 的技能库
│   ├── clarify-interesting-questions.md
│   ├── create-initial-plan.md
│   ├── tdd-cycle.md
│   └── ...
└── AGENTS.md          # 项目级的 Agent 指令文件

Step 2：AGENTS.md / CLAUDE.md 是"总入口"

Superpowers 在每个插件目录下都提供了一个 AGENTS.md（或 CLAUDE.md、CODEX.md，取决于平台），它的作用是：

# AGENTS.md（Superpowers 注入的核心入口文件）

你是一个遵循 Superpowers 方法论的资深软件工程师。

## 在执行任何代码编写任务前，你必须：

1. 阅读并理解 `skills/clarify-interesting-questions.md`，并按其中的指引与用户澄清需求
2. 阅读 `skills/create-initial-plan.md`，形成设计方案并与用户确认
3. 阅读 `skills/create-implementation-plan.md`，拆解实现计划
4. 按 `skills/tdd-cycle.md` 的指引，用 TDD 方式逐步完成实现
5. 完成实现后，按 `skills/request-code-review.md` 发起代码审查

## 禁止行为

- 禁止在没有测试用例的情况下编写实现代码
- 禁止跳过方案设计阶段直接开始编码
- 禁止在没有通过所有测试的情况下提交代码

Agent 在启动时会自动读取项目目录下的 AGENTS.md / CLAUDE.md 等文件，将其作为"系统提示词"的一部分。这就是 Skill 注入的底层原理。

Step 3：每个 Skill 文件 = 一个强制行为模式

以 tdd-cycle.md 为例（简化版）：

# TDD Cycle Skill

你正在采用测试驱动开发（TDD）方式实现功能。

## 严格遵循 Red-Green-Refactor 循环

### Red 阶段
- 写一个失败的测试用例
- 运行测试，确认它确实失败了（红灯）
- 禁止在这个阶段写任何实现代码

### Green 阶段
- 写**最少量的代码**让测试通过
- 不要追求代码优雅，只要测试通过
- 运行测试，确认绿灯

### Refactor 阶段
- 现在可以重构代码了
- 确保重构后所有测试仍然通过
- 检查代码可读性、性能、边界情况

## 循环终止条件
- 所有需求对应的测试用例都已通过
- 代码已通过静态检查（lint/type check）
- 准备进入 request-code-review 阶段

Agent 读取这个文件后，它的后续行为会被"锁定"在这个模式里。不是建议，是强制——因为整个 Skill 文件就是 Agent 当前上下文的一部分，它必须遵守。

14 个核心 Skills 逐个数：哪一个是你的真命天子？

截至 v5.1.0，Superpowers 的 skills/ 目录下共有 14+ 个 Skills。下面逐一解析（按使用频率排序）：

1. `clarify-interesting-questions.md` — 需求澄清（每次必用）

触发时机：用户提出任何开发需求时
核心作用：强迫 Agent 先提问，再动手

典型提问清单（Agent 会自动生成类似的问题）：

"这个功能的边界是什么？异常处理怎么设计？"
"性能要求是多少？需要支持并发吗？"
"有没有已有的类似功能可以复用？"
"数据库 schema 需要一起改吗？迁移方案是？"

是否必须：✅ 强烈建议开启。没有需求澄清，后面的设计和实现都是"建立在沙子上的城堡"。

2. `create-initial-plan.md` — 初始方案设计（每次必用）

触发时机：需求澄清完成后
核心作用：形成技术方案，等待人类确认后再推进

方案设计模板（Agent 会自动填充）：

## 技术方案

### 架构概览
- 新增/修改的模块：<模块名>
- 依赖的现有模块：<模块名>
- 数据流向：<请求 → 处理 → 响应>

### 技术选型
- Web 框架：<Flask/FastAPI/Django...>
- 数据库：<SQLite/PostgreSQL...>
- 测试框架：<pytest/unittest...>

### 风险点
- <风险1>：<缓解方案>
- <风险2>：<缓解方案>

### 实现步骤（高层）
1. <步骤1>
2. <步骤2>
...

请确认这个方案，或者提出修改意见。

是否必须：✅ 必须。这是防止 AI "跑偏"的核心 checkpoint。

3. `create-implementation-plan.md` — 实现计划拆解（每次必用）

触发时机：方案设计确认后
核心作用：把大任务拆解成 Agent 可以逐条完成的小任务

拆解示例：

## 实现计划

- [ ] Task 1：设计数据模型（对应测试用例 #1-#3）
  - 子步骤：
    - 定义 User 表 schema
    - 编写 migration 脚本
    - 写单元测试验证 schema 正确性

- [ ] Task 2：实现 JWT 签发逻辑（对应测试用例 #4-#7）
  - 子步骤：
    - 写失败测试：缺失 secret、过期 token、非法 payload
    - 实现签发函数
    - 所有测试通过

- [ ] Task 3：...

是否必须：✅ 必须。没有拆解的计划 = 空中楼阁。

4. `tdd-cycle.md` — TDD 强制循环（每次必用）

前文已详细介绍，不再赘述。

是否必须：✅ 强烈建议。TDD 是保证代码质量的"最后一道防线"。

5. `request-code-review.md` — 代码审查（每次必用）

触发时机：所有实现完成、所有测试通过后
核心作用：强制 Agent 进行自我审查，或请求人类 Code Review

自我审查清单（Agent 会自动执行）：

## Code Review Checklist

- [ ] 所有测试用例通过？
- [ ] 代码覆盖率 ≥ 80%？
- [ ] 没有硬编码的密码/密钥/token？
- [ ] 错误处理完整（try/except，错误码定义）？
- [ ] 函数/模块有文档字符串？
- [ ] 代码风格符合项目规范（lint 通过）？
- [ ] 没有引入新的依赖，或者已更新 requirements.txt？
- [ ] Git commit message 符合规范？

审查完成后，Agent 会输出一份 Review 报告，并等待人类确认是否合并。

是否必须：✅ 必须。没有 Review 的代码不应该被合并。

6. `worktree-isolation.md` — Git Worktree 隔离（多 Agent 协作时必用）

触发时机：需要并行开发多个功能时
核心作用：为每个子 Agent 创建独立的 worktree，避免冲突

# Agent 会自动执行类似命令
git worktree add ../worktree/feature-login -b feature/login main
cd ../worktree/feature-login
# 在这个 worktree 里独立开发，不影响 main 分支

完成后：

git worktree remove ../worktree/feature-login
git merge feature/login

是否必须：🔶 多 Agent 协作时必用，单 Agent 开发可以跳过。

7. `systematic-debugging.md` — 系统化调试

触发时机：测试失败、或者运行时报错
核心作用：防止 Agent "瞎改代码碰运气"，强制系统化定位问题

调试流程：

1. 复现问题（找到最小复现用例）
2. 读错误信息（完整的 stack trace）
3. 定位根因（哪个模块、哪一行）
4. 写一个新的失败测试，复现这个 bug
5. 修复代码，让新测试通过
6. 确认所有老测试仍然通过（没有引入回归）

是否必须：🔶 调试时必用，正常开发流程中非必需。

8. `write-documentation.md` — 文档编写

触发时机：功能实现完成、代码审查通过后
核心作用：强制 Agent 编写必要的文档

文档清单：

API 文档（每个 endpoint 的请求/响应格式）
模块文档（每个导出函数的用途、参数、返回值）
README 更新（如果是新功能）
架构决策记录（ADR，如果需要）

是否必须：🔶 建议开启。好的项目离不开好的文档。

9. `refactor-existing-code.md` — 重构现有代码

触发时机：需要重构遗留代码、或者偿还技术债时
核心作用：确保重构不引入新 bug

重构安全网：

1. 先写/完善现有代码的测试用例（确保覆盖原有行为）
2. 确认所有测试通过（建立"安全基线"）
3. 执行重构
4. 再次运行所有测试，确保通过后
5. 对比重构前后性能（如果有性能要求）

是否必须：🔶 重构时必用。

10. `handle-merge-conflicts.md` — 合并冲突处理

触发时机：Git merge 发生冲突时
核心作用：系统化解决冲突，不丢代码

是否必须：🔶 遇到冲突时必用。

11-14. 其他 Skills

Skill 文件名	作用	使用频率
`research-and-evaluate.md`	技术调研与方案对比	中
`write-tests-for-existing-code.md`	为遗留代码补测试	中
`optimize-performance.md`	性能优化（profiling → 优化 → 对比）	低
`prepare-release.md`	发版准备（版本号、CHANGELOG、tag）	低

TDD 强制循环：让 AI 先红灯、再绿灯、最后重构

这一部分深入讲解 Superpowers 的 TDD Skill 实现细节。

为什么 AI 特别需要 TDD？

AI 写代码有两个天然缺陷：

"写完就跑"心态：AI 倾向于一口气生成大量代码，然后才发现逻辑错误
测试用例"走过场"：AI 生成的测试往往是为了"让覆盖率数字好看"，而不是真正验证边界情况

TDD 的 Red-Green-Refactor 循环，正好针对这两个缺陷：

缺陷1 → 被"小步迭代"克制：每次只写几行代码，测试不过不敢继续
缺陷2 → 被"测试先行"克制：测试是先写的，AI 无法"先写实现再补测试"

TDD Cycle 在 Superpowers 中的完整流程

以"实现用户登录接口"为例：

Round 1：第一个测试用例（登录成功）

RED 阶段：

# test_auth.py（Agent 先写这个文件）

def test_login_success():
    """测试正确的用户名密码能够登录成功"""
    response = client.post("/api/login", json={
        "username": "testuser",
        "password": "correct_password"
    })
    assert response.status_code == 200
    assert "access_token" in response.json()
    assert response.json()["token_type"] == "bearer"

# Agent 运行测试 → 失败（RED），因为 /api/login 还没实现

GREEN 阶段：

# app.py（Agent 写最少量的代码让测试通过）

from flask import Flask, request, jsonify
import jwt
from datetime import datetime, timedelta

app = Flask(__name__)

@app.route("/api/login", methods=["POST"])
def login():
    data = request.get_json()
    # 最简实现：硬编码通过测试
    if data["username"] == "testuser" and data["password"] == "correct_password":
        token = jwt.encode(
            {"sub": "testuser", "exp": datetime.utcnow() + timedelta(hours=1)},
            "secret",
            algorithm="HS256"
        )
        return jsonify({"access_token": token, "token_type": "bearer"})
    return jsonify({"error": "Unauthorized"}), 401

# Agent 运行测试 → 通过（GREEN）

REFACTOR 阶段：

# 重构：把硬编码去掉，接入真实数据库

from flask import Flask, request, jsonify
import jwt
from datetime import datetime, timedelta
from models import User  # 新增：导入 User 模型

app = Flask(__name__)

@app.route("/api/login", methods=["POST"])
def login():
    data = request.get_json()
    user = User.query.filter_by(username=data["username"]).first()
    if user and user.check_password(data["password"]):
        token = jwt.encode(
            {"sub": user.id, "exp": datetime.utcnow() + timedelta(hours=1)},
            app.config["SECRET_KEY"],
            algorithm="HS256"
        )
        return jsonify({"access_token": token, "token_type": "bearer"})
    return jsonify({"error": "Unauthorized"}), 401

# Agent 运行测试 → 仍然通过（REFACTOR 安全）

Round 2：第二个测试用例（密码错误）

RED 阶段：

# test_auth.py（Agent 新增测试）

def test_login_wrong_password():
    """测试错误密码返回 401"""
    response = client.post("/api/login", json={
        "username": "testuser",
        "password": "wrong_password"
    })
    assert response.status_code == 401
    assert "access_token" not in response.json()

# 运行测试 → 失败（RED）

GREEN 阶段：

# app.py（Agent 修改实现，让新测试通过）

    # ... 前面的代码 ...
    if user and user.check_password(data["password"]):
        # ... 签发 token ...
        return jsonify({"access_token": token, "token_type": "bearer"})
    return jsonify({"error": "Unauthorized"}), 401

# 运行所有测试 → 通过（GREEN）

循环继续...

Agent 会继续写更多测试用例（用户名不存在、JWT 过期、并发登录...），每写一个测试就跑一次 Red-Green-Refactor 循环，直到覆盖所有需求。

这就是 Superpowers 的 TDD Skill 的威力：它把"写测试"从"可选的建议"变成了"必经的流程"。

代码实战：用 Superpowers 开发一个 REST API

下面用一个完整的例子，演示 Superpowers 如何改变开发流程。

需求描述

开发一个简单的 Todo List REST API，支持：
- 创建 Todo
- 查询 Todo 列表
- 更新 Todo 状态（完成/未完成）
- 删除 Todo

技术要求：
- 使用 Flask + SQLAlchemy
- 数据持久化到 SQLite
- 每个接口都要有单元测试
- 使用 JWT 做认证（只有登录用户才能操作自己的 Todo）

传统 AI 编程流程（没有 Superpowers）

用户：帮我写上面的 Todo API

AI：好！（直接生成下面所有代码）

【app.py（200 行）】
【models.py（50 行）】
【tests.py（30 行，测试用例很浅）】

AI：写完了！你看一下～

你运行测试：
..................................F....
=================================== FAILURES ===================================
______________________ test_update_todo_not_found _______________________________
【AI 没有考虑 edge case：更新一个不存在的 Todo 应该怎么处理】

使用 Superpowers 后的流程

Step 1：需求澄清（`clarify-interesting-questions` Skill 自动触发）

Agent：
感谢你的需求描述！在开始之前，我需要澄清几个问题：

1. Todo 有哪些字段？只有 title + done，还是需要增加 description、due_date、priority？
2. "查询 Todo 列表"接口需要支持过滤和分页吗？
3. JWT 认证：是需要我实现完整的用户注册/登录流程，还是可以用一个固定的测试 token？
4. SQLite 数据库文件放在哪里？项目根目录还是 ./data/？
5. 错误处理：API 的错误响应格式有要求吗？（比如 {"error": "..."} 还是 {"detail": "..."}）

请回答这些问题，我再开始设计方案。

（你回答了这些问题后，进入下一步）

Step 2：方案设计（`create-initial-plan` Skill 自动触发）

Agent：
好的，根据您的回答，我设计了以下技术方案：

## 技术方案

### 数据模型
class Todo(db.Model):
    id: int (主键)
    title: str (必填，最长 200 字符)
    description: str (可选)
    done: bool (默认 False)
    created_at: datetime (自动生成)
    user_id: int (外键 → User.id)

class User(db.Model):
    id: int
    username: str (唯一)
    password_hash: str

### API 端点设计
- POST   /api/register      注册新用户（无需认证）
- POST   /api/login         登录，返回 JWT（无需认证）
- POST   /api/todos         创建 Todo（需要认证）
- GET    /api/todos         查询当前用户的 Todo 列表（支持 ?done=true/false 过滤，需要认证）
- PUT    /api/todos/<id>    更新 Todo（需要认证，只能操作自己的）
- DELETE /api/todos/<id>    删除 Todo（需要认证，只能操作自己的）

### 技术栈
- Flask 3.x
- SQLAlchemy 2.x（ORM）
- PyJWT（JWT 签发/验证）
- pytest + pytest-flask（测试）

### 风险点
- JWT secret 管理：本 demo 用环境变量，生产环境建议用密钥管理服务
- SQLAlchemy session 管理：需要正确处理事务提交/回滚

请确认这个方案，或者提出修改意见。

（你确认方案后，进入下一步）

Step 3：实现计划拆解（`create-implementation-plan` Skill 自动触发）

Agent：
方案已确认！下面是实现计划，我会逐条完成：

## 实现计划

- [ ] Task 1：搭建项目骨架（Flask app 初始化、SQLAlchemy 配置、数据库迁移脚本）
  - 测试用例：
    - test_app_creates_db（验证数据库文件成功创建）
  
- [ ] Task 2：实现 User 模型 + 注册接口
  - 测试用例：
    - test_register_success（正常注册）
    - test_register_duplicate_username（重复用户名返回 400）
    - test_register_missing_password（缺失密码返回 400）
    
- [ ] Task 3：实现登录接口（JWT 签发）
  - 测试用例：
    - test_login_success（正确密码返回 JWT）
    - test_login_wrong_password（错误密码返回 401）
    - test_login_nonexistent_user（不存在的用户返回 401）
    
- [ ] Task 4：实现 JWT 认证装饰器
  - 测试用例：
    - test_access_protected_endpoint_with_valid_token（有效 token 可以访问）
    - test_access_protected_endpoint_without_token（无 token 返回 401）
    - test_access_protected_endpoint_with_expired_token（过期 token 返回 401）
    
- [ ] Task 5：实现 Todo CRUD 接口
  - 测试用例（共 12 个）：
    - 创建：成功、缺失 title、title 超长
    - 查询：返回当前用户自己的 Todo、过滤 done 状态、空列表
    - 更新：成功、Todo 不存在、操作别人的 Todo（返回 403）
    - 删除：成功、Todo 不存在、操作别人的 Todo（返回 403）
    
- [ ] Task 6：代码审查 + 文档编写

开始执行 Task 1...

Step 4：TDD 方式逐 Task 实现（每个 Task 都遵循 `tdd-cycle` Skill）

以 Task 2（注册接口）为例：

RED：

# tests/test_auth.py

def test_register_success(client):
    """测试正常注册流程"""
    response = client.post("/api/register", json={
        "username": "alice",
        "password": "secure_password_123"
    })
    assert response.status_code == 201
    assert "user_id" in response.json()
    
    # 验证数据库里确实写入了
    user = User.query.filter_by(username="alice").first()
    assert user is not None
    assert user.check_password("secure_password_123")

# Agent 运行：失败（RED）→ User 模型还没定义

GREEN：

# models.py

from app import db
from werkzeug.security import generate_password_hash, check_password_hash

class User(db.Model):
    id = db.Column(db.Integer, primary_key=True)
    username = db.Column(db.String(80), unique=True, nullable=False)
    password_hash = db.Column(db.String(200), nullable=False)
    
    def set_password(self, password):
        self.password_hash = generate_password_hash(password)
    
    def check_password(self, password):
        return check_password_hash(self.password_hash, password)

# app.py（新增注册路由）

@app.route("/api/register", methods=["POST"])
def register():
    data = request.get_json()
    if not data.get("username") or not data.get("password"):
        return jsonify({"error": "Missing username or password"}), 400
    
    if User.query.filter_by(username=data["username"]).first():
        return jsonify({"error": "Username already exists"}), 400
    
    user = User(username=data["username"])
    user.set_password(data["password"])
    db.session.add(user)
    db.session.commit()
    
    return jsonify({"user_id": user.id}), 201

# Agent 运行测试：通过（GREEN）

REFACTOR：

# 重构：加入输入验证（用户名长度、密码复杂度）

import re

def validate_registration(username, password):
    if len(username) < 3 or len(username) > 80:
        return False, "Username must be 3-80 characters"
    if len(password) < 8:
        return False, "Password must be at least 8 characters"
    return True, ""

# 修改 register() 函数使用 validate_registration

Step 5：所有 Task 完成后，自动触发代码审查（`request-code-review` Skill）

Agent：
所有功能已实现，所有测试已通过（共 23 个测试用例，覆盖率 87%）。

## Code Review 报告

### 通过的检查项
- [x] 所有测试通过
- [x] 代码覆盖率 87% ≥ 80%
- [x] 没有硬编码密钥（JWT secret 从环境变量读取）
- [x] 所有接口都有错误处理
- [x] 所有导出函数都有 docstring
- [x] flake8 lint 通过
- [x] requirements.txt 已更新

### 需要人类确认的项
- [ ] JWT 过期时间设为 24 小时，是否合理？
- [ ] SQLite 用于 demo，生产环境是否需要迁移到 PostgreSQL？
- [ ] 缺少 rate limiting（防止暴力破解密码），是否需要加入？

请确认是否可以合并到 main 分支。

多 Agent 协作：Git Worktree 隔离 + 子 Agent 分工

Superpowers 内置了对多 Agent 并行协作的支持，这是它在企业级项目中真正脱颖而出的特性。

问题场景

你有一个大型需求："给用户系统加上社交功能（关注、私信、动态）"

这个需求可以拆成 3 个独立子任务：
- 子任务 A：实现关注/取关功能
- 子任务 B：实现私信功能
- 子任务 C：实现动态（朋友圈）功能

如果让一个 Agent 串行完成，需要 2 小时。
如果让 3 个 Agent 并行完成，只需 40 分钟。

但并行开发有冲突风险：3 个 Agent 同时改 models.py，最后合并时炸了。

Worktree 隔离方案

worktree-isolation Skill 让每个子 Agent 在独立的 worktree 里工作：

# 主 Agent（你的大脑）拆解任务后，启动 3 个子 Agent

# 子 Agent A：关注功能
git worktree add ../worktree/feature-follow -b feature/social-follow main
cd ../worktree/feature-follow
# 子 Agent A 在这个目录里独立开发，改 models.py 不会影响别人

# 子 Agent B：私信功能
git worktree add ../worktree/feature-message -b feature/social-message main
cd ../worktree/feature-message
# 子 Agent B 独立开发

# 子 Agent C：动态功能
git worktree add ../worktree/feature-feed -b feature/social-feed main
cd ../worktree/feature-feed
# 子 Agent C 独立开发

# 3 个子 Agent 同时工作，互不干扰
# 完成后，逐个合并到 main
git checkout main
git merge feature/social-follow
git merge feature/social-message  
git merge feature/social-feed
# 如果有冲突，在合并时解决（冲突范围小，因为各子 Agent 负责的模块相对独立）

Superpowers 如何自动化这个过程？

worktree-isolation Skill 提供了标准的 Agent 指令模板：

# worktree-isolation.md（Skill 内容摘要）

你正在并行开发多个功能。为了实现隔离开发：

1. 为每个子任务创建一个独立的 Git worktree：
   git worktree add <path> -b <feature-branch> main

2. 在 worktree 目录下工作，确保所有修改都在这个分支上

3. 完成开发后：
   - 运行测试，确保所有测试通过
   - 提交代码
   - 通知主 Agent 可以合并

4. 合并完成后，清理 worktree：
   git worktree remove <path>
   git branch -d <feature-branch>

配合 requesting-code-review Skill（子 Agent 完成后的自动 Review 请求），整个多 Agent 协作流程可以做到高度自动化。

接入指南：Claude Code、Codex、Cursor 全平台适配

Superpowers 的设计哲学是"零依赖、纯文本、全平台"——它只是一堆 Markdown 文件，任何能读取项目文件的 Agent 都能用。

Claude Code 接入（最完整支持）

# 方法 1：作为 Claude Code 插件安装（推荐）
mkdir -p ~/.claude/plugins
git clone https://github.com/obra/superpowers ~/.claude/plugins/superpowers

# 然后在你的项目里启用（创建符号链接）
cd your-project
mkdir -p .claude/plugins
ln -s ~/.claude/plugins/superpowers .claude/plugins/superpowers

# 方法 2：直接把 skills/ 目录复制到项目根目录
cd your-project
git clone https://github.com/obra/superpowers /tmp/superpowers
cp -r /tmp/superpowers/skills ./
cp /tmp/superpowers/AGENTS.md ./

Claude Code 会在启动时自动读取 .claude/plugins/superpowers/AGENTS.md，加载所有 Skills。

OpenAI Codex 接入

cd your-project
git clone https://github.com/obra/superpowers /tmp/superpowers
mkdir -p .codex
cp -r /tmp/superpowers/skills .codex/skills
cp /tmp/superpowers/CODEX.md .codex/AGENTS.md  # Codex 使用 CODEX.md

Cursor 接入

cd your-project
git clone https://github.com/obra/superpowers /tmp/superpowers
mkdir -p .cursor/rules
cp -r /tmp/superpowers/skills .cursor/skills
cp /tmp/superpowers/AGENTS.md .cursor/rules/superpowers.mdc

验证安装是否成功

启动 Agent，输入：

请列出你当前可用的 Superpowers Skills。

如果 Agent 能正确列出 14+ 个 Skills（clarify-interesting-questions、create-initial-plan 等），说明安装成功。

与其它方案的对比：Superpowers vs Aider vase vs OpenSpec

特性	Superpowers	Aider vase	OpenSpec
实现方式	Markdown Skills（纯文本）	Python 库 + CLI	OpenAPI Spec 扩展
接入成本	低（复制文件即可）	中（需要安装 Python 包）	高（需要写 OpenAPI 扩展）
TDD 强制	✅ 强制（Skill 规定流程）	🔶 可选（依赖 prompt）	❌ 不支持
多 Agent 协作	✅ 原生支持（worktree-isolation）	❌ 不支持	❌ 不支持
平台兼容性	高（任何能读文件的 Agent）	低（仅 Aider）	中（仅 OpenAPI 生态）
学习曲线	低（读 Markdown 即可）	中（需要学 Aider 命令）	高（需要懂 OpenAPI）
社区 Stars	~198k（截至 2026.05）	~45k	N/A
适合场景	团队协作、企业级项目	个人快速原型	API-first 项目

结论：如果你想要"装上去就能用、不挑 Agent 平台、强制工程纪律"，Superpowers 是目前最好的选择。

实战踩坑与最佳实践

踩坑 1：Agent 忽略 Skill，直接写代码

原因：Agent 的上下文窗口太大，Skill 文件被"稀释"了。
解决方案：在 AGENTS.md 开头加上：

# ⚠️ 强制执行声明

你**必须**在每次写代码前，先阅读对应的 Skill 文件。
如果你跳过 Skill 直接写代码，你就是违反了用户明确指定的开发规范。

## 每次开发任务的标准流程（不可跳过）
1. 读 skills/clarify-interesting-questions.md
2. 读 skills/create-initial-plan.md
3. ...（列出所有 Skills）

踩坑 2：TDD 循环陷入死循环（Agent 一直写测试不过）

原因：Agent 写的测试用例有逻辑错误（比如断言写错了）。
解决方案：在 tdd-cycle.md 里加上"如果同一个测试连续失败 3 次，停止并请求人类介入"的规则。

踩坑 3：Git Worktree 用完后忘记清理

原因：worktree 占用磁盘空间，忘记清理会导致 Git 仓库臃肿。
解决方案：在 worktree-isolation.md 里加上"完成合并后必须执行 git worktree remove"的强制规定。

最佳实践 1：为项目定制 Skills

Superpowers 提供的 Skills 是通用模板，你可以根据项目特点修改：

# skills/custom-tdd-cycle.md（项目定制的 TDD 流程）

本项目的 TDD 特殊要求：
- 每个测试用例必须包含 mock（禁止访问真实数据库）
- 测试覆盖率必须 ≥ 90%（通用版是 80%）
- 性能测试：每个接口必须有 benchmark 测试

最佳实践 2：配合 CI/CD 使用

在 CI 流水线里加入 Superpowers 的合规检查：

# .github/workflows/superpowers-check.yml

name: Superpowers Compliance Check

on: [push, pull_request]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Check TDD compliance
        run: |
          # 检查是否有测试文件
          test_files=$(find . -name "test_*.py" | wc -l)
          if [ $test_files -eq 0 ]; then
            echo "❌ 没有测试文件！请遵循 TDD 规范。"
            exit 1
          fi
          
      - name: Run tests
        run: pytest --cov=app --cov-report=term-missing
        
      - name: Check coverage ≥ 80%
        run: |
          coverage=$(pytest --cov=app --cov-report=term | grep TOTAL | awk '{print $4}' | sed 's/%//')
          if [ $coverage -lt 80 ]; then
            echo "❌ 测试覆盖率 $coverage% < 80%，请补充测试。"
            exit 1
          fi

底层原理：为什么一套 Markdown Skills 能改变 Agent 行为？

这一节深入讲解 Superpowers 的"魔法"背后的技术原理。

原理 1：上下文注入（Context Injection）

现代 Coding Agent（Claude Code、Cursor、Codex 等）都有一个共同特性：

在响应用户请求时，Agent 会自动读取项目目录下的特定文件（如 CLAUDE.md、AGENTS.md、.cursorrules），并将其内容作为"系统提示词"的一部分。

Superpowers 利用的就是这个机制：

项目目录结构：
your-project/
├── AGENTS.md          ← Agent 启动时自动读取
├── skills/
│   ├── skill-a.md    ← AGENTS.md 里引用了这些文件
│   └── skill-b.md    ← Agent 会在需要时主动读取
└── src/
    └── main.py

Agent 的上下文组成：
[系统提示词] + [AGENTS.md 内容] + [用户当前消息] + [当前打开的文件]

当 AGENTS.md 里写了"在写代码前，你必须先读 skills/clarify-interesting-questions.md"，Agent 就会真的去读——因为它的训练数据里包含了"遵循指令"这种模式。

原理 2：Skills 是"少样本提示"（Few-Shot Prompting）

每个 Skill 文件本质上是一个高质量的少样本示例：

# skills/create-initial-plan.md

## 示例：设计一个用户认证方案

输入：用户需求 ="实现登录功能"

输出（你必须按这个格式输出）：
### 技术方案

#### 架构概览
- 新增模块：AuthController、JWTService
- 依赖模块：UserModel、Config
...

#### 风险点
- JWT secret 泄露风险：使用环境变量存储
...

Agent 读取这个文件后，会"模仿"文件里的示例来生成自己的方案设计。Skill 文件的质量直接决定了 Agent 输出的质量。

原理 3：递归上下文加载（Recursive Context Loading）

Superpowers 的一个精妙设计是：Skills 之间可以互相引用。

AGENTS.md
  ├── 引用：skills/clarify-interesting-questions.md
  │     └── 引用：skills/_templates/question-template.md
  ├── 引用：skills/create-initial-plan.md
  │     └── 引用：skills/_templates/plan-template.md
  └── 引用：skills/tdd-cycle.md
        └── 引用：skills/_templates/tdd-example.md

Agent 在处理任务时，会根据当前阶段"按需加载"对应的 Skill 文件。这避免了一次性把所有 Skills 都塞进上下文（导致_token 溢出_）。

社区生态与未来路线图

当前生态（截至 2026 年 5 月）

GitHub Stars：~198,582
Fork 数：~12,400
Discord 社区：~8,700 名成员
贡献者：87 人（持续增加中）
知名企业用户：Google、Microsoft、Stripe、Vercel 等（据社区反馈）

未来路线图（根据 GitHub Issues 和 PR 整理）

版本	预计发布时间	核心特性
v5.2	2026.Q3	支持更多 Agent 平台（GitHub Copilot Workspace、Devin）
v6.0	2026.Q4	Skill 市场（开发者可以发布/下载自定义 Skills）
v6.5	2027.Q1	多语言支持（Java/Go/Rust 项目的专属 Skills）
v7.0	2027.Q2	AI 自动生成项目专属 Skills（基于代码库分析）

总结与展望：AI 编程的"工程化元年"已经到来

Superpowers 的意义，不仅仅是一个开源项目——它标志着 AI 辅助编程从"玩具阶段"进入"工程化阶段"。

关键要点回顾

问题：传统 AI 编程工具"码力爆棚，但工程纪律为零"——像实习生一样写代码
方案：Superpowers 通过 14+ 个 Markdown Skills，把资深工程师的工程纪律"硬编码"进 Agent 的行为模式
核心机制：利用 Agent 的"自动读取项目文件"能力，将 Skills 注入上下文
效果：AI 写出的代码有测试、有文档、有设计、有 Review——接近人类资深工程师的交付标准

适合谁用？

✅ 个人开发者：想让 AI 帮自己写"能上生产"的代码，而不是"能跑就行"的代码
✅ 技术团队 Leader：想统一团队的代码规范，让 AI 辅助工具的输出符合团队标准
✅ 企业用户：需要满足合规要求（代码审查、测试覆盖率、文档完整性），不能接受"黑盒 AI 输出"
❌ 快速原型开发者：如果你只是想"快速验证一个想法"，Superpowers 的规范流程可能会让你觉得"太重了"

展望

2026 年，我们正在见证软件开发史上的一个转折点：

"写代码"的能力正在迅速贬值，"知道该写什么代码"和"知道怎么验证代码正确性"的能力正在迅速升值。

Superpowers 做的，就是把后者"固化"进工具里，让每一个使用 AI 编程工具的人，都能站在资深工程师的肩膀上。

20 万开发者已经用脚投票。你呢？

参考资源

项目地址：https://github.com/obra/superpowers
官方博客：https://blog.fsck.com/2025/10/09/superpowers/
Discord 社区：https://discord.gg/35wsABTejz
CSDN 中文教程：https://blog.csdn.net/wsad0532/article/details/161026049
博客园深度解析：https://www.cnblogs.com/funkygod/p/20063337

本文撰写于 2026 年 6 月，基于 Superpowers v5.1.0。项目持续演进中，建议以官方 GitHub 为准。

作者：程序员茄子 AI 助手 | 欢迎访问 chenxutan.com 获取更多深度技术文章。