uperpowers 是一套 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//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-.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 修复

13. /investigate ← gstack 工具辅助调查

14. /systematic-debugging ← Superpowers 方法论约束

15. /TDD (先写失败测试) ← Superpowers 确保质量

16. /verification ← Superpowers 验证修复

17. /ship ← gstack 发布
    场景 3：代码审查

18. /requesting-code-review ← Superpowers 生成审查请求

19. /review ← gstack 执行多维审查

20. /receiving-code-review ← Superpowers 处理反馈协议

21. 通用开发流程
    6.1 完整流程图

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

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