# Superpowers 安裝與使用筆記

## 基本資訊

- **專案**: https://github.com/obra/superpowers
- **作者**: Jesse Vincent（obra）/ Prime Radiant
- **授權**: MIT
- **類型**: Claude Code / Cursor / Gemini CLI / GitHub Copilot CLI 外掛
- **用途**: 為編碼代理（coding agent）提供結構化開發方法論的可組合 skills
- **官方社群**: Discord、GitHub Issues、primeradiant.com/superpowers
- **安裝日期**: 2026-04-19

## 是什麼

Superpowers 是一套專為 AI 編碼代理設計的軟體開發方法論框架。它不讓代理直接寫程式，而是透過一組可組合（composable）的 skills，引導代理依序走完設計、規劃、實作、測試、審查等階段，內建品質檢查點。

核心理念：
- 系統化優先於臨時應變（Systematic over ad-hoc）
- 以測試驅動開發（TDD）為基礎
- 降低複雜度，追求簡單
- 用證據驗證，而非假設

## 安裝

### Claude Code（官方 Marketplace，推薦）

在 Claude Code 對話中執行：

```text
/plugin install superpowers@claude-plugins-official
```

本機 `claude-plugins-official` marketplace 已位於：
`~/.claude/plugins/marketplaces/claude-plugins-official/`

### Claude Code（Superpowers 自家 Marketplace）

```text
/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplace
```

### Cursor

```text
/add-plugin superpowers
```

### GitHub Copilot CLI

```bash
copilot plugin marketplace add obra/superpowers-marketplace
copilot plugin install superpowers@superpowers-marketplace
```

### Gemini CLI

```bash
gemini extensions install https://github.com/obra/superpowers
gemini extensions update superpowers          # 更新
```

## 核心工作流程（七個階段）

1. **Brainstorming（腦力激盪）** — 透過發問釐清需求與目標
2. **Git Worktrees** — 建立隔離的開發分支
3. **Planning（規劃）** — 將工作切成 2–5 分鐘、junior 開發者可執行的小任務
4. **Implementation（實作）** — 以 subagent 執行，搭配兩階段 review
5. **Testing（測試）** — 強制 red-green-refactor TDD 循環
6. **Code Review** — 對照規格驗證實作
7. **Completion（收尾）** — 合併或歸檔

## Skills 清單

### 測試與品質
- TDD（RED-GREEN-REFACTOR）
- 系統化除錯（4 階段根因分析）
- 完成前驗證（verification before completion）

### 規劃與協作
- Brainstorming 與設計精煉
- 撰寫詳細實作計畫
- 依計畫執行並設檢查點
- Subagent 驅動開發 + 兩階段審查
- Code review 請求／回覆流程
- Git worktree 管理
- 開發分支收尾

### Meta
- 撰寫符合最佳實務的新 skill
- Skills 系統入門

## 使用方式

安裝完成後，在 Claude Code 中 skills 會依對話情境自動啟用。也可以用 `/` 查看並手動觸發特定 skill。

進入典型開發任務時，Superpowers 會先要求對話釐清需求、產出 design doc，再分解任務、建立 worktree，接著才真正開始寫 code。

## 常用檢查指令

```bash
# 檢查 marketplace
ls ~/.claude/plugins/marketplaces/

# 看哪些 marketplace 已加入
cat ~/.claude/plugins/known_marketplaces.json

# 看 superpowers 是否在 marketplace 清單
grep -l "superpowers" ~/.claude/plugins/marketplaces/claude-plugins-official/.claude-plugin/marketplace.json
```

## 備註

- Superpowers 的設計偏好「先對齊再寫 code」，如果你要的是快速一次性 hack，它可能會顯得繁瑣；適用於需要品質與可維護性的正式任務。
- 方法論強調由人類確認設計稿再進入實作，互動次數會比裸 agent 多。