gstack 入门：一人搞定产品设计、代码审查、QA 部署全流程

难度：入门 | 时长：15 分钟 | 收获：掌握 gstack 核心用法，理解 AI 编程工作流设计理念

---

目标读者

你已经会用 Claude Code 写代码，但总觉得一个人做产品时缺少"团队感"——没人帮你审视架构，没人跑 QA，没人替你把关设计。想把 AI 编程从「高级自动补全」升级成「真正的工程团队」？

这篇文章就是写给你的。我们会从安装开始，跑通一个完整的 /office-hours → /ship 工作流，让你亲身体会 gstack 是怎么把一个人变成一支部队的。

前置知识：有 Git 和命令行基础，了解 Claude Code 基本用法。

---

核心依赖与环境

仓库地址：https://github.com/garrytan/gstack

操作系统：macOS、Linux（Git Bash）、Windows 11（WSL 或 Git Bash）

---

完整项目结构

克隆到本地后，gstack 的核心目录结构如下：

gstack/
├── browse/                  # 持久化无头浏览器引擎（Playwright + 自定义 CDP 层）
│   ├── src/                 # CLI + HTTP 服务端 + 命令实现
│   └── dist/                # 编译后的单文件二进制（~58MB）
├── office-hours/            # YC 风格产品对话，启动所有流程的设计文档
├── plan-ceo-review/         # CEO 级产品策略审查（范围、定位、优先级）
├── plan-eng-review/         # 工程架构审查（数据流、状态机、测试计划）
├── plan-design-review/      # 设计审查（UI/UX 评分、Slop 检测）
├── design-consultation/     # 从零构建设计系统
├── review/                  # PR 代码审查（自动修复 + 问题分级）
├── investigate/             # 系统化根因调试（Iron Law：不调查不修复）
├── qa/                      # QA 测试 + 自动原子提交修复
├── qa-only/                # QA 报告模式（只报告，不改代码）
├── cso/                    # 首席安全官模式（OWASP Top 10 + STRIDE）
├── ship/                   # 发布工作流（同步 main → 测试 → 推送 → 开 PR）
├── land-and-deploy/        # 合并 PR → 部署 → 生产健康验证
├── canary/                 # 上线后监控循环（错误率、性能回归）
├── benchmark/              # 性能基准测试（Core Web Vitals、页面大小）
├── document-release/       # 发布后文档同步更新
├── retro/                  # 回顾会议（支持全局跨项目模式）
├── codex/                  # OpenAI Codex 第二意见（交叉模型分析）
├── browse/                 # 浏览器自动化（持久化 Chromium，~100ms/命令）
├── setup-browser-cookies/  # 从真实浏览器导入 Cookie（Chrome/Arc/Brave/Edge）
├── setup-deploy/           # 部署配置向导（检测平台、URL、命令）
├── careful/                # 危险命令警告（rm -rf / DROP TABLE 等）
├── freeze/                 # 锁定编辑范围，防止越界修改
├── guard/                  # careful + freeze 合一，等效最高安全模式
├── unfreeze/               # 解除 freeze
├── autoplan/               # 自动串联：CEO → 设计 → 工程 完整审查流程
└── bin/                    # CLI 工具集（gstack-config / gstack-analytics 等）

28 个技能，覆盖产品设计 → 架构审查 → 开发 → 安全 → QA → 部署 → 回顾的完整生命周期。

---

手把手步骤

Step 1 — 安装 gstack

全局安装（推荐）

打开 Claude Code，在对话框中粘贴以下命令，Claude 会自动完成剩余步骤：

git clone https://github.com/garrytan/gstack.git ~/.claude/skills/gstack && cd ~/.claude/skills/gstack && ./setup

./setup 脚本会：

1. 检测系统环境（Bun / Node / Git）
2. 编译 browse/dist/browse 二进制（bun build --compile，约 10 秒）
3. 注册所有 28 个技能到 Claude Code

安装完成后，你需要告诉 Claude Code 关于 gstack 的配置。把以下内容添加到项目根目录的 CLAUDE.md 文件：

## gstack
Use /browse from gstack for all web browsing. Never use mcp__claude-in-chrome__* tools.
Available skills: /office-hours, /plan-ceo-review, /plan-eng-review, /plan-design-review,
/design-consultation, /review, /ship, /land-and-deploy, /canary, /benchmark, /browse,
/qa, /qa-only, /design-review, /setup-browser-cookies, /setup-deploy, /retro,
/investigate, /document-release, /codex, /cso, /autoplan, /careful, /freeze, /guard,
/unfreeze, /gstack-upgrade.

项目级安装（让队友也能用）

如果希望团队成员 git clone 后自动获得 gstack：

cp -Rf ~/.claude/skills/gstack .claude/skills/gstack && rm -rf .claude/skills/gstack/.git && cd .claude/skills/gstack && ./setup

验证安装

# 检查二进制是否存在
ls ~/.claude/skills/gstack/browse/dist/browse

# 检查技能是否注册成功，Claude Code 中输入：
/help
# 应该在可用命令列表中看到 gstack 相关技能

---

Step 2 — 跑通第一个完整工作流

这是 gstack 的核心用法：5 条命令，覆盖产品设计到发布的全流程。我们在本地一个真实项目里操作一遍。

2.1 用 /office-hours 定义产品

/office-hours

gstack 会启动 YC Office Hours 模式——它会问你 6 个强制性问题，重新框定你的产品思路。关键是说出真实痛点，而不是直接描述功能。

示例对话：

你：我想要一个每天早上根据日历生成简报的功能。

gstack：我在重新审视你的框架。你说的是"简报生成器"，但实际上你描述的痛点是：
1. 多 Google 日历，信息陈旧
2. 准备时间太长
3. 结果不够好
你实际上在构建的是一款"个人首席助理 AI"。

要不要重新定义范围？或者告诉我为什么原始范围是对的？

设计对话结束后，gstack 会生成一份设计文档，自动流向后续的审查技能。

2.2 用 /plan-ceo-review 审查产品策略

/plan-ceo-review

gstack 读取上一步的设计文档，从 CEO/创始人视角做四象限审查：

• 扩张：把范围扩大到哪里？
• 选择性扩张：保留核心，砍掉哪些？
• 维持范围：现在的大小刚刚好
• 缩减：聚焦最窄切入点

它还会给出 3 种实现路径，每种标注人天 + AI 时间对比：

2.3 用 /review 审查代码

代码写好后，在分支上运行：

/review

gstack 会：

• 自动修复明显问题（如未处理边界条件）
• 对复杂问题弹出 AskUserQuestion 征求你的意见
• 输出分级报告：[AUTO-FIXED] / [ASK] / [WARN]

示例输出：

[/review] 分析完成：

[AUTO-FIXED] 2 处
  - src/api/calendar.ts:67 — 缺少 Promise reject 处理
  - src/utils/date.ts:12 — 时区偏移硬编码

[ASK] Race condition in refresh loop — 推荐修复方案：
A) 加 mutex lock（更安全，+15 行）
B) 加 debounce（更简单，+5 行）
推荐 A，全面处理并发场景。

2.4 用 /qa 测试你的应用

# 替换成你的 staging 地址
/qa https://staging.myapp.com

gstack 的 /qa 会启动持久化 Chromium 浏览器（复用 Cookie 和登录态），自动：

1. 打开页面，截图
2. 点击关键路径（登录 → 核心功能 → 边界场景）
3. 发现 bug → 原子提交修复 → 重新验证
4. 为每个修复生成回归测试

与普通自动化测试的区别：普通测试跑的是你写好的断言。/qa 会主动寻找你没写断言的场景——空状态、错误状态、并发边界。

2.5 用 /ship 发布

/ship

/ship 执行完整的发布流水线：

# 等效手动操作：
git checkout main && git pull
git merge your-branch
pnpm test           # 或你的测试命令
pnpm build
git push
gh pr create        # 自动打开 PR，包含变更摘要

每个环节有检查清单，通过才继续。遇到问题会停在你面前，等你决策。

---

Step 3 — 按阶段深入核心技能

3.1 设计阶段：office-hours 与 plan 系列

这一阶段的核心是把"想法"变成"设计文档"，让后续所有步骤都能读取。

/office-hours — 不是头脑风暴，是产品重新框架化。gstack 会：

• 识别你没说出口的真实需求（从描述的痛点反推）
• 挑战你默认的假设
• 生成有具体里程碑的实现路径

/plan-ceo-review — 读设计文档，从市场规模、竞争格局、优先级做判断。

/plan-eng-review — 锁定技术架构：

• ASCII 数据流图
• 状态机设计
• 失败路径分析
• 测试矩阵（每个分支至少一个测试）

3.2 开发阶段：review 与 investigate

/review 的核心逻辑是"找到 CI 通过但生产会爆炸的 bug"。它不替代 linter，而是做语义分析：

• 逻辑错误（条件遗漏、分支不平衡）
• 并发问题（race condition、deadlock 模式）
• 安全风险（注入、认证绕过）

/investigate 是调试专用。当某个 bug 反复出现，运行：

/investigate

gstack 会：

1. 提出假设
2. 逐个验证（不修复，只调查）
3. 找到根因后停止（Iron Law：没有调查就没有修复）

3.3 发布阶段：ship、land-and-deploy、canary

/ship          # 代码审查通过后 → 开 PR
/land-and-deploy  # 合并 PR → 部署 → 验证生产健康
/canary        # 部署后持续监控 30 分钟

/canary 会监控三个指标：

• Console 错误率：JavaScript 异常是否上升
• 性能回归：Core Web Vitals 是否变差
• 页面失败率：关键页面是否 500

任一指标异常，自动告警并可触发回滚。

---

Step 4 — 浏览器自动化实战

/browse 是 gstack 最独特的能力：它运行一个长驻 Chromium 进程，通过本地 HTTP API 接收命令，平均 ~100ms 响应，支持真正的登录态复用。

4.1 基本使用

# 打开一个页面
$B goto https://example.com

# 查看可交互元素（自动编号 @e1, @e2 ...）
$B snapshot -i

# 点击第 3 个元素
$B click @e3

# 填表单
$B fill @e1 "[email protected]"
$B fill @e2 "password123"

# 截图
$B screenshot /tmp/result.png

4.2 验证 UI 变更

# 基准快照
$B snapshot -i

# 做操作
$B click @e5

# 差异对比（只显示变化的部分）
$B snapshot -D

-D flag 输出 unified diff 格式，告诉你操作后哪些元素出现了、消失了、变了内容。

4.3 测试登录态

从真实浏览器导入 Cookie：

# 交互式选择器（macOS 支持 Chrome / Arc / Brave / Edge）
$B cookie-import-browser

# 直接指定域名
$B cookie-import-browser chrome --domain .github.com

4.4 响应式测试

# 同时生成手机 / 平板 / 桌面三张截图
$B goto https://yourapp.com
$B responsive /tmp/layout
# 输出：layout-mobile.png, layout-tablet.png, layout-desktop.png

---

Step 5 — 团队协作与进阶

5.1 Vendored 安装详解

全局安装适合个人使用，Vendored 安装让团队共享：

# 在项目根目录执行
git clone https://github.com/garrytan/gstack.git .claude/skills/gstack
cd .claude/skills/gstack
./setup

关键点：

• 安装的是快照，不是 submodule
• .git 目录被删除，所以不会污染你的仓库历史
• 升级：每个成员 pull 最新后重跑 ./setup

5.2 并行 Sprint 与 Conductor

gstack 的结构设计天然支持并行。单个 Claude Code 是一个"人"，但多个 Claude Code 实例可以并行跑不同的 Sprint 阶段。

gstack 官方推荐的 Conductor 可以同时启动多个 Claude Code 实例，每个在独立 workspace 中跑：

• 实例 A：/office-hours 重新定义产品
• 实例 B：实施某个特性
• 实例 C：/review 审查另一个分支
• 实例 D：/qa 测试 staging 环境

所有实例共享同一个 Git 仓库。 不会产生冲突——Git 的分支模型天然隔离。

5.3 安全模式

处理生产代码时，开启安全护栏：

/guard   # = /careful + /freeze

• /careful：危险命令（rm -rf、DROP TABLE、git push --force）会弹出确认
• /freeze：限制文件编辑范围到指定目录，防止调试时误改生产代码
• /unfreeze：解除 freeze

---

常见问题排查

1. 技能不显示

# 进入 gstack 目录，手动运行 setup
cd ~/.claude/skills/gstack && ./setup

如果二进制编译失败，检查 Bun 版本：

bun --version  # 需要 v1.0+

macOS/Linux 安装问题：

# 确保目录存在
mkdir -p ~/.claude/skills/

# 确保有执行权限
chmod +x ~/.claude/skills/gstack/setup

2. /browse 启动失败

# 手动构建二进制
cd ~/.claude/skills/gstack/browse
bun install
./setup

如果 Bun 版本过低：

# 升级 Bun
curl -fsSL https://bun.sh/install | bash

3. Codex 报错 "Skilled loading invalid"

Codex 的技能描述缓存过期了。修复：

# 全局安装的 Codex
cd ~/.codex/skills/gstack && git pull && ./setup --host codex

# Vendored 安装的 Codex
cd "$(readlink -f .agents/skills/gstack)" && git pull && ./setup --host codex

4. Windows 兼容问题

gstack 在 Windows 上依赖 WSL 或 Git Bash（不是 PowerShell）。确保：

# 在 Git Bash 或 WSL 中运行
# Bun 和 node 都要在 PATH 中
which bun   # 应有输出
which node  # 应有输出

Windows 上 Playwright 有一个已知 bug（bun#4253），gstack 会自动回退到 Node.js 执行。

5. Cookie 导入失败

Cookie 导入仅支持 macOS（使用系统 Keychain）。Linux 和 Windows 目前不支持。

如果你在 Linux 上测试需要登录态的页面，可以手动导出 Cookie 为 JSON：

[
  {"name": "session_token", "value": "...", "domain": ".example.com", "path": "/"}
]

然后用：

$B cookie-import /path/to/cookies.json

6. 版本升级

# 方式一：运行升级技能
/gstack-upgrade

# 方式二：手动拉取最新代码
cd ~/.claude/skills/gstack && git pull && ./setup

gstack-upgrade 会检测是全局安装还是 Vendored 安装，并分别处理。

---

扩展阅读 / 进阶方向

ETHOS.md — gstack 的核心理念文档。"Boil the Lake"（沸腾湖泊）原则：AI 让完整实现的边际成本接近零，不要选择"够用就行"。还有 "Search Before Building"：三层知识体系——已验证方案（Layer 1）、流行新方案（Layer 2）、第一性原理（Layer 3）。

Autoplan — 一条命令自动串联 CEO 审查 → 设计审查 → 工程审查的完整流程。如果你不想逐个调用技能，直接 /autoplan，它会按正确顺序依次运行所有 plan，编码决策会在关键节点弹出等你确认。

Conductor — gstack 官方的多会话并行管理工具。将多个 Claude Code 实例组织成真正的 AI 工程团队，适合同时推进多个功能的情况。

源码阅读路线：

1. browse/src/commands.ts — 所有浏览器命令的注册表，单一事实来源
2. browse/src/snapshot.ts — Ref 系统的核心实现（ARIA 树 → Playwright Locator）
3. scripts/gen-skill-docs.ts — SKILL.md 自动生成管道
4. ARCHITECTURE.md — 完整架构设计文档

---