什么是 Superpowers？

Superpowers 是一套 Claude Code 插件技能集，专注于软件工程方法论的系统化。它将 TDD（测试驱动开发）、代码审查、系统调试等工程实践编码为可复用的 AI 工作流，确保 AI 编码助手遵循严格的工程纪律。

核心理念： 用规则约束 AI 行为，防止"快速但低质量"的代码输出。

1.2 什么是 gstack？

gstack 是一套全生命周期项目管理技能集，覆盖从产品构思到部署监控的完整开发流程。它提供 QA 测试、代码审查、设计审查、部署验证等自动化工作流。

核心理念： "Boil the Ocean"（把海水煮沸）— 既然 AI 边际成本趋近于零，就把每件事做到极致完整。

1.3 为什么要结合使用？

维度	Superpowers 贡献	gstack 贡献
规划	设计文档 + 实施计划模板	CEO/工程/设计多维审查
实现	TDD + 子代理驱动开发	自动化测试 + 浏览器 QA
审查	代码审查协议	多维审查军团 + 安全扫描
部署	完成分支管理	Ship + 部署 + 金丝雀监控
质量	验证即完成	设计审查 + 可访问性审计

---

2. 安装与配置

2.1 前置条件

检查项	要求
Node.js	>= 18
Git	>= 2.34
Claude Code CLI	已安装
GitHub CLI (gh)	已安装并认证
操作系统	macOS / Linux / Windows (WSL)

2.2 安装 Superpowers

Superpowers 作为 Claude Code 插件安装：

# 方法一：通过 Claude Code 插件市场安装（推荐）
claude plugins:install superpowers

# 方法二：手动安装
cd ~/.claude/plugins
git clone https://github.com/anthropics/superpowers.git

# 验证安装
claude skills:list | grep superpowers

安装完成后，技能文件位于：

~/.claude/plugins/cache/superpowers/superpowers/<version>/skills/
├── brainstorming/SKILL.md
├── dispatching-parallel-agents/SKILL.md
├── executing-plans/SKILL.md
├── finishing-a-development-branch/SKILL.md
├── receiving-code-review/SKILL.md
├── requesting-code-review/SKILL.md
├── subagent-driven-development/SKILL.md
├── systematic-debugging/SKILL.md
├── test-driven-development/SKILL.md
├── using-git-worktrees/SKILL.md
├── using-superpowers/SKILL.md
├── verification-before-completion/SKILL.md
├── writing-plans/SKILL.md
└── writing-skills/SKILL.md

2.3 安装 gstack

# 方法一：通过 setup 脚本安装（推荐）
cd ~/.claude/skills
git clone https://github.com/garryslist/gstack.git
cd gstack && ./setup

# 方法二：如果已有 Claude Code 环境，直接运行
cd ~/.claude/skills/gstack && ./setup --team

# 验证安装
ls ~/.claude/skills/gstack/SKILL.md

gstack 安装后的目录结构：

~/.claude/skills/gstack/
├── SKILL.md              # 主入口技能
├── bin/                  # CLI 工具集
├── browse/              # 无头浏览器引擎
├── sections/            # 各子流程详细步骤
└── ...

~/.claude/skills/         # gstack 子技能（独立目录）
├── spec/
├── ship/
├── qa/
├── investigate/
├── review/
├── design-review/
├── context-save/
├── context-restore/
├── autoplan/
├── office-hours/
├── land-and-deploy/
├── canary/
├── dev-workflow/
└── ...

2.4 配置 CLAUDE.md 路由规则

安装完成后，在项目根目录的 CLAUDE.md 中添加技能路由：

## Skill routing

When the user's request matches an available skill, invoke it via the Skill tool.

Key routing rules:
- 产品创意/头脑风暴     → /office-hours
- 策略/范围    → /plan-ceo-review
- 架构      → /plan-eng-review
- 设计系统/计划审查     → /design-consultation 或 /plan-design-review
- 全流程审查      → /autoplan
- Bug/错误     → /investigate
- QA/测试行为     → /qa 或 /qa-only
- 代码审查/diff 检查    → /review
- 视觉优化     → /design-review
- 发布/部署/PR    → /ship 或 /land-and-deploy
- 保存进度     → /context-save
- 恢复上下文      → /context-restore
- 撰写规格文档    → /spec

2.5 配置流程图

---

3. Superpowers 技能详解

3.1 技能总览

3.2 各技能详细说明

3.2.1 brainstorming（头脑风暴）

属性	说明
用途	在任何创意性工作之前进行需求探索和设计
触发	新功能、新组件、行为变更
硬性规则	设计批准前禁止任何实现代码

工作流：

探索项目上下文 → 逐一提问（单选题优先）→ 提出2-3个方案 → 分段展示设计 → 用户逐段批准 → 写入设计文档 → 过渡到 writing-plans

使用示例：

用户: 我想给系统加一个通知中心
AI: [调用 brainstorming] 让我先了解一下需求...
    1. 通知中心主要服务哪些用户？
    A) 内部运营  B) 终端用户  C) 两者都有

---

3.2.2 writing-plans（编写计划）

属性	说明
用途	将需求/设计文档转化为可执行的实施计划
触发	有了 spec 或需求，准备开始编码之前
硬性规则	禁止占位符（TBD、"类似任务N"等）

计划文件结构：

# 实施计划: [功能名称]

## Header
- Goal: [目标]
- Architecture: [架构描述]
- Tech Stack: [技术栈]
- Global Constraints: [全局约束]

## Task 1: [任务名]
### Step 1.1: Write failing test
- File: `src/tests/feature.test.ts`
- Expected: RED (test fails)
- Command: `npm test -- --grep "feature"`
- Expected output: "1 failing"

### Step 1.2: Implement minimal code
- File: `src/feature.ts`
- Expected: GREEN (test passes)
...

保存位置： docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md

---

3.2.3 test-driven-development（测试驱动开发）

属性	说明
用途	所有新功能、Bug 修复、重构的实现方法
触发	任何代码变更
铁律	没有失败测试，不写生产代码

Red-Green-Refactor 循环：

关键规则：

• 先写测试 → 运行确认失败（必须看到红色）
• 写最小代码 → 运行确认通过（必须看到绿色）
• 重构 → 保持测试通过
• 在测试之前写的代码 = 删除重来

---

3.2.4 systematic-debugging（系统化调试）

属性	说明
用途	任何 Bug、测试失败、异常行为的调查
触发	报错、异常、"为什么不工作"
铁律	不找到根因不修复

四阶段流程：

三振出局规则： 3次修复尝试失败 → 停止并质疑架构

---

3.2.5 subagent-driven-development（子代理驱动开发）

属性	说明
用途	将计划中的任务分派给独立子代理执行
触发	有计划、任务相对独立、需要并行
关键	每个任务一个代理 + 任务审查 + 全分支审查

执行模式：

---

3.2.6 verification-before-completion（完成前验证）

属性	说明
用途	任何"完成"声明之前的强制验证
触发	准备说"Done"、"Fixed"、"Passing"
铁律	没有新鲜的验证证据，不声明完成

门控函数：

识别证明命令 → 运行完整命令 → 读取完整输出 → 验证输出支持声明 → 才能声明

---

3.2.7 其他技能速查

技能	一句话说明	何时使用
using-superpowers	技能调度总控，确保正确技能被调用	每次对话开始
dispatching-parallel-agents	将独立任务并行分派给多个代理	3+ 独立故障
executing-plans	在当前会话中逐步执行计划	无子代理时
finishing-a-development-branch	分支完成后的合并/PR/清理	实现完毕
requesting-code-review	派遣审查子代理做代码审查	每个任务完成后
receiving-code-review	处理审查反馈的协议	收到审查意见
using-git-worktrees	创建隔离工作空间	开始新功能
writing-skills	用 TDD 方法编写新技能	创建/编辑技能

---

4. gstack 技能详解

4.1 技能总览