Superpowers 项目解析

飞龙1477565746750
16 阅读7分钟

Superpowers 项目解析

一、项目概述

Superpowers 是一个为编码代理（如 Claude Code）设计的完整软件开发工作流系统，通过一套可组合的"技能"（Skills）和约束机制，确保代理能够系统化、高质量地完成软件开发任务。

核心特点

特点说明
零依赖插件本身不依赖任何第三方库
多平台支持兼容 Claude Code、Cursor、Codex、OpenCode、GitHub Copilot CLI、Gemini CLI
自动触发技能根据上下文自动激活，无需手动调用
强制流程通过约束机制确保流程严格执行

安装方式

# Claude Code 官方市场
/plugin install superpowers@claude-plugins-official

# Claude Code 自定义市场
/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplace

# Cursor
/add-plugin superpowers

# 更新
/plugin update superpowers

二、核心工作流程

Superpowers 定义了完整的软件开发流程：

需求澄清 → 头脑风暴 → 方案设计 → 任务拆解 → 分批执行 → 代码审查 → Git 提交

流程详解

阶段技能触发时机
头脑风暴brainstorming开始新的开发任务时
创建工作树using-git-worktrees设计批准后
编写计划writing-plans有了批准的设计后
执行任务subagent-driven-development有了计划后
测试驱动test-driven-development实现阶段
代码审查requesting-code-review任务之间
完成分支finishing-a-development-branch任务完成后

三、技能系统

3.1 技能目录结构

skills/
  skill-name/
    SKILL.md           # 主文件（必须有）
    helper.js          # 辅助脚本（可选）
    reference.md       # 详细文档（可选）

3.2 SKILL.md 文件格式

---
name: skill-name
description: Use when [触发条件]
---

# 技能标题

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

## When to Use
什么时候用，什么时候不用

## 具体步骤/内容
...

## Red Flags
- 如果出现这些情况，说明做错了

3.3 技能加载机制

会话启动
    ↓
加载所有技能的元数据（name + description）
    ↓
Claude 分析用户请求
    ↓
匹配技能描述 → 决定是否触发
    ↓
触发时：加载完整的 SKILL.md 内容
    ↓
技能内容成为 Claude 上下文的一部分
    ↓
Claude 遵循技能中的指令

3.4 技能优先级

1. 用户明确指令（CLAUDE.md、GEMINI.md、AGENTS.md）— 最高优先级
2. Superpowers 技能 — 覆盖默认系统行为
3. 默认系统提示 — 最低优先级

四、约束机制

Superpowers 使用多层约束机制确保流程严格执行。

4.1 硬性关卡 (HARD-GATE)

作用：阻止代理在满足条件前执行某些操作。

格式：

<HARD-GATE>
[禁止的操作] until [必须满足的条件]
</HARD-GATE>

示例（来自 brainstorming 技能）：

<HARD-GATE>
Do NOT invoke any implementation skill, write any code, scaffold any project, 
or take any implementation action until you have presented a design and the 
user has approved it.
</HARD-GATE>

设计原理：

  • XML 标签格式，视觉突出
  • 明确禁止 + 明确条件
  • 适用于所有情况，无例外

4.2 铁律 (Iron Law)

作用：定义不可违反的核心原则。

示例：

技能铁律
test-driven-developmentNO PRODUCTION CODE WITHOUT A FAILING TEST FIRST
systematic-debuggingNO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST

4.3 红标志 (Red Flags)

作用：帮助代理识别自己是否在合理化违反规则的行为。

格式：

## Red Flags - STOP and Start Over

- 违规行为1
- 违规行为2
- "合理化借口1"
- "合理化借口2"

**All of these mean: [纠正措施]**

示例（来自 test-driven-development 技能）：

## Red Flags - STOP and Start Over

- Code before test
- Test after implementation
- "I already manually tested it"
- "Tests after achieve the same purpose"
- "This is different because..."

**All of these mean: Delete code. Start over with TDD.**

4.4 约束机制对比

机制作用时机功能格式
HARD-GATE行动之前阻止操作发生XML 标签
Iron Law始终定义核心原则代码块
Red Flags行动过程中检测合理化行为列表/表格
NEVER/STOP特定条件禁止特定行为关键词

五、链式调用

5.1 概念

每个技能在完成后明确指定下一个要调用的技能，形成完整的流程链。

brainstorming → writing-plans → subagent-driven-development → finishing-a-development-branch

5.2 实现方式

方式 1：终端状态声明

**The terminal state is invoking writing-plans.** 
The ONLY skill you invoke after brainstorming is writing-plans.

方式 2：REQUIRED SUB-SKILL 标记

- **REQUIRED SUB-SKILL:** Use superpowers:finishing-a-development-branch

方式 3：检查清单

9. **Transition to implementation** — invoke writing-plans skill

方式 4：禁止列表

Do NOT invoke frontend-design, mcp-builder, or any other implementation skill.

5.3 流程图可视化

digraph brainstorming {
    "User reviews spec?" -> "Invoke writing-plans skill" [label="approved"];
}

六、会话启动机制

6.1 钩子配置

文件：hooks/hooks.json

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|clear|compact",
        "hooks": [
          {
            "type": "command",
            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" session-start",
            "async": false
          }
        ]
      }
    ]
  }
}

6.2 启动脚本

文件：hooks/session-start

功能：

  1. 读取 using-superpowers 技能内容
  2. 将内容注入到会话上下文中
  3. 确保代理从一开始就知道必须使用技能系统

七、如何添加新技能

7.1 创建步骤

1. 创建文件夹：skills/你的技能名/
2. 创建文件：SKILL.md
3. 写 YAML 头：name + description
4. 写内容
5. 测试
6. 提交

7.2 SKILL.md 模板

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

# Skill Name

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

## When to Use
- 适用场景
- 不适用场景

## The Process / Core Pattern
具体步骤或模式。

## Quick Reference
快速参考表格或列表。

## Common Mistakes
常见错误及修复方法。

## Red Flags
- 违规行为或合理化借口
- **纠正措施**

7.3 测试驱动开发（重要！）

RED 阶段（先测试失败）：
  1. 写压力测试场景
  2. 没有技能时运行 → 记录代理的错误行为
  3. 找出代理会用什么借口逃避规则

GREEN 阶段（写技能）：
  1. 写 SKILL.md
  2. 有技能时运行 → 验证代理现在遵守规则

REFACTOR 阶段（堵漏洞）：
  1. 找新的逃避借口
  2. 加红标志列表
  3. 再测试，直到无漏洞

7.4 检查清单

**RED Phase:**
- [ ] 创建压力场景
- [ ] 无技能运行，记录基线行为
- [ ] 识别合理化模式

**GREEN Phase:**
- [ ] 名称只用字母、数字、连字符
- [ ] YAML frontmatter 正确
- [ ] description 以 "Use when..." 开头
- [ ] description 用第三人称
- [ ] 有清晰的核心原则
- [ ] 有代码示例
- [ ] 有技能时运行通过

**REFACTOR Phase:**
- [ ] 识别新的合理化
- [ ] 添加红标志列表
- [ ] 再测试直到无漏洞

**Quality Checks:**
- [ ] 流程图（如果需要）
- [ ] 快速参考表
- [ ] 常见错误部分
- [ ] 无叙事性内容

**Deployment:**
- [ ] 提交到 git
- [ ] 考虑贡献回上游

八、技能库一览

测试类

技能说明
test-driven-developmentRED-GREEN-REFACTOR 循环

调试类

技能说明
systematic-debugging4 阶段根因分析
verification-before-completion确保问题真正解决

协作类

技能说明
brainstorming苏格拉底式设计提炼
writing-plans详细实现计划
executing-plans带检查点的批量执行
dispatching-parallel-agents并发子代理工作流
requesting-code-review预审查清单
receiving-code-review回应反馈
using-git-worktrees并行开发分支
finishing-a-development-branch合并/PR 决策工作流
subagent-driven-development两阶段审查的快速迭代

元技能

技能说明
writing-skills创建新技能
using-superpowers技能系统介绍

九、关键设计原理

9.1 说服心理学应用

原理应用
权威性MUST、NEVER、No exceptions 等权威语言
承诺一致性检查清单创建明确承诺，红标志暴露不一致
稀缺性强调违规的严重后果

9.2 测试驱动

  • 所有技能通过压力测试验证
  • 先记录失败行为，再写技能解决
  • 持续迭代堵漏洞

9.3 渐进式披露

  • 启动时只加载元数据
  • 触发时加载完整内容
  • 按需加载辅助文件

十、常见问题

Q: 硬性关卡是 Claude 的原生功能吗？

A: 不是。HARD-GATE 是 Superpowers 定义的设计模式，通过技能文档实现。Claude 会认真读技能内容并遵循其中的指令。

Q: 如何验证技能是否生效？

A: 启动新会话，提出应该触发技能的请求，观察代理是否遵循技能定义的流程。

Q: 可以修改现有技能吗？

A: 可以。技能文件就是普通的 Markdown 文件，可以直接编辑。但修改后需要重新测试验证。

Q: 如何贡献新技能？

A:

  1. Fork 仓库
  2. 创建技能分支
  3. 遵循 writing-skills 技能创建和测试
  4. 提交 PR

十一、参考资料

avatar
文章
阅读
粉丝