Superpowers

1. 项目简介

Superpowers 是为 AI 编程代理打造的完整软件开发工作流系统，建立在一组可组合的"技能"(Skills)之上，并配有初始指令确保代理正确使用这些技能。

核心特点

• 自动触发 - 技能根据上下文自动激活，无需手动调用
• 强制工作流 - 不是建议，而是必须遵循的流程
• 端到端覆盖 - 从需求澄清到代码审查的完整流程
• 子代理驱动 - 支持并行任务执行，代理可自主工作数小时

工作方式

当你启动编程代理时，它不会直接开始写代码。相反，它会：

1. 后退一步，询问你真正想要构建什么
2. 通过对话提炼出规格说明，分块展示便于理解
3. 在你批准设计后，制定清晰的实施计划（足够详细到"热情但缺乏经验的初级工程师"也能执行）
4. 启动子代理驱动开发流程，让代理逐个处理工程任务，审查并继续推进

2. 架构概述

2.1 基础工作流

Superpowers 定义了一个完整的开发流程，每个阶段对应一个或多个技能：

2.2 技能分类

3. 核心技能详解

3.1 brainstorming - 头脑风暴 Core

触发条件：任何创造性工作之前 - 创建功能、构建组件、添加功能或修改行为

流程

1. 理解想法：
   • 先查看当前项目状态（文件、文档、最近提交）
   • 一次一个问题细化想法（优先多选题）
   • 聚焦于：目的、约束、成功标准
2. 探索方案：
   • 提出2-3个不同方案及权衡
   • 以推荐方案开头并解释原因
3. 展示设计：
   • 分段展示（每段200-300词）
   • 每段后询问是否正确
   • 覆盖：架构、组件、数据流、错误处理、测试

关键原则

3.2 writing-plans - 编写计划 Core

触发条件：有规格或需求的多步骤任务，在接触代码之前

任务粒度

每个步骤是一个动作（2-5分钟）：

- "编写失败测试" - 一步
- "运行确认失败" - 一步
- "实现最小代码使测试通过" - 一步
- "运行测试确认通过" - 一步
- "提交" - 一步

任务结构模板

### 任务 N: [组件名称]

**文件:**
- 创建: `exact/path/to/file.py`
- 修改: `exact/path/to/existing.py:123-145`
- 测试: `tests/exact/path/to/test.py`

**步骤 1: 编写失败测试**
```python
def test_specific_behavior():
    result = function(input)
    assert result == expected
```

**步骤 2: 运行测试验证失败**
运行: `pytest tests/path/test.py::test_name -v`
预期: FAIL - "function not defined"

**步骤 3: 编写最小实现**
```python
def function(input):
    return expected
```

**步骤 4: 运行测试验证通过**
运行: `pytest tests/path/test.py::test_name -v`
预期: PASS

**步骤 5: 提交**
```bash
git add tests/path/test.py src/path/file.py
git commit -m "feat: add specific feature"
```

3.3 test-driven-development - 测试驱动开发 Testing

RED-GREEN-REFACTOR 循环

好测试的标准

常见合理化借口

3.4 systematic-debugging - 系统化调试 Debugging

四个阶段

阶段 1: 根因调查

1. 仔细阅读错误消息 - 不要跳过错误或警告，它们通常包含确切解决方案
2. 一致地复现 - 能可靠触发吗？确切步骤是什么？
3. 检查最近变更 - 什么改变可能导致这个？Git diff、最近提交、新依赖
4. 在多组件系统中收集证据 - 在每个组件边界添加诊断日志
5. 追踪数据流 - 坏值从哪里来？什么用坏值调用了这个？

阶段 2: 模式分析

• 在同一代码库中找到工作的类似代码
• 完整阅读参考实现（不要略读）
• 识别工作和损坏之间的差异

阶段 3: 假设和测试

• 形成单一假设："我认为X是根因，因为Y"
• 做最小可能的改变来测试假设
• 一次一个变量

阶段 4: 实现

• 创建失败测试用例（最简单的复现）
• 实现单一修复（解决识别的根因）
• 验证修复
• 如果3+次修复失败：质疑架构 - 这是架构问题，不是修复问题

3.5 subagent-driven-development - 子代理驱动开发 Collaboration

触发条件：在当前会话中执行有独立任务的实施计划

核心原则

每个任务派发新子代理 + 两阶段审查（规格合规，然后代码质量）= 高质量，快速迭代

流程

1. 读取计划 - 提取所有任务的完整文本，记录上下文，创建待办事项
2. 对于每个任务：
   • 派发实现者子代理
   • 实现者提问 → 回答问题，提供上下文
   • 实现者实现、测试、提交、自审
   • 派发规格审查者子代理 → 确认代码匹配规格
   • 派发代码质量审查者子代理 → 批准代码质量
   • 标记任务完成
3. 所有任务完成后 - 派发最终代码审查者，使用 finishing-a-development-branch

vs 其他方法的优势

3.6 using-git-worktrees - Git Worktree 使用 Collaboration

触发条件：开始需要与当前工作空间隔离的功能工作，或执行实施计划之前

目录选择优先级

1. 检查现有目录（.worktrees 或 worktrees）
2. 检查 CLAUDE.md 中的偏好设置
3. 询问用户选择项目本地还是全局位置

安全验证

对于项目本地目录，必须在创建工作树之前验证目录被忽略：

git check-ignore -q .worktrees 2>/dev/null

如果未被忽略：添加到 .gitignore，提交更改，然后继续。

创建步骤

# 1. 检测项目名
project=$(basename "$(git rev-parse --show-toplevel)")

# 2. 创建工作树
git worktree add "$path" -b "$BRANCH_NAME"
cd "$path"

# 3. 运行项目设置
if [ -f package.json ]; then npm install; fi
if [ -f requirements.txt ]; then pip install -r requirements.txt; fi

# 4. 验证干净基线
npm test  # 或项目适当的命令

3.7 dispatching-parallel-agents - 并行代理调度 Collaboration

触发条件：面对2+个独立任务，可以在没有共享状态或顺序依赖的情况下工作

使用时机

• 3+个测试文件有不同根因失败
• 多个子系统独立损坏
• 每个问题可以在不了解其他问题的情况下理解
• 调查之间没有共享状态

模式

1. 识别独立域 - 按损坏的内容分组失败
2. 创建聚焦的代理任务 - 每个代理获得：特定范围、明确目标、约束、预期输出
3. 并行派发
4. 审查和集成 - 阅读摘要，验证无冲突，运行完整测试套件

代理提示结构示例

修复 src/agents/agent-tool-abort.test.ts 中的3个失败测试：

1. "should abort tool with partial output capture" - 期望消息中有 'interrupted at'
2. "should handle mixed completed and aborted tools" - 快速工具被中止而非完成
3. "should properly track pendingToolCount" - 期望3个结果但得到0

这些是时序/竞态条件问题。你的任务：

1. 读取测试文件并理解每个测试验证什么
2. 识别根因 - 时序问题还是实际bug？
3. 修复方式：
   - 用基于事件的等待替换任意超时
   - 如果发现中止实现中的bug则修复
   - 如果测试的是已更改的行为则调整测试期望

不要只是增加超时 - 找到真正的问题。

返回：你发现了什么以及修复了什么的摘要。

3.8 代码审查技能 Collaboration

requesting-code-review - 请求代码审查

强制时机：

• 子代理驱动开发中每个任务之后
• 完成主要功能之后
• 合并到 main 之前

receiving-code-review - 接收代码审查

核心原则：技术评估，不是情感表演。实施前验证，假设前询问，技术正确性优于社交舒适。

响应模式

收到代码审查反馈时：

1. 阅读: 完整阅读反馈，不做反应
2. 理解: 用自己的话重述需求（或询问）
3. 验证: 对照代码库现实检查
4. 评估: 对这个代码库技术上是否合理？
5. 响应: 技术确认或有理由的反驳
6. 实现: 一次一项，每项都测试

禁止的响应

• ✗ "你完全正确！"
• ✗ "好观点！" / "优秀的反馈！"
• ✗ "让我现在就实现那个"（验证之前）

正确的响应

• ✓ "已修复。[简短描述更改内容]"
• ✓ "好发现 - [具体问题]。在 [位置] 修复。"
• ✓ [直接修复并在代码中展示]

3.9 verification-before-completion - 完成前验证 Debugging

门控函数

声称任何状态或表达满意之前：

1. 识别: 什么命令能证明这个声明？
2. 运行: 执行完整命令（新鲜、完整）
3. 阅读: 完整输出，检查退出码，计数失败
4. 验证: 输出确认声明吗？
   - 如果否: 陈述实际状态及证据
   - 如果是: 陈述声明及证据
5. 然后才能: 做出声明

跳过任何步骤 = 撒谎，不是验证

常见失败

3.10 finishing-a-development-branch - 完成开发分支 Collaboration

触发条件：实现完成，所有测试通过，需要决定如何集成工作

流程

1. 验证测试 - 如果测试失败，停止，不继续到第2步
2. 确定基础分支
3. 展示4个选项：
   1. 本地合并回基础分支
   2. 推送并创建 Pull Request
   3. 保持分支原样（稍后处理）
   4. 丢弃这项工作
4. 执行选择
5. 清理工作树（选项1、4清理；选项2、3保留）

3.11 writing-skills - 编写技能 Meta

核心理念：编写技能就是应用于流程文档的测试驱动开发。

TDD 映射到技能创建

SKILL.md 结构

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

# 技能名称

## 概述
这是什么？1-2句核心原则。

## 何时使用
[小型内联流程图，如果决策不明显]
带症状和用例的要点列表
何时不使用

## 核心模式（用于技术/模式）
前/后代码比较

## 快速参考
扫描常见操作的表格或要点

## 实现
简单模式的内联代码
重参考或可重用工具链接到文件

## 常见错误
什么出错了 + 修复方法

4. 安装配置

Claude Code（通过插件市场）

# 1. 注册市场
/plugin marketplace add obra/superpowers-marketplace

# 2. 安装插件
/plugin install superpowers@superpowers-marketplace

# 3. 验证安装
/help
# 应该看到:
# /superpowers:brainstorm - 交互式设计细化
# /superpowers:write-plan - 创建实施计划
# /superpowers:execute-plan - 批量执行计划

Codex

告诉 Codex：

Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.codex/INSTALL.md

OpenCode

告诉 OpenCode：

Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.opencode/INSTALL.md

更新

/plugin update superpowers

5. 使用示例

完整工作流示例

# 1. 用户提出需求
用户: "我想添加用户认证功能"

# 2. brainstorming 自动激活
代理: "我正在使用 brainstorming 技能来细化这个想法。
       你想支持哪种认证方式？
       1. 用户名/密码
       2. OAuth (Google, GitHub)
       3. 两者都要"

# 3. 设计完成后，设置工作空间
代理: "设计已保存到 docs/plans/2025-01-26-auth-design.md
       准备设置实施环境了吗？"
用户: "是"
代理: "我正在使用 using-git-worktrees 技能设置隔离工作空间。
       工作树就绪于 .worktrees/feature-auth
       测试通过（47个测试，0失败）
       准备好实施 auth 功能"

# 4. 创建实施计划
代理: "我正在使用 writing-plans 技能创建实施计划。"
      [生成详细计划，每个任务2-5分钟]
      "计划已保存到 docs/plans/2025-01-26-auth-implementation.md
       两种执行选项：
       1. 子代理驱动（当前会话）- 每个任务派发新子代理
       2. 并行会话（单独）- 在新会话中执行
       选哪个？"

# 5. 执行计划
用户: "1"
代理: "我正在使用 subagent-driven-development 技能执行计划。

       任务 1: 用户模型
       [派发实现者子代理]
       实现者: 实现完成，5/5测试通过，已提交
       [派发规格审查者]
       规格审查者: ✅ 规格合规
       [派发代码质量审查者]
       代码审查者: ✅ 批准
       任务 1 完成

       任务 2: 登录端点..."

# 6. 所有任务完成
代理: "我正在使用 finishing-a-development-branch 技能完成工作。
       测试通过（89个测试，0失败）

       实现完成。你想怎么做？
       1. 本地合并回 main
       2. 推送并创建 Pull Request
       3. 保持分支原样
       4. 丢弃这项工作"

6. 核心理念

铁律总结

"违反规则的字面意思就是违反规则的精神。"