Superpowers + gstack 应用实践指南

版本: v1.0 | 日期: 2025-06-25 | 适用环境: Claude Code CLI / Desktop / Web

---

目录

1. 概述
2. 安装与配置
3. Superpowers 技能详解
4. gstack 技能详解
5. 两者结合使用
6. 通用开发流程
7. 通用开发流程 Skill
8. 最佳实践与注意事项

---

1. 概述

1.1 什么是 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 技能总览

4.2 核心技能详细说明

4.2.1 /office-hours（产品构思）

属性	说明
用途	YC 式产品办公时间，探索产品方向
触发	"我有个想法"、"这个值得做吗"、"帮我想想"
输出	设计文档（非代码）

两种模式：

• Startup Mode：六大逼问（需求真实性、现状、紧迫性、最窄切入点...）
• Builder Mode：生成式、鼓励性探索

使用示例：

用户: /office-hours 我想做一个 AI 驱动的客服机器人
AI: [启动 Startup Mode]
    让我问第一个问题：
    谁正在急迫地为这个问题付费或忍受痛苦？
    能否描述一个具体的用户和他们今天是怎么应对的？

---

4.2.2 /spec（规格文档）

属性	说明
用途	将模糊意图变为精确、可执行的规格
触发	"写个 ticket"、"提个 issue"、"规格化"
输出	GitHub Issue

五阶段流程：

---

4.2.3 /qa（QA 测试）

属性	说明
用途	系统化 QA 测试 Web 应用并修复 Bug
触发	"测试一下"、"QA"、"有没有 bug"
三层深度	Quick / Standard / Exhaustive

工作流：

初始化 → 认证 → 定向 → 逐页探索 → 截图取证 → 健康评分 → 分诊
→ 修复循环（定位→修复→提交→回测）→ 最终 QA → 报告

关键特性：

• 使用无头浏览器（不看源码，以用户视角测试）
• 每个修复一个原子提交
• 回归时自动 revert
• 每个 Issue 必须有截图证据
• 硬限 50 个修复

---

4.2.4 /investigate（Bug 调查）

属性	说明
用途	系统化根因调查
触发	"为什么坏了"、"debug"、"根因分析"
铁律	不找到根因不修复

与 Superpowers 的 systematic-debugging 完全互补：

• Superpowers 提供方法论框架
• gstack /investigate 提供工具支持（浏览器、代码搜索、学习记录等）

---

4.2.5 /ship（发布）

属性	说明
用途	自动化发布流程
触发	发布、创建 PR、ship it
特点	全自动，极少打断

21 步流水线：

---

4.2.6 /review（代码审查）

属性	说明
用途	着陆前代码审查
触发	审查代码、看看我的改动、code review
特色	多维并行审查军团

审查维度：

• SQL 安全性
• LLM 信任边界
• 竞态条件
• Shell 注入
• 枚举完整性
• 测试覆盖
• 可维护性
• 性能
• API 契约

---

4.2.7 /land-and-deploy（着陆部署）

属性	说明
用途	合并 PR + 等待部署 + 验证生产
触发	merge、deploy、land it
后续	自动触发 /canary

预检 → CI 检查 → 等待 CI → 预合并门控 → 合并 → 部署策略检测 → 等待部署 → 金丝雀验证 → 异常回滚 → 部署报告

---

4.2.8 /canary（金丝雀监控）

属性	说明
用途	部署后持续监控
触发	监控部署、post-deploy check
默认时长	10 分钟

监控内容：

• 控制台错误
• 性能回归（2x 基线 = 回归）
• 页面加载失败
• 截图对比

---

4.2.9 /context-save & /context-restore（上下文管理）

/context-save:  保存当前 git 状态 + 决策 + 剩余工作 → 检查点文件
/context-restore: 加载最近检查点 → 恢复工作上下文

使用场景： 切换分支、会话超时、跨天工作

---

5. 两者结合使用

5.1 职责分工图

5.2 对应关系表

开发阶段	Superpowers 技能	gstack 技能	结合方式
构思	/brainstorming	/office-hours	gstack 提供产品框架，Superpowers 确保设计先行
规划	/writing-plans	/autoplan	Superpowers 写计划，gstack 多维审查
隔离	/using-git-worktrees	—	Superpowers 管理 worktree 生命周期
实现	/TDD + /subagent-driven	—	严格 Red-Green-Refactor
调试	/systematic-debugging	/investigate	方法论 + 工具链双重保障
审查	/requesting/receiving-review	/review	Superpowers 定协议，gstack 跑军团
测试	/verification-before-completion	/qa	先 QA 黑盒测试，再白盒验证
发布	/finishing-a-branch	/ship	Superpowers 管分支，gstack 管流水线
部署	—	/land-and-deploy + /canary	gstack 全权负责
上下文	—	/context-save/restore	gstack 跨会话保存

5.3 典型结合场景

场景 1：新功能开发

1. /office-hours              ← gstack 产品探索
2. /brainstorming             ← Superpowers 设计先行
3. /writing-plans             ← Superpowers 编写计划
4. /autoplan                  ← gstack 全维度审查
5. /using-git-worktrees       ← Superpowers 创建隔离环境
6. /TDD (Red-Green-Refactor)  ← Superpowers 驱动实现
7. /requesting-code-review    ← Superpowers 派遣审查代理
8. /review                    ← gstack 审查军团
9. /verification              ← Superpowers 验证证据
10. /ship                     ← gstack 发布
11. /land-and-deploy          ← gstack 部署
12. /canary                   ← gstack 监控

场景 2：Bug 修复

1. /investigate               ← gstack 工具辅助调查
2. /systematic-debugging      ← Superpowers 方法论约束
3. /TDD (先写失败测试)         ← Superpowers 确保质量
4. /verification              ← Superpowers 验证修复
5. /ship                      ← gstack 发布

场景 3：代码审查

1. /requesting-code-review    ← Superpowers 生成审查请求
2. /review                    ← gstack 执行多维审查
3. /receiving-code-review     ← Superpowers 处理反馈协议

---

6. 通用开发流程

6.1 完整流程图

6.2 阶段门控条件

阶段	门控条件（必须满足才能进入下一阶段）
构思 → 规划	设计文档已写入并获用户批准
规划 → 隔离	计划通过 autoplan 审查
隔离 → 实现	工作树创建成功、测试基线通过
实现 → 审查	所有任务完成、测试通过
审查 → 验证	Critical 全修复、Important 全修复
验证 → 发布	QA 通过、验证证据收集完毕
发布 → 部署	PR 创建成功、CI 通过
部署 → 完成	金丝雀监控 HEALTHY

6.3 快速通道

对于简单任务，可跳过部分阶段：

任务复杂度	跳过的阶段	保留的阶段
Typo/Config (< 5 行)	构思、规划、隔离、审查军团	TDD、验证、发布
Bug Fix (已知根因)	构思	/investigate 确认→计划→实现→全流程
Hotfix (紧急修复)	构思、规划、隔离、金丝雀	TDD→验证→直接发布到 main
Feature (新功能)	无跳过	完整流程

---

## 7. 通用开发流程 Skill

以下是一个可直接使用的通用开发流程 Skill，结合了 Superpowers 和 gstack 的最佳实践：

```markdown
---
name: dev-workflow
description: >
  Full-cycle development workflow combining Superpowers discipline with gstack
  tooling. Use when starting a non-trivial feature, refactor, or fix that needs
  structured planning and verification. NOT for typos, trivial config, or pure
  research.
triggers:
  - new feature
  - start working on
  - build
  - implement
  - full workflow
  - 新功能
  - 开始开发
  - 完整流程
---

# Dev Workflow: Superpowers + gstack

## Stage Overview

8 gated stages. Each has a GATE condition — do not advance without meeting it.

## Stage 1: CLASSIFY

Determine task type and select the appropriate path:

| Type | Criteria | Path |
|------|----------|------|
| Trivial | < 10 lines, no behavior change | → Stage 4 (skip brainstorm/plan) |
| Bug Fix | Known symptoms, needs investigation | → /investigate → Stage 4 |
| Feature | New functionality or major refactor | → Stage 2 (full workflow) |
| Hotfix | Production-critical, time-sensitive | → Stage 4 (direct to main) |

## Stage 2: BRAINSTORM

**Tools:** Superpowers `brainstorming` + gstack `/office-hours`

1. Invoke `/office-hours` for product-level exploration
2. Apply `brainstorming` discipline:
   - Ask questions ONE at a time
   - Propose 2-3 approaches
   - Present design in sections, approve each
3. Write design doc to `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md`

**GATE:** Design document exists AND user has approved it.

## Stage 3: PLAN

**Tools:** Superpowers `writing-plans` + gstack `/plan-eng-review`

1. Write implementation plan following `writing-plans` rules:
   - Every step = 2-5 minutes
   - NO placeholders (TBD, "similar to...", "appropriate handling")
   - Each step: write test → run RED → implement → run GREEN → commit
2. Save to `docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md`
3. Run `/autoplan` for multi-dimensional review (or `/plan-eng-review` for eng-only)

**GATE:** Plan passes review (no blocking issues).

## Stage 4: ISOLATE

**Tools:** Superpowers `using-git-worktrees`

1. Check for existing isolation (native tools first)
2. Create worktree if needed: `EnterWorktree` or `git worktree add`
3. Install dependencies (auto-detect: npm/cargo/pip/go)
4. Run tests to establish clean baseline

**GATE:** Tests pass in the isolated workspace.

## Stage 5: IMPLEMENT

**Tools:** Superpowers `test-driven-development` + `subagent-driven-development`

For each task in the plan:

Rules:
- One task at a time (no batching)
- Must SEE red test output before writing implementation
- Must SEE green test output before committing
- If 3 attempts fail → STOP (systematic-debugging)

**GATE:** All tasks complete, all tests pass.

## Stage 6: REVIEW

**Tools:** Superpowers `requesting-code-review` + gstack `/review`

1. Dispatch code-reviewer subagent (Superpowers protocol)
2. Run `/review` for multi-dimensional review army
3. Process findings:
   - Critical → fix immediately
   - Important → fix before proceeding
   - Minor → note for later

**GATE:** Zero Critical/Important issues remaining.

## Stage 7: VERIFY

**Tools:** gstack `/qa` + Superpowers `verification-before-completion`

1. Run `/qa` (black-box testing via browser)
2. Apply `verification-before-completion`:
   - Identify proving command
   - Run it FRESH
   - Read FULL output
   - Confirm output proves claim
3. Collect evidence (screenshots, test output, logs)

**GATE:** QA passes + verification evidence collected.

## Stage 8: SHIP

**Tools:** gstack `/ship` + Superpowers `finishing-a-development-branch`

1. Run `/ship`:
   - Tests → Coverage → Version bump → CHANGELOG → Push → PR
2. Apply `finishing-a-development-branch`:
   - Present merge/PR/keep/discard options
   - Execute chosen path
   - Clean up worktree

**GATE:** PR created and CI green.

## Post-Ship (Optional)

- `/land-and-deploy` — merge + deploy + verify
- `/canary` — post-deploy monitoring (10 min)
- `/context-save` — save progress for cross-session work

## User Controls

| Command | Effect |
|---------|--------|
| `skip <stage>` | Skip a stage (with acknowledgment) |
| `back` | Return to previous stage |
| `pause` | Save context and stop |
| `abort` | Discard and clean up |

## Completion Status

- **SHIPPED** — PR created and/or deployed
- **VERIFIED** — All evidence collected, awaiting ship
- **BLOCKED** — Cannot proceed (state blocker)
- **PAUSED** — Context saved, ready to resume

---

8. 最佳实践与注意事项

8.1 最佳实践

#	实践	说明
1	永远设计先行	brainstorming / office-hours 在编码之前
2	永远测试先行	TDD Red-Green-Refactor 不可跳过
3	永远验证完成	看到证据才说 Done
4	永远隔离工作	worktree 保护 main 分支
5	永远原子提交	一个修复一个 commit
6	永远找根因	调试时不猜测，不"先试试"
7	定期保存	/context-save 防止丢失进度
8	信任工具	让 /review 和 /qa 做它们擅长的事

8.2 常见反模式

反模式	正确做法
"这个简单，不需要测试"	再简单也走 TDD
"我先写代码再补测试"	先写的代码必须删除
"应该修好了"	不看验证输出不算修好
"快速修一下"	先 /investigate 找根因
"直接在 main 上改"	用 worktree 隔离
"一次性提交所有改动"	每个逻辑单元一个 commit
"代码审查太慢了跳过"	审查是质量保障不是负担

8.3 技能调用速查表

示例	技能
"我有个想法"	→ /office-hours
"帮我规划一下"	→ /brainstorming → /writing-plans
"审查一下计划"	→ /autoplan
"开始写代码"	→ /using-git-worktrees → /TDD
"这里有个 bug"	→ /investigate + /systematic-debugging
"测试一下这个页面"	→ /qa
"看看我的代码"	→ /review + /requesting-code-review
"可以发布了"	→ /ship
"合并上线"	→ /land-and-deploy
"监控一下部署"	→ /canary
"保存进度，明天继续"	→ /context-save
"我之前做到哪了"	→ /context-restore

8.4 性能建议

• 使用子代理并行化：独立任务用 dispatching-parallel-agents
• 按需加载技能：不要一次性调用所有技能
• 利用 gstack 学习记录：/learn 可以避免重复踩坑
• 设置 proactive 模式：让 gstack 自动建议最合适的技能

---

附录 A：命令速查

命令	作用	所属
/office-hours	产品构思	gstack
/spec	写规格文档	gstack
/autoplan	全维度审查	gstack
/investigate	Bug 调查	gstack
/qa	QA 测试	gstack
/review	代码审查	gstack
/design-review	设计审查	gstack
/ship	发布 PR	gstack
/land-and-deploy	部署	gstack
/canary	部署监控	gstack
/context-save	保存上下文	gstack
/context-restore	恢复上下文	gstack
/cso	安全审查	gstack
/health	代码质量	gstack
/learn	学习记录	gstack
superpowers:brainstorming	头脑风暴	Superpowers
superpowers:writing-plans	写计划	Superpowers
superpowers:executing-plans	执行计划	Superpowers
superpowers:test-driven-development	TDD	Superpowers
superpowers:systematic-debugging	系统调试	Superpowers
superpowers:subagent-driven-development	子代理开发	Superpowers
superpowers:verification-before-completion	完成验证	Superpowers
superpowers:finishing-a-development-branch	分支完成	Superpowers
superpowers:requesting-code-review	请求审查	Superpowers
superpowers:receiving-code-review	接收审查	Superpowers
superpowers:dispatching-parallel-agents	并行代理	Superpowers
superpowers:using-git-worktrees	工作树	Superpowers

---

附录 B：官方仓库与文档

gstack 官方资源

资源	URL
GitHub 仓库	https://github.com/garrytan/gstack
架构文档 (ARCHITECTURE.md)	https://github.com/garrytan/gstack/blob/master/ARCHITECTURE.md
贡献指南 (CONTRIBUTING.md)	https://github.com/garrytan/gstack/blob/master/CONTRIBUTING.md
浏览器命令参考 (BROWSER.md)	https://github.com/garrytan/gstack/blob/master/BROWSER.md
版本日志 (CHANGELOG.md)	https://github.com/garrytan/gstack/blob/master/CHANGELOG.md
GBrain 集成指南	https://github.com/garrytan/gstack/blob/master/USING_GBRAIN_WITH_GSTACK.md
设计系统	https://github.com/garrytan/gstack/blob/master/DESIGN.md
OpenClaw 集成	https://github.com/garrytan/gstack/blob/master/docs/OPENCLAW.md
技能详解	https://github.com/garrytan/gstack/blob/master/docs/skills.md
远程浏览器访问	https://github.com/garrytan/gstack/blob/master/docs/REMOTE_BROWSER_ACCESS.md

Superpowers 官方资源

资源	URL
GitHub 仓库	https://github.com/obra/superpowers
Claude Code 开发辅助	https://github.com/obra/superpowers-developing-for-claude-code
实验技能实验室	https://github.com/obra/superpowers-lab
Superpowers 市场	https://github.com/obra/superpowers-marketplace

---

附录 C：参考文章

• Claude Code Superpowers 使用教程
• gstack 实战指南
• Superpowers + gstack 安装配置详解
• Claude Code gstack 技能深度解析

---

文档生成时间: 2025-06-25 | 基于 Superpowers v6.0.2 + gstack v1.27.x