Superpowers Skill 深度解析：给 AI 编程助手装上"纪律引擎"

一、Superpowers 到底是什么

1.1 一句话定义

Superpowers 是一个开源的 AI 编程助手"纪律框架"——它不会让你的 AI 变得更聪明，但会让它变得更"守规矩"。

想象一下：你请了一位非常聪明但有点"随性"的实习生。他能力很强，但常常跳过需求分析直接写代码，写完后也不测试就说"搞定了"。Superpowers 就是给这位实习生制定的一套标准化工作流程，确保他每次接到任务时，都会按照资深工程师的标准步骤来执行。

1.2 它解决了什么问题

在使用 Claude Code、Cursor、Codex 等 AI 编程工具时，大家普遍遇到过一个痛点：

AI 太急于表现了。

你刚说"帮我加个用户登录功能"，它就开始噼里啪啦写代码。结果：

• 选了你不想要的第三方库
• 文件创建在了错误的位置
• 漏掉了两个你隐含的需求
• 写完不测试，一运行就报错

等你发现时，已经在调试一堆"不是你想要的"代码了。

根本原因不是 AI 不够聪明，而是它的"默认行为"就是尽快产出结果——这是大语言模型训练时的本能。Superpowers 做的，就是在 AI 动手之前，强制它先走完一套" senior engineer 的标准流程"。

1.3 核心理念：纪律 > 能力

Superpowers 的创始人 Jesse Vincent（也是知名开源项目 Request Tracker 的作者）有一个核心观点：

AI 编码助手缺的不是能力，而是纪律。

你问 Claude "什么是 TDD（测试驱动开发）"，它能给你讲半小时。但让它写代码时，它还是会先写实现再补测试。

Superpowers 把工程纪律编码成了一组 SKILL.md 文件——每个文件是一份"行为指南"，告诉 AI 在特定场景下必须遵循什么流程。这些技能不是建议，而是强制规则。

1.4 技术本质：纯文本的方法论

Superpowers 的技术实现简单得令人惊讶：

没有自定义模型、没有特殊推理层、没有专有 SDK。 就是纯 Markdown 文件 + YAML 前置元数据。这也是为什么它能跨平台支持 Claude Code、Cursor、Codex、Gemini CLI、OpenCode 等十几种工具。

1.5 项目现状

• GitHub Stars：超过 15 万（截至 2026 年 5 月）
• 开源协议：MIT（完全免费）
• 社区：活跃的 Discord 讨论组，持续迭代
• 主要维护者：Jesse Vincent @ Prime Radiant

---

二、五分钟上手：安装与配置

2.1 安装方式一览

Superpowers 支持"一键安装"和"手动安装"两种方式。不同 AI 工具的安装命令略有不同：

Claude Code（官方插件市场）

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

# 方式二：社区市场
/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplace

Cursor

# 在 Cursor Agent 聊天中输入
/add-plugin superpowers

# 或在插件市场中搜索 "superpowers" 安装

Codex CLI / Codex App

# CLI 中打开插件界面
/plugins
# 搜索 "superpowers" 并安装

# 或在 App 侧边栏 Plugins 中点击安装

Gemini CLI

gemini extensions install https://github.com/obra/superpowers

OpenCode

# 让 OpenCode 自动获取安装指南
Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.opencode/INSTALL.md

手动安装（通用方法）

# 1. 克隆仓库
git clone https://github.com/obra/superpowers.git

# 2. 复制 skills 目录到对应位置
# Claude Code:
cp -r superpowers/skills ~/.claude/skills

# Cursor:
cp -r superpowers/skills .cursor/skills

# Codex:
cp -r superpowers/skills ~/.codex/skills

# 其他工具类似...

2.2 验证安装

安装完成后，重启你的 AI 工具会话，然后：

# Claude Code 中查看可用命令
/help

# 应该能看到：
# /superpowers:brainstorm      - 交互式设计细化
# /superpowers:write-plan      - 创建实现计划
# /superpowers:execute-plan    - 执行计划

或者直接问 AI：

"你现在有哪些 Superpowers 技能？"

如果安装正确，AI 会列出所有 14 个技能。

2.3 配置文件说明

Superpowers 与项目的 CLAUDE.md（或 AGENTS.md、GEMINI.md 等）是互补关系：

重要：如果 CLAUDE.md 和 Skill 有冲突，项目配置优先。例如，你的项目文件说"不用 TDD"，那么 TDD Skill 会自动退让。

---

三、核心工作流：七个阶段拆解

Superpowers 的核心是一个强制性的多阶段工作流。每个阶段对应一个 Skill，且必须按顺序完成，不能跳过。

用一张图来理解整个流程：

┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│  1. 头脑风暴  │ → │ 2. Git隔离   │ → │  3. 制定计划  │
│ brainstorming│    │ worktrees   │    │ writing-plans│
└─────────────┘    └─────────────┘    └─────────────┘
                                              ↓
┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│  7. 收尾合并  │ ← │  6. 代码审查  │ ← │  4. 子代理开发 │
│   finishing │    │ code-review │    │ subagent-dev │
└─────────────┘    └─────────────┘    └──────┬──────┘
                                              │
                                       ┌──────┴──────┐
                                       │  5. TDD执行  │
                                       │     TDD     │
                                       └─────────────┘

阶段 1：Brainstorming（头脑风暴）

触发时机：当你表达"我要做某个功能"时自动激活。

做什么：

• AI 不会直接写代码，而是先问你一系列澄清问题
• 探索替代方案，讨论架构权衡
• 把设计分成小块，逐块向你确认
• 输出一份你签字确认的设计文档

为什么重要：防止"做了半天发现不是想要的"这种最昂贵的错误。

示例对话：

你："帮我加个用户登录功能"

AI："在开始之前，让我先确认几个关键点：

1. 你是指传统的用户名/密码登录，还是也要支持 OAuth（微信/Google 登录）？
2. 密码需要满足什么复杂度要求？
3. 登录失败次数过多是否需要锁定账户？
4. 是否需要'记住我'功能？ ..."

阶段 2：Using Git Worktrees（Git 隔离工作区）

触发时机：设计文档确认后。

做什么：

• 自动创建一个新的 Git 分支
• 在独立的目录（worktree）中工作，不影响你的主分支
• 运行项目初始化，验证测试基线是否干净

为什么重要：

• 你可以在主分支继续工作，AI 在隔离区开发
• 改崩了直接丢弃，零风险
• 天然支持多任务并行

阶段 3：Writing Plans（制定计划）

触发时机：隔离工作区准备就绪后。

做什么：

• 把设计拆成超细粒度的任务（每个 2-5 分钟工作量）
• 每个任务包含：
  • 精确的文件路径
  • 完整的预期代码
  • 明确的验证步骤

为什么重要：

• 计划阶段的模糊性，会在执行阶段变成返工
• 把假设提前暴露在"便宜的文本阶段"解决

计划示例：

## Task 1: 创建 User 模型
- **文件**: `src/models/User.ts`
- **代码**: 
  typescript
  export interface User {
    id: string;
    email: string;
    passwordHash: string;
    createdAt: Date;
  }
  
- **验证**: `npm test -- User.model.test.ts` 通过
- **预计时间**: 2 分钟

## Task 2: 创建登录验证逻辑
- **文件**: `src/services/auth.ts`
- **代码**: ...
- **验证**: `npm test -- auth.service.test.ts` 通过

阶段 4：Subagent-Driven Development（子代理开发）

触发时机：计划确认后，开始执行。

做什么：

• 为每个任务启动一个全新的 AI 子代理
• 每个子代理只拿到它需要完成的任务 + 相关计划片段
• 解决"上下文漂移"问题（长会话中 AI 逐渐偏离原始需求）

为什么重要：

• 主代理不会因为做了 20 个任务后"失忆"
• 每个任务都有新鲜、专注的上下文

注意：子代理功能目前仅在 Claude Code 和 Codex 上完整支持，其他平台使用顺序执行模式。

阶段 5：Test-Driven Development（测试驱动开发）

触发时机：每个子代理开始写代码时。

做什么：

• 红：先写测试，确保它失败
• 绿：写最少代码让测试通过
• 重构：优化代码结构，保持测试通过

铁律：

"NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST"

（没有失败的测试，就不允许写生产代码）

如果 AI 先写了实现再补测试，Superpowers 会要求删除代码，重新开始。

阶段 6：Requesting Code Review（代码审查）

触发时机：任务完成后。

做什么：

• 启动一个独立的审查代理（不带实现者的上下文偏见）
• 对照计划检查实现是否符合规范
• 按严重程度报告问题，关键问题阻塞进度

为什么重要：

• 自己审查自己的代码容易"带着有色眼镜"
• 独立审查者能发现实现者忽略的问题

阶段 7：Finishing a Development Branch（收尾合并）

触发时机：所有任务完成并通过审查后。

做什么：

• 运行完整测试套件验证
• 提供选项：合并到主分支 / 发起 PR / 保留分支 / 丢弃
• 清理 worktree，保持环境整洁

---

四、技能体系源码剖析

4.1 仓库结构一览

obra/superpowers/
├── skills/                          # 核心：14 个技能目录
│   ├── using-superpowers/           # 元技能：技能系统的入口
│   ├── brainstorming/               # 头脑风暴
│   ├── writing-plans/               # 制定计划
│   ├── executing-plans/             # 顺序执行计划
│   ├── subagent-driven-development/ # 子代理开发
│   ├── test-driven-development/     # 测试驱动开发
│   ├── systematic-debugging/        # 系统化调试
│   ├── verification-before-completion/  # 完成前验证
│   ├── using-git-worktrees/         # Git 隔离工作区
│   ├── finishing-a-development-branch/    # 收尾分支
│   ├── requesting-code-review/      # 请求代码审查
│   ├── receiving-code-review/       # 接收审查反馈
│   ├── dispatching-parallel-agents/ # 并行代理调度
│   └── writing-skills/              # 编写新技能（元技能）
│
├── .claude-plugin/                  # Claude Code 插件清单
├── .cursor-plugin/                  # Cursor 插件清单
├── .codex/                          # Codex 安装指南
├── .opencode/                       # OpenCode 适配
├── gemini-extension.json            # Gemini CLI 扩展
└── README.md

4.2 SKILL.md 文件结构解析

每个技能都是一个独立的目录，核心文件是 SKILL.md：

---
name: skill-name-with-hyphens
description: Use when [具体触发条件和症状]
---

# Skill Name

## Overview
一句话说明核心原则。

## When to Use
- 使用场景（症状、触发词）
- 不适用场景

## Core Pattern
Before/After 代码对比

## Quick Reference
快速参考表格

## Implementation
实现细节或链接到外部文件

## Common Mistakes
常见错误 + 修复方法

## Real-World Impact (可选)
实际效果数据

关键设计原则：

1. YAML 前置元数据：只有 name 和 description 两个字段，description 必须描述何时使用，而不是做什么
2. 字数控制：常用技能 < 200 词，其他技能 < 500 词（Token 效率）
3. 无叙事：不写"某天我解决了..."的故事，只写可复用的方法论

4.3 "铁律"与"红旗"机制

每个"纪律型"技能都以一条大写的铁律（Iron Law）开头，后面跟着一张红旗表（Red Flags）：

示例：TDD 技能

## Iron Law
NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST

## Red Flags
- "I'll write the test after" → 删除代码，重新开始
- "Tests passing on first run" → 测试可能没真正验证行为
- "Just this once" → 没有例外
- "Keeping deleted code as reference" → 清理掉，不要留着

设计意图：

• AI 已经知道 TDD 是什么，不需要教它
• 需要防止的是 AI "说服自己"跳过这些规则
• 红旗表列出了 AI 最常用的"合理化借口"，提前堵死

4.4 技能发现与触发机制

用户输入
   ↓
Session Start Hook 注入 using-superpowers 技能
   ↓
AI 分析用户输入，匹配 description 中的触发条件
   ↓
如果有匹配技能 → 强制调用（无选择权）
   ↓
AI 读取 SKILL.md 内容并严格遵循

触发规则：

• 自动触发：基于上下文检测（如"build X"触发 brainstorming）
• 手动触发：输入 /skill-name 或 "Use the X skill"
• 1% 规则：只要有 1% 的概率某个技能适用，就必须调用

4.5 跨平台适配原理

Superpowers 的平台无关性是其最大设计亮点：

核心洞察：技能本身是纯 Markdown，不同平台只需要一个"发现机制"让 AI 能读取这些文件。

---

五、四大核心技能详解

5.1 Brainstorming（头脑风暴）—— 设计之门

类型：流程型技能
铁律：在得到用户明确确认前，不允许写任何代码

工作流程：

用户提出需求
    ↓
AI 开始苏格拉底式提问
    ↓
探索替代方案 → 讨论架构权衡 → 识别边界情况
    ↓
分块呈现设计（每块足够短，用户能真正读完）
    ↓
用户逐块确认 / 修改
    ↓
输出设计文档（保存到项目目录）
    ↓
[Gate] 用户签字确认后才能进入下一阶段

为什么这是最重要的技能：

在软件开发中，"做错误的事"比"做错事"昂贵 10 倍。

Superpowers 把 "build the right thing"（做对的事）放在了 "build the thing right"（把事做对）之前。

实际效果：

• 避免"我以为你要的是 A，结果你要的是 B"
• 提前暴露技术债务和架构风险
• 设计文档成为后续开发的"合同"

5.2 Writing Plans（制定计划）—— 执行的蓝图

类型：技术型技能
核心原则：计划要详细到"一个热情但品味差、没判断力、不了解项目、讨厌测试的初级工程师"也能执行

计划结构：

每个任务必须包含：

1. 精确文件路径：src/components/UserProfile.tsx
2. 完整预期代码：不是伪代码，是能直接用的代码
3. 验证步骤：运行什么命令、期望什么输出
4. 时间估算：2-5 分钟完成

示例对比：

❌ 差的计划：

- 创建用户模型
- 实现登录逻辑
- 添加前端表单

✅ Superpowers 计划：

## Task 1: 定义 User 接口
- **文件**: `src/types/user.ts`
- **代码**:
  ```typescript
  export interface User {
    id: string;
    email: string;
    passwordHash: string;
    createdAt: Date;
    updatedAt: Date;
  }

• 验证: npm run typecheck 无错误
• 预计时间: 2 分钟

**为什么过度详细反而更好**：
- 强迫在计划阶段解决所有模糊性
- 执行阶段不需要"即兴发挥"
- 子代理拿到的是"傻瓜式指令"，减少理解偏差

### 5.3 Test-Driven Development（测试驱动开发）—— 质量之锚

**类型**：纪律型技能  
**铁律**：**NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST**

**红-绿-重构循环**：

写测试 → 确认测试失败（Red） ↓ 写最少代码让测试通过（Green） ↓ 重构代码，保持测试通过（Refactor） ↓ 提交代码 ↓ 重复

**反模式目录**：

TDD Skill 包含一个完整的"常见错误"参考表：

| 反模式 | 症状 | 修复 |
|--------|------|------|
| 虚假测试 | 测试总是通过，不测边界情况 | 先写测试，确保它失败 |
| 测试后补 | 先写实现再补测试 | 删除实现，重新开始 |
| 过度测试 | 测试实现细节而非行为 | 测试输入输出，不测试内部 |
| 忽略重构 | 测试通过后不优化代码 | 必须包含重构步骤 |

**实际案例**：

chardet 项目使用 Superpowers 发布 7.0.0 版本：
- 处理速度提升 **41 倍**
- 准确率 **96.8%**
- 修复了数十个长期存在的问题
- 测试套件覆盖 2,161 个文件、99 种编码

这些测试是 TDD 的直接产物。

### 5.4 Systematic Debugging（系统化调试）—— 根因追踪

**类型**：模式型技能  
**铁律**：**NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST**

**四阶段流程**：

Phase 1: 复现（Reproduce）

• 写一个能稳定触发 Bug 的测试用例
• 如果无法复现，就不是真正的 Bug

Phase 2: 定位（Investigate）

• 追踪调用链，找到根因（不是症状）
• 使用 root-cause-tracing 技术
• 形成假设："问题出在 X，因为 Y"

Phase 3: 修复（Fix）

• 修改根因，而不是包一层 try-catch
• 最小化改动范围

Phase 4: 验证（Verify）

• 运行测试确认修复
• 检查没有引入新问题
• 运行相关回归测试

**为什么 AI 需要这个技能**：

没有指导时，AI 遇到 Bug 的典型反应：
1. 看到报错信息
2. 在报错位置加 try-catch
3. "不报错了，修好了！"

实际上问题根本没解决，只是被掩盖了。Systematic Debugging 强制 AI 在动手前**先理解问题**。

**特别说明**：
> "Use this ESPECIALLY when under time pressure. Emergencies make guessing tempting."
> 
> （时间越紧迫，越要使用这个技能。紧急情况下最容易产生"猜一个试试"的冲动。）

---

## 六、自定义技能开发指南

### 6.1 为什么要创建自定义技能

标准 14 个技能覆盖了通用开发流程，但你的团队可能有特殊需求：

| 场景 | 标准技能 | 自定义技能 |
|------|----------|------------|
| 通用开发流程 | ✅ | - |
| 团队编码规范 | - | ✅ |
| 行业合规要求（如金融、医疗） | - | ✅ |
| 特定技术栈最佳实践 | - | ✅ |
| 公司发布流程 | - | ✅ |

### 6.2 技能创建方法论：TDD for Documentation

Superpowers 把技能创建本身也做成了 TDD 流程：

RED 阶段：写失败测试

• 创建压力场景（3+ 个组合压力）
• 不用技能运行场景，记录 AI 的基线行为
• 收集 AI 的"合理化借口"

GREEN 阶段：写最小技能

• 遵循标准 SKILL.md 结构
• 针对基线失败编写规则
• 用技能运行场景，验证 AI 现在遵守规则

REFACTOR 阶段：堵 loophole

• 测试中发现新的"合理化借口"
• 添加显式对策
• 重新测试直到"防弹"

### 6.3 SKILL.md 标准模板

```markdown
---
name: your-skill-name
description: Use when [具体触发条件和症状]
---

# Skill Name

## Overview
核心原则，1-2 句话。

## When to Use
**Use when:**
- 触发条件 1
- 触发条件 2

**Don't use for:**
- 不适用场景 1

## Core Pattern
Before / After 对比

## Quick Reference
| 场景 | 操作 |
|------|------|
| 情况 A | 做法 X |
| 情况 B | 做法 Y |

## Implementation
代码示例或链接到外部文件

## Common Mistakes
**错误**：描述错误做法
**修复**：正确做法

## Related Skills
- [相关技能 1]
- [相关技能 2]

6.4 命名与描述规范

命名规则：

• ✅ test-driven-development（动词开头，连字符连接）
• ✅ creating-skills（动名词形式）
• ❌ tdd（缩写不明确）
• ❌ skill-creation（被动语态）

描述规则：

• 只描述何时使用，不描述做什么
• 以 "Use when..." 开头
• 包含具体触发词、症状、错误信息
• 第三人称
• 不超过 1024 字符

# ❌ 错误：描述做了什么
 description: Use when executing plans - dispatches subagent per task with code review

# ✅ 正确：只描述触发条件
 description: Use when executing implementation plans with independent tasks in the current session

6.5 实战案例：创建"生产部署"技能

Step 1: 定义目标

**Skill name**: deploying-to-production

**Problem to solve**:
团队没有统一的生产部署流程，导致：
- 遗漏部署前检查
- 回滚计划不清晰
- 相关人员未及时通知

**Success criteria**:
- [ ] 自动化的部署前检查清单
- [ ] 明确的回滚计划
- [ ] 利益相关者自动通知

Step 2: 编写触发条件

## Trigger

**Automatic triggers**:
- "Deploy to production"
- "Release a new version"
- "Ship the new feature"

**Manual triggers**:
- "Use the deploying-to-production skill"

**Do not trigger**:
- "Deploy to test"
- "Deploy to staging"

Step 3: 定义行为与流程

## Behavior
When triggered, the skill should:
1. Present a deployment checklist
2. Request rollback plan and notification list
3. Generate step-by-step deployment plan

## Process
### Phase 1: Pre-deployment checks
1. Show checklist (code, tests, docs)
2. Confirm items one by one
3. Record results

### Phase 2: Risk assessment
1. Assess change scope
2. Confirm rollback plan
3. Identify risk points

### Phase 3: Execute deployment
1. Follow steps in order
2. Verify after each step
3. Record results

### Phase 4: Post-deployment verification
1. Run smoke tests
2. Check monitoring metrics
3. Confirm feature works

Step 4: 测试技能

## Test Scenarios

### Scenario 1: Normal deployment
**Input**: "Prepare to deploy to production"
**Expected**:
1. Skill triggers
2. Checklist shown
3. Rollback plan requested
4. Deployment plan generated

### Scenario 2: Skip checks request
**Input**: "Quick deploy, skip checks"
**Expected**:
1. Risk warning shown
2. Minimum checklist enforced
3. Explicit confirmation required

### Scenario 3: Non-production deployment
**Input**: "Deploy to test environment"
**Expected**:
- Skill does NOT trigger

6.6 发布与共享

## Release Process
1. Internal review (team review + test)
2. Pilot use (1-2 projects)
3. Formal release (update repo + notify team)
4. Ongoing maintenance (review + iterate)

## Publish to Marketplace
1. Prepare docs + test cases + examples
2. Create PR to superpowers-marketplace
3. Respond to review comments
4. Maintain after release

---

七、进阶用法与实战技巧

7.1 自然语言驱动，无需记命令

Superpowers 支持自动触发，你不需要记住技能名称：

7.2 强制完整流程

在需求前加一句，确保 AI 不跳过步骤：

"按 Superpowers 完整流程，先 brainstorm，再 write-plan，最后 execute-plan，必须做 TDD 和 code review"

7.3 并行子代理加速大任务

当任务互相独立时，Superpowers 自动并行：

你："帮我把这 6 个 API 接口都加上参数校验"

Superpowers 分析：6 个接口互不依赖
   ↓
自动分发给 3 个子代理并行处理
   ↓
每个子代理遵循 TDD 流程
   ↓
完成后合并，跑集成测试

效果对比：

时间节省 60%，Token 消耗仅增加约 12%。

7.4 长项目会话管理

超长期项目（数周）仍可能积累上下文债务：

解决方案：

1. 定期 /compact：压缩历史对话，保留关键决策
2. 文档化架构决策：让 Superpowers 在 Plan 阶段输出 ARCHITECTURE.md
3. Git Worktree 隔离：每个大功能独立分支，完成后合并清理

7.5 团队统一规范

全团队统一安装 Superpowers，实现：

• 统一开发流程
• 统一代码规范（通过自定义技能）
• 统一审查标准
• 降低沟通成本，提升交付质量

7.6 与 IDE 集成

虽然 Superpowers 主要在终端运行，但可以配合 IDE：

1. 在 VS Code 中安装 Claude Code Extension
2. 使用 VS Code 终端运行 claude 命令
3. 在 VS Code 中查看生成的代码和测试文件
4. 利用 VS Code 的 Git 面板管理 worktree 分支

7.7 何时不使用 Superpowers

Superpowers 不是银弹，有些场景不适合：

Jesse Vincent 的原话：

"Skills are meant to be invoked when they apply, and there are task types where none apply."

---

八、常见问题与避坑指南

8.1 安装问题

问题：安装后命令不可用

Claude Code：

# 检查插件是否安装
/plugin list

# 重新加载
/plugin reload superpowers

# 重启 Claude Code（必须）

Cursor：

# 完全退出 Cursor 再重新打开（不是 Reload Window）
# 在 Cursor 2.6+ 版本中已修复

问题：Windows 上符号链接失败

原因：Git Bash 的 ln -sf 在 Windows 上会复制文件而不是创建链接。

解决：

# 使用 Windows 目录连接点
mklink /J ".\\target" ".\\source"

8.2 技能不触发

问题：AI 直接写代码，没有 brainstorm

解决：

1. 确认插件安装成功（见 8.1）
2. 显式要求："Before writing any code, use the brainstorming skill"
3. 检查对话上下文是否匹配触发条件

问题：Skill 文件存在但 AI 不用

排查：

# 检查 YAML 格式（不能用 Tab，必须用空格）
# 检查 description 是否清晰
# 检查 skill 是否在正确的目录结构下

# 正确结构：
skills/
  skill-name/
    SKILL.md    # 必须有这个文件

8.3 执行问题

问题：子代理任务卡在审查循环

现象：AI 不断发现"关键问题"，无法推进。

解决：

# 查看阻塞任务
"Show me the critical issues blocking Task N"

# 决定修复或覆盖
"Accept the current implementation and continue to Task N+1"

问题：Worktree 冲突

# 查看活跃 worktree
git worktree list

# 强制移除卡住的 worktree
git worktree remove --force ../project-branch-name
git branch -d feature/branch-name

8.4 平台特定问题

OpenCode

# 查看详细日志
opencode run "test" --print-logs --log-level DEBUG

# 检查插件符号链接
ls -l ~/.config/opencode/plugins/

# 重启 OpenCode（插件更改后必须）

Codex

# 检查 Node.js 版本（需要 v18+）
node --version

# 给 CLI 脚本添加执行权限
chmod +x ~/.codex/superpowers/.codex/superpowers-codex

# 验证技能文件
ls ~/.codex/superpowers/skills/

8.5 常见误区

---

九、与同类工具对比

9.1 Superpowers vs GStack

一句话总结：

• 选 Superpowers：如果你的主要问题是"AI 写代码太随意、测试覆盖率低"
• 选 GStack：如果你需要"从产品构思到部署的完整生命周期管理"
• 两者都用：Superpowers 管实现纪律，GStack 管规划和 QA

9.2 Superpowers vs CLAUDE.md / Cursor Rules

关系：互补。CLAUDE.md 告诉 AI "你的项目是什么"，Superpowers 告诉 AI "你应该怎么工作"。

9.3 Superpowers vs 原生 AI 行为

9.4 生态对比总览

┌─────────────────────────────────────────────────────────────┐
│                      AI 编程助手生态                         │
├─────────────────────────────────────────────────────────────┤
│  基础层：Claude Code / Cursor / Codex / Gemini CLI          │
│     ↓                                                       │
│  纪律层：Superpowers（流程强制）                            │
│     ↓                                                       │
│  角色层：GStack（分工协作）                                  │
│     ↓                                                       │
│  能力层：Firecrawl / Document Skills / Webapp Testing        │
│     （给 AI 增加新能力：爬虫、文档处理、浏览器测试）         │
│     ↓                                                       │
│  偏好层：Frontend Design / React Best Practices             │
│     （编码风格、性能规则）                                    │
└─────────────────────────────────────────────────────────────┘

---

结语

Superpowers 代表了一种重要的范式转变：

从"让 AI 更聪明"到"让 AI 更守规矩"。

它不是又一个试图替代工程师的工具，而是一套把资深工程师的经验编码成可复用流程的框架。它的成功证明了：在 AI 编程时代，方法论和纪律比单纯的能力更重要。

对于技术读者，Superpowers 是一个值得深入研究的工程实践框架；对于非技术读者，它展示了 AI 工具正在从"聪明的助手"进化为"可靠的合作伙伴"的关键一步。

---

相关资源：

• Superpowers GitHub 仓库
• Jesse Vincent 的博客
• Superpowers Discord 社区
• Skills 市场

---

本文基于 Superpowers 2026 年 5 月版本撰写，框架持续快速迭代中，建议关注官方仓库获取最新动态。

---