gstack 深度指南

gstack 是一套面向 Claude Code、Codex 等 Coding Agent 的工程工作流，把“需求澄清、计划评审、代码审查、浏览器 QA、发布检查”做成可复用命令。

是什么

普通 Coding Agent 很擅长直接写代码，但真实项目不只需要代码。你还需要确认需求是否值得做、方案是否过度、测试是否覆盖、页面是否真的可用、发布前是否遗漏风险。

gstack 的思路是把这些环节拆成不同角色和命令，让 Agent 不再只扮演“写代码的人”，而是按一个小型软件团队的流程工作。

官方地址

类型	地址
官网	https://gstack.lol/
官方 GitHub	https://github.com/garrytan/gstack

典型流程是：

想法澄清 -> 计划评审 -> 实现 -> 代码审查 -> 浏览器 QA -> 发布 -> 复盘

适用场景

场景	是否推荐
想让 Claude Code / Codex 不只是写代码，还能参与产品和工程评审	推荐
项目有前端页面，需要真实浏览器 QA	推荐
团队希望统一 Agent 使用流程	推荐
只想体验一次简单问答	不必安装
不能接受工具改写本机 Agent 配置	先用项目级安装或暂缓

安装准备

安装前建议具备：

环境	检查命令	说明
Git	git --version	克隆和更新 gstack
Claude Code 或 Codex	claude --version / codex --version	作为宿主 Agent
项目测试命令	npm test / npm run build	方便 /review、/qa 验证结果
浏览器环境	Chrome / Chromium	浏览器 QA 相关流程可能需要

安装方式

Claude Code 插件安装

Claude Code 是 gstack 最核心的使用目标。官方插件路径可以直接在 Claude Code 里执行：

/plugin install gstack@claude-plugins-official

如果你希望只在当前项目启用：

/plugin install gstack@claude-plugins-official --project-scoped

Claude Code 手动安装

手动安装适合想看清楚文件落点、或者需要从仓库版本更新的人：

git clone --single-branch --depth 1 https://github.com/garrytan/gstack.git ~/.claude/skills/gstack
cd ~/.claude/skills/gstack
./setup

Codex 安装

Codex 需要显式指定 host：

git clone --single-branch --depth 1 https://github.com/garrytan/gstack.git ~/gstack
cd ~/gstack
./setup --host codex

安装后通常会把相关 skill 放到：

~/.codex/skills/gstack-*/

Team Mode

如果你希望把 gstack 作为团队标准，而不是只装在个人机器上，可以在项目里初始化 team mode：

(cd ~/.claude/skills/gstack && ./setup --team) && ~/.claude/skills/gstack/bin/gstack-team-init required

这种方式会影响项目级配置，适合团队明确决定统一使用 gstack 时再做。

核心目录和机制

位置	作用
~/.claude/skills/gstack	Claude Code 手动安装目录
~/.codex/skills/gstack-*	Codex host 的 skill 安装目录
~/.gstack/	gstack 全局状态、配置、运行数据
.gstack/	项目级 gstack 配置，team mode 可能使用
.gstack-worktrees/	工作树相关临时目录，取决于工作流配置

gstack 的重点不是某个单独命令，而是命令之间的顺序。前一个命令产生的上下文，会给后面的命令提供更好的输入。

命令大全

下面列出常见命令。具体命令数量和名称会随版本变化，实际使用时以官方 README 和本机安装结果为准。

命令	作用	示例	注意事项
/office-hours	澄清需求，重新定义问题和产品切入点	/office-hours	适合在编码前使用
/plan-ceo-review	从产品和商业角度挑战计划	/plan-ceo-review	防止做一个“能做但不值得做”的版本
/plan-eng-review	从架构、数据流、测试角度审查计划	/plan-eng-review	适合复杂功能开发前
/plan-design-review	从交互和视觉角度审查方案	/plan-design-review	前端页面、工具界面更适合
/review	审查当前分支代码风险	/review	关注 bug、回归、缺测试
/qa	打开真实浏览器做 QA	/qa	前端项目最好先启动本地服务
/ship	发布前检查	/ship	不等于自动替你发布生产
/retro	复盘本次工作	/retro	适合沉淀经验和改进流程
/gstack-upgrade	升级 gstack	/gstack-upgrade	如果插件安装可优先用插件更新方式

推荐工作流

新功能开发

/office-hours
  -> /plan-ceo-review
  -> /plan-eng-review
  -> 让主力 Agent 实现
  -> /review
  -> /qa
  -> /ship

Bug 修复

先让 Agent 复现问题
  -> /plan-eng-review
  -> 修复
  -> /review
  -> 跑测试

前端页面调整

/plan-design-review
  -> 实现 CSS / 组件
  -> /qa
  -> 截图检查

与 Claude Code、Codex、Gemini 的关系

gstack 不是模型，也不是独立 IDE。它更像“工作流增强层”：

宿主	支持状态	说明
Claude Code	主要目标	插件和手动安装路径都比较成熟
Codex	支持	使用 ./setup --host codex
Gemini CLI	需看当前官方说明	不同版本扩展机制可能变化

安全建议

• 安装前先看官方仓库和 README，确认命令来源。
• team mode 会影响项目级配置，团队项目不要私自启用。
• /qa、/ship 这类命令可能运行浏览器或项目命令，先确认本地服务和环境变量。
• 不要让 Agent 自动执行生产发布、强推、删除数据等操作。
• 安装后用 git status 检查项目是否出现新的配置文件。

排错

命令没有出现

先重启宿主 Agent。很多插件、skill、slash command 都是在启动时扫描。

Claude Code 手动安装可尝试：

cd ~/.claude/skills/gstack
./setup

Codex 可检查：

ls ~/.codex/skills

Codex 提示 SKILL.md 无效

重新拉取并执行 setup：

cd ~/.codex/skills/gstack
git pull
./setup --host codex

如果你的实际 clone 在 ~/gstack，就进入那个目录执行。

想卸载

优先使用官方卸载脚本：

~/.claude/skills/gstack/bin/gstack-uninstall

手动清理要谨慎，尤其是项目级 .gstack 和工作树目录，确认不再需要后再删。

总结

gstack 的价值在于把“让 Agent 写代码”升级为“让 Agent 参与工程交付流程”。如果你已经开始用 Claude Code 或 Codex 做真实项目，gstack 值得尝试；如果你还没熟悉主力 Agent，建议先把基础命令和权限机制学会，再引入这套工作流。