GStack Setup, Deployment, and Practical Guide

With Key Considerations

GStack 建置部署與實戰注意事項完全指南

從環境準備到生產級工作流

GStack turns Claude Code into a full product-engineering team — but only if you set it up correctly. This guide covers every step, every gotcha, and every decision you'll face along the way.

GStack 能把 Claude Code 變成一整個產品工程團隊——但前提是你得正確設定它。本指南涵蓋每一個步驟、每一個陷阱，以及你在過程中會面對的每一個決策。

Why GStack?

Claude Code is powerful on its own. You can write code, debug issues, and refactor files. But it operates in a reactive mode — you ask, it answers. GStack changes that dynamic entirely.

GStack is an open-source skill pack created by Garry Tan that installs nine slash commands into Claude Code. Together, these commands form a sprint workflow — a structured process that takes you from product idea to shipped PR, with strategic review, architecture planning, code auditing, browser-based QA, and retrospective baked in.

What GStack gives you that vanilla Claude Code doesn't:

A structured product development workflow (not just code completion)
CEO-level strategic review before you write a single line
Architecture design review that catches structural issues early
Automated browser-based QA testing
A release workflow that creates PRs and handles shipping
Retrospectives that help you improve sprint over sprint

Who should use this guide:

Developers who already use Claude Code and want a structured sprint workflow
Solo founders building products and wanting AI-assisted product thinking
Teams evaluating GStack for adoption across projects

為什麼選 GStack？

Claude Code 本身就很強大。你可以寫程式碼、除錯、重構檔案。但它以被動模式運作——你問，它答。GStack 徹底改變了這種互動方式。

GStack 是由 Garry Tan 建立的開源 skill 套件，它在 Claude Code 中安裝了九個 slash command。這些指令組合在一起，形成一套完整的 Sprint 工作流——一個結構化流程，帶你從產品構想走到發佈 PR，其中內建了策略審查、架構規劃、程式碼審計、瀏覽器 QA 測試和回顧。

GStack 能給你而原生 Claude Code 做不到的事：

結構化的產品開發工作流（不只是程式碼補全）
在你寫任何一行程式碼之前，就進行 CEO 層級的策略審查
架構設計審查，在早期就抓住結構性問題
自動化的瀏覽器 QA 測試
建立 PR 並處理發佈的 release 工作流
幫助你逐次改進 sprint 的回顧機制

誰應該讀這份指南：

已在使用 Claude Code、想要結構化 sprint 工作流的開發者
獨立建構產品、想要 AI 輔助產品思維的 solo founder
正在評估 GStack 以在團隊中推廣的技術主管

1. Prerequisites Checklist

Before you begin, verify every item on this list. A missing dependency will cause cryptic errors later.

Requirement	Minimum Version	Check Command	Notes
macOS or Linux	macOS 12+ / Ubuntu 20.04+	`uname -a`	Windows via WSL2 may work but is unsupported
Architecture	x64 or arm64	`uname -m`	Apple Silicon (M1/M2/M3/M4) is arm64
Git	2.30+	`git --version`	Needed for cloning and branch operations
Bun	1.0+	`bun --version`	GStack's runtime — not Node, not Deno
Claude Code CLI	Latest	`claude --version`	Must be authenticated (`claude auth`)
Active git repo	—	`git status`	GStack operates within git repositories

Installing Missing Dependencies

Bun (if not installed):

bash

curl -fsSL https://bun.sh/install | bash

After installation, restart your terminal or run:

bash

source ~/.bashrc  # or ~/.zshrc on macOS

Verify:

bash

bun --version
# Expected: 1.x.x

Claude Code CLI (if not installed):

bash

npm install -g @anthropic-ai/claude-code

Then authenticate:

bash

claude auth

Follow the prompts to connect your Anthropic account.

Pre-Flight Verification Script

Run this to check everything at once:

bash

echo "=== GStack Pre-Flight Check ==="
echo "OS: $(uname -s) $(uname -m)"
echo "Git: $(git --version 2>/dev/null || echo 'NOT FOUND')"
echo "Bun: $(bun --version 2>/dev/null || echo 'NOT FOUND')"
echo "Claude: $(claude --version 2>/dev/null || echo 'NOT FOUND')"
echo "================================"

All four should show version numbers. If any shows NOT FOUND, install it before proceeding.

1. 環境需求檢查清單

在開始之前，請逐一確認以下所有項目。遺漏的依賴會在後續引發難以理解的錯誤。

需求	最低版本	檢查指令	備註
macOS 或 Linux	macOS 12+ / Ubuntu 20.04+	`uname -a`	Windows 透過 WSL2 可能可行但不受官方支援
架構	x64 或 arm64	`uname -m`	Apple Silicon（M1/M2/M3/M4）為 arm64
Git	2.30+	`git --version`	用於 clone 和分支操作
Bun	1.0+	`bun --version`	GStack 的 runtime——不是 Node，不是 Deno
Claude Code CLI	最新版	`claude --version`	必須已認證（`claude auth`）
活躍的 git repo	—	`git status`	GStack 在 git 倉庫中運作

安裝缺少的依賴

Bun（若未安裝）：

bash

curl -fsSL https://bun.sh/install | bash

安裝後，重新啟動終端機或執行：

bash

source ~/.bashrc  # macOS 上是 ~/.zshrc

驗證：

bash

bun --version
# 預期輸出：1.x.x

Claude Code CLI（若未安裝）：

bash

npm install -g @anthropic-ai/claude-code

然後進行認證：

bash

claude auth

按照提示連接你的 Anthropic 帳號。

預檢腳本

執行這段腳本一次性檢查所有依賴：

bash

echo "=== GStack Pre-Flight Check ==="
echo "OS: $(uname -s) $(uname -m)"
echo "Git: $(git --version 2>/dev/null || echo 'NOT FOUND')"
echo "Bun: $(bun --version 2>/dev/null || echo 'NOT FOUND')"
echo "Claude: $(claude --version 2>/dev/null || echo 'NOT FOUND')"
echo "================================"

四項都應該顯示版本號。如果任何一項顯示 NOT FOUND，在繼續之前先安裝它。

2. Installation

GStack supports two installation modes: global (shared across all projects) and per-project (scoped to a single repository). Choose based on your needs.

Option A: Global Installation (Recommended)

Global installation places GStack in Claude Code's shared skills directory. Every project on your machine can access it.

bash

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

What this does, step by step:

Clones the GStack repository into ~/.claude/skills/gstack/
Changes into that directory
Runs the setup script, which:
- Installs the Chromium binary for browser automation (~58 MB)
- Registers the nine slash commands with Claude Code
- Configures file paths and permissions

Expected output:

Cloning into '/Users/you/.claude/skills/gstack'...
...
✓ Browser binary installed
✓ Skills registered
✓ Setup complete

Option B: Per-Project Installation

Use this when you want GStack available only within a specific project, or when different projects need different GStack versions.

bash

# First, ensure you have the global clone (or clone to a temp location)
git clone https://github.com/garrytan/gstack.git /tmp/gstack

# Copy into your project
cp -r /tmp/gstack /path/to/your-project/.claude/skills/gstack

# Run setup from within the project
cd /path/to/your-project/.claude/skills/gstack && ./setup

When to choose per-project:

You work on projects with different GStack versions
Your team requires reproducible setups (GStack committed to the repo)
You want to customize GStack's behavior per project
Corporate environments where global installs are restricted

Verifying the Installation

After either installation method, verify the directory structure:

bash

ls -la ~/.claude/skills/gstack/

You should see:

SKILL.md           # Main skill definition
setup              # Setup script
browse/            # Browser automation skill
qa/                # QA testing skill
review/            # Code review skill
ship/              # Release workflow skill
retro/             # Retrospective skill
office-hours/      # Strategic thinking skill
plan-ceo-review/   # CEO review skill
plan-eng-review/   # Engineering review skill
careful/           # Safety mode skill
freeze/            # Edit boundary skill

Each subdirectory contains its own SKILL.md that defines the slash command.

2. 安裝

GStack 支援兩種安裝模式：全域安裝（所有專案共享）和專案內安裝（僅限單一倉庫）。根據你的需求選擇。

方案 A：全域安裝（推薦）

全域安裝將 GStack 放在 Claude Code 的共享 skills 目錄中。你機器上的每個專案都能存取它。

bash

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

逐步拆解這條指令做了什麼：

將 GStack 倉庫 clone 到 ~/.claude/skills/gstack/
切換到該目錄
執行 setup 腳本，它會：
- 安裝用於瀏覽器自動化的 Chromium 二進位檔（約 58 MB）
- 向 Claude Code 註冊九個 slash command
- 設定檔案路徑和權限

預期輸出：

Cloning into '/Users/you/.claude/skills/gstack'...
...
✓ Browser binary installed
✓ Skills registered
✓ Setup complete

方案 B：專案內安裝

當你只想在特定專案中使用 GStack，或不同專案需要不同 GStack 版本時，使用這個方案。

bash

# 首先確保你有全域 clone（或 clone 到臨時位置）
git clone https://github.com/garrytan/gstack.git /tmp/gstack

# 複製到你的專案中
cp -r /tmp/gstack /path/to/your-project/.claude/skills/gstack

# 在專案內執行 setup
cd /path/to/your-project/.claude/skills/gstack && ./setup

何時選擇專案內安裝：

你的專案使用不同版本的 GStack
你的團隊需要可重現的設定（GStack 提交到 repo 中）
你想針對每個專案自訂 GStack 行為
企業環境中限制全域安裝

驗證安裝

無論使用哪種安裝方式，都要驗證目錄結構：

bash

ls -la ~/.claude/skills/gstack/

你應該看到：

SKILL.md           # 主要 skill 定義
setup              # 設定腳本
browse/            # 瀏覽器自動化 skill
qa/                # QA 測試 skill
review/            # 程式碼審查 skill
ship/              # 發佈工作流 skill
retro/             # 回顧 skill
office-hours/      # 策略思維 skill
plan-ceo-review/   # CEO 審查 skill
plan-eng-review/   # 工程審查 skill
careful/           # 安全模式 skill
freeze/            # 編輯邊界 skill

每個子目錄都包含自己的 SKILL.md，定義了對應的 slash command。

3. Post-Installation: CLAUDE.md Configuration

The CLAUDE.md file is Claude Code's project-level configuration. GStack needs to be referenced here so Claude knows the skills are available.

Check Your Existing CLAUDE.md

If your project already has a CLAUDE.md:

bash

cat CLAUDE.md

Look for any existing skill references. The setup script may have already added the necessary lines.

Manual Configuration

If the setup script didn't modify your CLAUDE.md, or if you need to add references manually, ensure your project's CLAUDE.md includes a reference to the GStack skills directory.

For global installation, Claude Code automatically discovers skills in ~/.claude/skills/, so you typically don't need to add anything. But you can explicitly reference them:

markdown

## Skills

This project uses GStack sprint workflow skills from `~/.claude/skills/gstack/`.

For per-project installation, the skills directory .claude/skills/gstack/ within your project is automatically discovered by Claude Code.

Customizing CLAUDE.md for GStack Workflows

Add project-specific context that GStack commands will use:

markdown

## Project Context

- **Product**: A SaaS dashboard for analytics
- **Tech Stack**: Next.js 15, TypeScript, Tailwind CSS, Prisma, PostgreSQL
- **Target Users**: Small business owners
- **Key Metrics**: Time to insight, dashboard load time
- **Repository Convention**: Feature branches off `main`, squash merge

## GStack Configuration

- Use `/careful` mode by default for this project
- `/freeze` the `prisma/schema.prisma` file — schema changes require manual review
- Sprint branches should follow: `sprint/YYYY-MM-DD-feature-name`

This context is consumed by commands like /office-hours and /plan-ceo-review to provide relevant strategic advice.

CLAUDE.md Best Practices for GStack

Be specific about your tech stack — GStack's review and QA commands use this context
Define your branching strategy — /ship creates branches and PRs based on this
List frozen files explicitly — Prevents accidental modifications during sprints
Include deployment targets — Helps /ship know where code goes
Document testing conventions — /qa uses this to know what to test and how

3. 安裝後配置：CLAUDE.md 設定

CLAUDE.md 是 Claude Code 的專案層級設定檔。GStack 需要在這裡被參照，Claude 才知道這些 skills 可用。

檢查現有的 CLAUDE.md

如果你的專案已經有 CLAUDE.md：

bash

cat CLAUDE.md

檢查是否有現有的 skill 參照。setup 腳本可能已經添加了必要的內容。

手動配置

如果 setup 腳本沒有修改你的 CLAUDE.md，或者你需要手動添加參照，請確保你專案的 CLAUDE.md 包含對 GStack skills 目錄的參照。

對於全域安裝，Claude Code 會自動發現 ~/.claude/skills/ 中的 skills，所以通常不需要額外添加。但你可以明確參照它們：

markdown

## Skills

This project uses GStack sprint workflow skills from `~/.claude/skills/gstack/`.

對於專案內安裝，專案中的 .claude/skills/gstack/ 目錄會被 Claude Code 自動發現。

為 GStack 工作流自訂 CLAUDE.md

添加專案特定的上下文，GStack 指令會使用這些資訊：

markdown

## Project Context

- **Product**: A SaaS dashboard for analytics
- **Tech Stack**: Next.js 15, TypeScript, Tailwind CSS, Prisma, PostgreSQL
- **Target Users**: Small business owners
- **Key Metrics**: Time to insight, dashboard load time
- **Repository Convention**: Feature branches off `main`, squash merge

## GStack Configuration

- Use `/careful` mode by default for this project
- `/freeze` the `prisma/schema.prisma` file — schema changes require manual review
- Sprint branches should follow: `sprint/YYYY-MM-DD-feature-name`

這些上下文會被 /office-hours 和 /plan-ceo-review 等指令使用，以提供相關的策略建議。

針對 GStack 的 CLAUDE.md 最佳實踐

明確描述你的技術棧 —— GStack 的 review 和 QA 指令會使用這些資訊
定義你的分支策略 —— /ship 根據這個建立分支和 PR
明確列出凍結的檔案 —— 防止 sprint 期間的意外修改
包含部署目標 —— 幫助 /ship 知道程式碼要部署到哪裡
記錄測試慣例 —— /qa 用這些來決定測試什麼及如何測試

4. The Nine Slash Commands — A Complete Reference

GStack installs nine primary commands, plus two safety commands. Here's what each one does, when to use it, and what to expect.

Sprint Workflow Commands

Command	Purpose	Typical Duration	When to Use
`/office-hours`	Strategic product thinking	2-5 min	Start of sprint — reframe the problem
`/plan-ceo-review`	CEO-level strategy review	3-8 min	After office hours — validate direction
`/plan-eng-review`	Architecture design review	3-8 min	Before coding — plan the technical approach
`/review`	Code audit	2-5 min	After building — catch bugs and issues
`/ship`	Release workflow	1-3 min	After review — create PR and release
`/retro`	Sprint retrospective	2-5 min	After shipping — learn and improve

Testing Commands

Command	Purpose	Typical Duration	When to Use
`/browse`	Browser automation	1-5 min	Manual exploration, screenshot capture
`/qa`	QA testing with automatic fixes	3-10 min	After building — find and fix issues
`/qa-only`	QA reporting without fixes	2-8 min	When you want to review issues before fixing

Safety Commands

Command	Purpose	When to Use
`/careful`	Enable warnings before destructive commands	Always — especially on production codebases
`/freeze`	Set edit boundaries for files/directories	When certain files must not be modified

Command Details

/office-hours — This is your "zoom out" command. Instead of jumping into code, it forces you to think about the product problem you're solving. Claude acts as a product advisor, asking questions like: "Who is the user? What pain point are you solving? Is this the highest-leverage thing to build right now?"

/plan-ceo-review — Takes the output from office hours and applies a CEO lens: market positioning, competitive advantage, user value proposition. This is not technical — it's strategic. Useful for solo founders who don't have a co-founder to bounce ideas off.

/plan-eng-review — Now we get technical. This command reviews the proposed architecture: data models, API design, component structure, scalability concerns, security implications. It produces a concrete plan before any code is written.

/review — A thorough code audit. Checks for bugs, security vulnerabilities, performance issues, code style violations, and logic errors. More comprehensive than a typical PR review because it has full context of the codebase.

/qa — Launches the browser daemon, navigates your application, and tests user flows. When it finds bugs, it fixes them automatically. This is the "test and fix" mode.

/qa-only — Same testing as /qa, but only reports issues without applying fixes. Use this when you want to triage before patching.

/browse — Direct browser control. Navigate to URLs, take screenshots, interact with page elements. Useful for exploration and debugging visual issues.

/ship — Creates a feature branch (if not already on one), commits changes, pushes to remote, and creates a pull request. Handles the mechanical parts of releasing code.

/retro — Reviews what happened during the sprint: what went well, what didn't, what to do differently next time. Outputs structured learnings.

4. 九個 Slash Command——完整參考

GStack 安裝了九個主要指令，加上兩個安全指令。以下是每個指令的功能、使用時機和預期結果。

Sprint 工作流指令

指令	用途	典型時長	使用時機
`/office-hours`	策略性產品思維	2-5 分鐘	Sprint 開始——重新定義問題
`/plan-ceo-review`	CEO 層級策略審查	3-8 分鐘	Office hours 之後——驗證方向
`/plan-eng-review`	架構設計審查	3-8 分鐘	開始寫程式碼之前——規劃技術方案
`/review`	程式碼審計	2-5 分鐘	建構完成後——抓出 bug 和問題
`/ship`	發佈工作流	1-3 分鐘	審查之後——建立 PR 並發佈
`/retro`	Sprint 回顧	2-5 分鐘	發佈之後——學習並改進

測試指令

指令	用途	典型時長	使用時機
`/browse`	瀏覽器自動化	1-5 分鐘	手動探索、截圖
`/qa`	QA 測試並自動修復	3-10 分鐘	建構完成後——找出問題並修復
`/qa-only`	只報告 QA 結果不修復	2-8 分鐘	想在修復前先審查問題

安全指令

指令	用途	使用時機
`/careful`	在執行破壞性指令前啟用警告	始終開啟——特別是生產環境的程式碼庫
`/freeze`	為檔案或目錄設定編輯邊界	某些檔案不得被修改時

指令詳解

/office-hours —— 這是你的「拉遠視角」指令。與其直接跳進程式碼，它強迫你思考你要解決的產品問題。Claude 扮演產品顧問的角色，提出這樣的問題：「使用者是誰？你在解決什麼痛點？這是目前最高槓桿率的事情嗎？」

/plan-ceo-review —— 接收 office hours 的輸出，用 CEO 視角審視：市場定位、競爭優勢、使用者價值主張。這不是技術性的——而是策略性的。對沒有合夥人可以討論的 solo founder 特別有用。

/plan-eng-review —— 現在進入技術層面。這個指令審查提議的架構：資料模型、API 設計、元件結構、可擴展性考量、安全性影響。在寫任何程式碼之前產出具體計畫。

/review —— 全面的程式碼審計。檢查 bug、安全漏洞、效能問題、程式碼風格違規和邏輯錯誤。比一般的 PR review 更全面，因為它擁有整個 codebase 的完整上下文。

/qa —— 啟動瀏覽器 daemon，導覽你的應用程式，測試使用者流程。當它發現 bug 時，會自動修復。這是「測試並修復」模式。

/qa-only —— 與 /qa 相同的測試，但只報告問題而不套用修復。當你想在打補丁前先做分類時使用。

/browse —— 直接控制瀏覽器。導覽到 URL、截圖、與頁面元素互動。適合探索和除錯視覺問題。

/ship —— 建立 feature branch（如果還不在的話）、commit 變更、push 到 remote、建立 pull request。處理發佈程式碼的機械性工作。

/retro —— 回顧 sprint 期間發生的事：什麼做得好、什麼沒做好、下次要怎麼改。輸出結構化的學習成果。

5. Verifying Installation — Testing Each Command

Don't assume installation worked. Test each command systematically.

Quick Smoke Test

Open Claude Code in any git repository:

bash

cd /path/to/your-project
claude

Then type each command to verify it's recognized:

/office-hours

If the command is recognized, Claude will respond with strategic questions about your project. If you see "Unknown command," the skills directory isn't configured correctly.

Verification Checklist

Test each command and note the result:

[ ] /office-hours — Responds with product strategy questions
[ ] /plan-ceo-review — Asks for or reviews a product plan
[ ] /plan-eng-review — Asks for or reviews technical architecture
[ ] /review — Begins scanning code for issues
[ ] /ship — Initiates the release workflow
[ ] /browse — Launches the browser daemon
[ ] /qa — Begins browser-based QA testing
[ ] /qa-only — Begins QA reporting
[ ] /retro — Begins the retrospective process

If a Command Isn't Recognized

Check the skills directory exists:

bash

ls ~/.claude/skills/gstack/

Check that each sub-skill has a SKILL.md:

bash

for dir in ~/.claude/skills/gstack/*/; do
  if [ -f "$dir/SKILL.md" ]; then
    echo "✓ $(basename $dir)"
  else
    echo "✗ $(basename $dir) — missing SKILL.md"
  fi
done

Re-run setup if needed:

bash

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

Restart Claude Code — skills are loaded at startup.

5. 驗證安裝——測試每個指令

不要假設安裝成功了。系統性地測試每個指令。

快速冒煙測試

在任何 git 倉庫中開啟 Claude Code：

bash

cd /path/to/your-project
claude

然後輸入每個指令來驗證它是否被識別：

/office-hours

如果指令被識別，Claude 會回應關於你專案的策略問題。如果你看到「Unknown command」，表示 skills 目錄沒有正確配置。

驗證清單

測試每個指令並記錄結果：

[ ] /office-hours —— 回應產品策略問題
[ ] /plan-ceo-review —— 詢問或審查產品計畫
[ ] /plan-eng-review —— 詢問或審查技術架構
[ ] /review —— 開始掃描程式碼找問題
[ ] /ship —— 啟動發佈工作流
[ ] /browse —— 啟動瀏覽器 daemon
[ ] /qa —— 開始瀏覽器 QA 測試
[ ] /qa-only —— 開始 QA 報告
[ ] /retro —— 開始回顧流程

如果指令未被識別

bash

ls ~/.claude/skills/gstack/

確認每個子 skill 都有 SKILL.md：

bash

for dir in ~/.claude/skills/gstack/*/; do
  if [ -f "$dir/SKILL.md" ]; then
    echo "✓ $(basename $dir)"
  else
    echo "✗ $(basename $dir) — missing SKILL.md"
  fi
done

如有需要，重新執行 setup：

bash

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

重新啟動 Claude Code —— skills 在啟動時載入。

6. Browser Daemon Setup and Configuration

The browser daemon is what powers /browse, /qa, and /qa-only. It runs a headless Chromium instance that Claude controls programmatically.

How the Browser Daemon Works

Binary: A persistent Chromium binary (~58 MB) installed during ./setup
Startup: Auto-starts when you first invoke /browse or /qa
Latency: 100-200ms per browser command (navigate, click, type, screenshot)
Lifecycle: Stays running until you close Claude Code or explicitly stop it

Configuring Authenticated Testing

Many applications require login. GStack provides a cookie setup command:

/setup-browser-cookies

This command:

Opens a visible browser window (not headless)
Lets you manually log into your application
Captures the cookies from your session
Saves them for future /qa and /browse sessions

When to use this:

Your app requires authentication to test
You need to test admin-only features
You're testing features behind feature flags tied to user accounts

Browser Daemon Resource Management

The Chromium process consumes memory. On a typical machine:

Scenario	Memory Usage	Notes
Idle daemon	~150 MB	Just the browser process
Single page loaded	~200-400 MB	Depends on page complexity
Multi-page QA session	~400-800 MB	Multiple tabs may be opened

Tips for managing resources:

Close the browser daemon when not actively using QA commands
If your machine has less than 8 GB RAM, avoid running QA during heavy compilation
Monitor with: ps aux | grep -i chromium
Force kill if orphaned: pkill -f chromium

Port Conflicts

The browser daemon uses a debug port to communicate. If you see errors about port conflicts:

bash

# Find what's using the port
lsof -i :9222

# Kill the conflicting process
kill -9 <PID>

Port 9222 is the default Chrome DevTools Protocol port. If another Chromium/Chrome instance is using it, you'll need to close it first.

6. 瀏覽器 Daemon 設定與配置

瀏覽器 daemon 是 /browse、/qa 和 /qa-only 的動力來源。它運行一個 headless Chromium 實例，由 Claude 程式化控制。

瀏覽器 Daemon 的運作方式

二進位檔：在 ./setup 期間安裝的持久 Chromium 二進位檔（約 58 MB）
啟動方式：在你第一次使用 /browse 或 /qa 時自動啟動
延遲：每個瀏覽器指令（導覽、點擊、輸入、截圖）100-200ms
生命週期：持續運行直到你關閉 Claude Code 或明確停止它

配置認證測試

許多應用程式需要登入。GStack 提供了 cookie 設定指令：

/setup-browser-cookies

這個指令：

開啟一個可見的瀏覽器視窗（不是 headless）
讓你手動登入你的應用程式
擷取你登入 session 的 cookies
儲存以供未來 /qa 和 /browse 使用

何時使用：

你的應用需要認證才能測試
你需要測試僅限管理員的功能
你在測試與使用者帳號綁定的 feature flag 背後的功能

瀏覽器 Daemon 資源管理

Chromium 進程會消耗記憶體。在一般機器上：

情境	記憶體使用量	備註
閒置 daemon	約 150 MB	僅瀏覽器進程
載入單一頁面	約 200-400 MB	取決於頁面複雜度
多頁面 QA session	約 400-800 MB	可能開啟多個分頁

資源管理技巧：

不使用 QA 指令時關閉瀏覽器 daemon
如果你的機器 RAM 少於 8 GB，避免在繁重編譯期間執行 QA
用以下指令監控：ps aux | grep -i chromium
如果進程孤立，強制終止：pkill -f chromium

連接埠衝突

瀏覽器 daemon 使用 debug port 進行通訊。如果你看到關於連接埠衝突的錯誤：

bash

# 查找是什麼佔用了該連接埠
lsof -i :9222

# 終止衝突的進程
kill -9 <PID>

Port 9222 是預設的 Chrome DevTools Protocol 連接埠。如果另一個 Chromium/Chrome 實例正在使用它，你需要先關閉它。

7. Sprint Workflow Walkthrough — A Practical Example

Let's walk through a complete sprint from start to finish. We'll build a "dark mode toggle" feature for a Next.js application.

Step 1: Start with `/office-hours`

/office-hours

Claude asks strategic questions. You describe the feature:

"I want to add a dark mode toggle to the dashboard. Users have been requesting it, and our analytics show 40% of users visit after 8 PM."

Claude might respond with:

Is dark mode the highest-impact feature right now?
Have you considered system preference detection instead of a manual toggle?
What's the scope — just the dashboard, or the entire app?

This forces you to think before you build. Maybe you realize system preference detection plus a manual override is the right approach.

Step 2: Strategy Review with `/plan-ceo-review`

/plan-ceo-review

Claude evaluates from a CEO perspective:

User value: High — directly requested, supported by usage data
Effort vs. impact: Low effort for high user satisfaction
Competitive context: Most modern apps support dark mode — table stakes
Recommendation: Ship it, but include system preference detection

Step 3: Architecture with `/plan-eng-review`

/plan-eng-review

Claude produces a technical plan:

Use CSS custom properties for theme variables
Store preference in localStorage with system default fallback
Create a ThemeProvider React context
Add a ThemeToggle component in the header
Ensure all existing components use theme variables
Test plan: visual regression on 5 key pages

Step 4: Build the Feature

Now you write code. Use Claude Code normally — ask it to implement the plan from step 3. GStack doesn't interfere with the building phase; it frames and follows up.

Create the ThemeProvider and ThemeToggle based on the engineering plan above.

Step 5: Code Audit with `/review`

/review

Claude scans the code you just wrote. It might find:

Missing prefers-color-scheme media query handling
A color that's hardcoded instead of using a theme variable
The toggle doesn't persist across page reloads (forgot to read from localStorage on mount)

Fix each issue Claude identifies.

Step 6: QA Testing with `/qa`

/qa

The browser daemon launches, navigates to your app, and:

Clicks the dark mode toggle
Verifies the UI updates correctly
Navigates to multiple pages to check consistency
Tests the toggle persistence (reload and verify)
Checks for contrast issues in dark mode

If it finds bugs, it fixes them automatically (unlike /qa-only).

Step 7: Ship It with `/ship`

/ship

Claude:

Creates a feature branch: feature/dark-mode-toggle
Commits all changes with a descriptive message
Pushes to remote
Creates a pull request with a summary of changes

Step 8: Retrospective with `/retro`

/retro

Claude reviews the sprint:

What went well: Architecture plan caught the localStorage persistence issue early
What could improve: Should have included accessibility testing in the QA plan
Action items: Add WCAG contrast ratio checks to future /qa runs

Time Investment

Step	Time	Value
`/office-hours`	3 min	Avoided building wrong feature scope
`/plan-ceo-review`	5 min	Validated strategic priority
`/plan-eng-review`	5 min	Prevented architectural mistakes
Building	15 min	Feature implementation
`/review`	3 min	Caught 3 bugs before QA
`/qa`	5 min	Found 1 visual regression
`/ship`	2 min	PR created automatically
`/retro`	3 min	Documented learnings
Total	~41 min	Complete feature sprint

Without GStack, you might ship faster initially — but you'd miss the strategic framing, skip the architecture review, and catch bugs later (in production, from users).

7. Sprint 工作流實戰演練——一個完整的實際案例

讓我們從頭到尾走完一個完整的 sprint。我們將為一個 Next.js 應用程式建構「深色模式切換」功能。

步驟 1：從 `/office-hours` 開始

/office-hours

Claude 提出策略性問題。你描述功能需求：

「我想在 dashboard 上添加深色模式切換。使用者一直在要求這個功能，我們的分析數據顯示 40% 的使用者在晚上 8 點後造訪。」

Claude 可能會回應：

深色模式是目前影響力最大的功能嗎？
你有考慮過系統偏好偵測而不是手動切換嗎？
範圍是什麼——只有 dashboard，還是整個應用程式？

這迫使你在動手之前先思考。也許你會意識到系統偏好偵測加手動覆蓋才是正確的方案。

步驟 2：用 `/plan-ceo-review` 進行策略審查

/plan-ceo-review

Claude 從 CEO 角度評估：

使用者價值：高——直接被要求，有使用數據支持
投入與影響：低投入換取高使用者滿意度
競爭脈絡：多數現代應用支援深色模式——這是基本功
建議：發佈它，但加入系統偏好偵測

步驟 3：用 `/plan-eng-review` 進行架構規劃

/plan-eng-review

Claude 產出技術計畫：

使用 CSS custom properties 作為主題變數
將偏好存在 localStorage 中，系統預設值作為 fallback
建立 ThemeProvider React context
在 header 中添加 ThemeToggle 元件
確保所有現有元件使用主題變數
測試計畫：在 5 個關鍵頁面上做視覺回歸測試

步驟 4：建構功能

現在你開始寫程式碼。正常使用 Claude Code——讓它根據步驟 3 的計畫實現。GStack 不會干擾建構階段；它負責框架和後續跟進。

Create the ThemeProvider and ThemeToggle based on the engineering plan above.

步驟 5：用 `/review` 進行程式碼審計

/review

Claude 掃描你剛寫的程式碼。它可能會發現：

缺少 prefers-color-scheme media query 處理
一個顏色是硬編碼的，而不是使用主題變數
切換在頁面重新載入後不會保持（忘了在 mount 時從 localStorage 讀取）

修復 Claude 識別出的每個問題。

步驟 6：用 `/qa` 進行 QA 測試

/qa

瀏覽器 daemon 啟動，導覽到你的應用程式，然後：

點擊深色模式切換按鈕
驗證 UI 是否正確更新
導覽到多個頁面檢查一致性
測試切換的持久性（重新載入並驗證）
檢查深色模式下的對比度問題

如果發現 bug，它會自動修復（不像 /qa-only）。

步驟 7：用 `/ship` 發佈

/ship

Claude：

建立 feature branch：feature/dark-mode-toggle
用描述性的 commit message 提交所有變更
Push 到 remote
建立包含變更摘要的 pull request

步驟 8：用 `/retro` 回顧

/retro

Claude 回顧 sprint：

做得好的：架構計畫在早期就抓住了 localStorage 持久性問題
可以改進的：應該在 QA 計畫中加入無障礙測試
行動項目：在未來的 /qa 執行中加入 WCAG 對比度比率檢查

時間投入

步驟	時間	價值
`/office-hours`	3 分鐘	避免建構錯誤的功能範圍
`/plan-ceo-review`	5 分鐘	驗證策略優先級
`/plan-eng-review`	5 分鐘	預防架構錯誤
建構	15 分鐘	功能實現
`/review`	3 分鐘	在 QA 前抓出 3 個 bug
`/qa`	5 分鐘	找到 1 個視覺回歸
`/ship`	2 分鐘	自動建立 PR
`/retro`	3 分鐘	記錄學習成果
合計	約 41 分鐘	完整的功能 sprint

沒有 GStack，你一開始可能發佈得更快——但你會錯過策略框架、跳過架構審查，然後在更晚的時候（在生產環境中、由使用者）才發現 bug。

8. Safety Features Configuration

GStack includes two safety mechanisms that are especially important for production codebases.

`/careful` — Destructive Command Warnings

Activating /careful mode makes Claude warn you before executing any potentially destructive operation:

/careful

Once active, Claude will pause and ask for confirmation before:

Deleting files
Overwriting existing files
Running git reset, git clean, or git checkout -- .
Dropping database tables
Any command that could result in data loss

Recommendation: Enable /careful at the start of every session on production codebases. The small friction of confirmation prompts is worth the protection.

`/freeze` — Edit Boundaries

/freeze prevents Claude from modifying specific files or directories:

/freeze prisma/schema.prisma
/freeze config/
/freeze .env .env.local

Common freeze targets:

File/Directory	Why Freeze It
`prisma/schema.prisma`	Database schema changes need manual review
`.env`, `.env.local`	Secrets must never be AI-modified
`config/`	Infrastructure config needs human approval
`package.json`	Dependency changes should be deliberate
`migrations/`	Database migrations need careful review
`Dockerfile`	Container config changes need testing

Combining Safety Features

For maximum safety on a production codebase:

/careful
/freeze .env .env.local .env.production
/freeze prisma/schema.prisma
/freeze Dockerfile docker-compose.yml
/freeze config/

This creates a layered defense: Claude warns before destructive actions AND cannot touch critical configuration files.

8. 安全功能配置

GStack 包含兩個安全機制，對生產環境的程式碼庫特別重要。

`/careful` —— 破壞性指令警告

啟用 /careful 模式後，Claude 在執行任何可能具有破壞性的操作前會先警告你：

/careful

啟用後，Claude 會在以下操作前暫停並要求確認：

刪除檔案
覆寫現有檔案
執行 git reset、git clean 或 git checkout -- .
刪除資料庫表
任何可能導致資料遺失的指令

建議：在生產環境程式碼庫上的每次 session 開始時都啟用 /careful。確認提示帶來的小摩擦，值得換取的保護。

`/freeze` —— 編輯邊界

/freeze 防止 Claude 修改特定檔案或目錄：

/freeze prisma/schema.prisma
/freeze config/
/freeze .env .env.local

常見的凍結目標：

檔案/目錄	為什麼要凍結
`prisma/schema.prisma`	資料庫 schema 變更需要手動審查
`.env`、`.env.local`	密鑰絕不能被 AI 修改
`config/`	基礎設施配置需要人工審批
`package.json`	依賴變更應該是有意為之的
`migrations/`	資料庫 migration 需要仔細審查
`Dockerfile`	容器配置變更需要測試

組合安全功能

在生產環境程式碼庫上獲得最大安全性：

/careful
/freeze .env .env.local .env.production
/freeze prisma/schema.prisma
/freeze Dockerfile docker-compose.yml
/freeze config/

這建立了分層防禦：Claude 在破壞性操作前會發出警告，同時無法觸碰關鍵的配置檔案。

9. Multi-Project Management

When you work on multiple projects, GStack's behavior depends on your installation method.

Global Installation: Shared Across Projects

With global installation (~/.claude/skills/gstack/), every project shares the same GStack version. This is simple but has trade-offs:

Advantages:

One installation to maintain
Consistent behavior across all projects
Updates apply everywhere at once

Disadvantages:

Can't customize GStack per project
A broken update affects all projects
No version pinning per project

Per-Project Installation: Independent Versions

With per-project installation (.claude/skills/gstack/ inside each repo), each project has its own GStack copy:

Advantages:

Version pinned per project
Customizable per project
Can commit to repo for team sharing
Isolated from other projects

Disadvantages:

Multiple copies to maintain
Updates must be applied per project
Larger repository size

Hybrid Approach (Recommended for Teams)

Use global installation for personal development and per-project for team projects:

bash

# Global (personal projects)
~/.claude/skills/gstack/

# Team project A (committed to repo)
/projects/team-app-a/.claude/skills/gstack/

# Team project B (committed to repo)
/projects/team-app-b/.claude/skills/gstack/

This way, team projects have reproducible setups while your personal projects always use the latest version.

Project-Specific CLAUDE.md Configuration

Each project should have its own CLAUDE.md with project-specific context, regardless of GStack installation method:

markdown

# Project: Team App A

## Tech Stack
- Next.js 15, TypeScript, Prisma, PostgreSQL

## GStack Notes
- Always run /careful before starting work
- /freeze the migrations/ directory
- Sprint branches: sprint/YYYYMMDD-description
- QA URL: http://localhost:3000

9. 多專案管理

當你同時在多個專案上工作時，GStack 的行為取決於你的安裝方式。

全域安裝：跨專案共享

使用全域安裝（~/.claude/skills/gstack/），每個專案共享同一個 GStack 版本。這很簡單但有取捨：

優點：

只需維護一個安裝
所有專案行為一致
更新一次全部生效

缺點：

無法針對每個專案自訂 GStack
一個有問題的更新會影響所有專案
無法針對每個專案鎖定版本

專案內安裝：獨立版本

使用專案內安裝（每個 repo 內的 .claude/skills/gstack/），每個專案有自己的 GStack 副本：

優點：

每個專案鎖定版本
可針對每個專案自訂
可提交到 repo 供團隊共享
與其他專案隔離

缺點：

需要維護多個副本
更新必須逐專案套用
倉庫體積較大

混合方案（團隊推薦）

個人開發使用全域安裝，團隊專案使用專案內安裝：

bash

# 全域（個人專案）
~/.claude/skills/gstack/

# 團隊專案 A（提交到 repo）
/projects/team-app-a/.claude/skills/gstack/

# 團隊專案 B（提交到 repo）
/projects/team-app-b/.claude/skills/gstack/

這樣團隊專案有可重現的設定，而你的個人專案始終使用最新版本。

專案特定的 CLAUDE.md 配置

無論 GStack 安裝方式如何，每個專案都應有自己的 CLAUDE.md，包含專案特定的上下文：

markdown

# Project: Team App A

## Tech Stack
- Next.js 15, TypeScript, Prisma, PostgreSQL

## GStack Notes
- Always run /careful before starting work
- /freeze the migrations/ directory
- Sprint branches: sprint/YYYYMMDD-description
- QA URL: http://localhost:3000

10. Parallelization with Conductor

GStack's most powerful feature for scaling output is the Conductor — it orchestrates multiple sprints running simultaneously.

What is Conductor?

Conductor is a meta-workflow that:

Takes a list of tasks (features, bugs, improvements)
Spins up isolated workspaces for each task
Runs the full sprint workflow in each workspace in parallel
Manages branch isolation so sprints don't conflict

How It Works

Each parallel sprint runs in its own:

Git worktree (isolated file state)
Claude Code session (independent context)
Feature branch (no merge conflicts during development)

Running Parallel Sprints

Typical Conductor usage:

Run 5 sprints in parallel:
1. Add dark mode toggle
2. Fix pagination bug on /users page
3. Refactor auth middleware to use JWT
4. Add CSV export to reports
5. Update onboarding flow copy

Claude Conductor:

Creates 5 git worktrees from main
Starts 5 Claude Code sessions
Each session runs the full sprint workflow independently
Results: 5 PRs ready for review

Practical Limits

Factor	Recommended	Maximum	Notes
Parallel sprints	5-8	10-15	Depends on machine specs
RAM per sprint	~500 MB	~1 GB	Includes Claude Code + browser
CPU cores	1 per sprint	—	More cores = better performance
API rate limits	Check plan	—	Anthropic rate limits apply

Resource Requirements for Parallel Sprints

For a MacBook Pro M3 with 18 GB RAM:

Base system:           ~4 GB
Claude Code (main):    ~500 MB
Per sprint overhead:   ~500 MB each
Browser daemon (shared): ~300 MB

5 parallel sprints:    ~4 + 0.5 + (5 × 0.5) + 0.3 = ~7.3 GB
10 parallel sprints:   ~4 + 0.5 + (10 × 0.5) + 0.3 = ~9.8 GB

Key insight: The browser daemon is shared across sprints, not duplicated. This makes parallelization more memory-efficient than you might expect.

Cost Implications

Each parallel sprint makes independent API calls. Running 10 sprints is roughly 10x the API cost of one sprint. See Section 11 for detailed cost analysis.

10. 使用 Conductor 進行平行化

GStack 最強大的規模化功能是 Conductor——它協調同時運行的多個 sprint。

什麼是 Conductor？

Conductor 是一個元工作流，它：

接收一個任務清單（功能、bug、改進）
為每個任務啟動隔離的工作空間
在每個工作空間中平行運行完整的 sprint 工作流
管理分支隔離，確保 sprint 之間不衝突

運作方式

每個平行 sprint 運行在自己的：

Git worktree（隔離的檔案狀態）
Claude Code session（獨立的上下文）
Feature branch（開發期間不會有合併衝突）

運行平行 Sprint

典型的 Conductor 使用方式：

Run 5 sprints in parallel:
1. Add dark mode toggle
2. Fix pagination bug on /users page
3. Refactor auth middleware to use JWT
4. Add CSV export to reports
5. Update onboarding flow copy

Claude Conductor：

從 main 建立 5 個 git worktree
啟動 5 個 Claude Code session
每個 session 獨立運行完整的 sprint 工作流
結果：5 個準備好審查的 PR

實際限制

因素	建議值	最大值	備註
平行 sprint 數	5-8	10-15	取決於機器規格
每個 sprint 的 RAM	約 500 MB	約 1 GB	包含 Claude Code + 瀏覽器
CPU 核心	每個 sprint 1 個	—	核心越多性能越好
API 速率限制	檢查你的方案	—	Anthropic 速率限制適用

平行 Sprint 的資源需求

以 MacBook Pro M3 搭載 18 GB RAM 為例：

基礎系統：             約 4 GB
Claude Code（主要）：   約 500 MB
每個 sprint 開銷：      每個約 500 MB
瀏覽器 daemon（共享）：  約 300 MB

5 個平行 sprint：    約 4 + 0.5 + (5 × 0.5) + 0.3 = 約 7.3 GB
10 個平行 sprint：   約 4 + 0.5 + (10 × 0.5) + 0.3 = 約 9.8 GB

關鍵洞察：瀏覽器 daemon 在 sprint 之間共享，不會重複啟動。這使得平行化比你預期的更節省記憶體。

成本影響

每個平行 sprint 都會獨立發出 API 呼叫。運行 10 個 sprint 的 API 成本大約是一個 sprint 的 10 倍。詳細成本分析請見第 11 節。

11. Important Considerations and Gotchas

This section covers the things that documentation often glosses over — the real-world factors that determine whether GStack works well for you.

11.1 Cost: API Usage Amplification

GStack significantly amplifies Claude Code API usage. Each slash command sends detailed system prompts plus your project context to the API.

Rough cost estimates per sprint (based on typical Claude API pricing):

Component	Input Tokens	Output Tokens	Estimated Cost
`/office-hours`	~5,000	~2,000	~$0.08
`/plan-ceo-review`	~8,000	~3,000	~$0.13
`/plan-eng-review`	~10,000	~5,000	~$0.20
Building (Claude Code)	~20,000	~10,000	~$0.40
`/review`	~15,000	~5,000	~$0.25
`/qa`	~12,000	~8,000	~$0.25
`/ship`	~5,000	~2,000	~$0.08
`/retro`	~5,000	~2,000	~$0.08
Total per sprint	~80,000	~37,000	~$1.47

At scale:

5 sprints/day: ~$7.35/day, ~$147/month
10 parallel sprints: ~$14.70 per batch
Heavy usage (20 sprints/day): ~$588/month

These are rough estimates. Actual costs depend on project size, codebase complexity, and how much context is loaded per command.

Cost management tips:

Skip /office-hours and /plan-ceo-review for small bug fixes
Use /qa-only instead of /qa when you don't want automatic fixes
Run /review only on changed files, not the entire codebase
Monitor your Anthropic API dashboard regularly

11.2 Token Consumption Patterns

Each slash command injects a detailed system prompt. Larger codebases mean more context tokens per command.

What consumes the most tokens:

/review on large codebases — reads many files for context
/qa with complex browser sessions — long interaction logs
/plan-eng-review with many existing components — needs to understand the architecture

Optimization strategies:

Keep your CLAUDE.md focused — don't dump irrelevant information
Use .claudeignore to exclude files Claude shouldn't read (build outputs, node_modules, etc.)
Run targeted commands: /review src/components/NewFeature.tsx instead of just /review

11.3 Git Hygiene

GStack creates branches and PRs prolifically. Without discipline, your git history becomes a mess.

Best practices:

Use a consistent branch naming convention: sprint/YYYYMMDD-feature-name
Squash merge sprint PRs into main
Delete sprint branches after merge
Review PR descriptions before merging — AI-generated descriptions may be verbose
Clean up abandoned sprint branches regularly

bash

# Clean up merged sprint branches
git branch --merged main | grep 'sprint/' | xargs git branch -d

# Clean up remote tracking branches
git remote prune origin

11.4 Security Considerations

GStack runs entirely locally. There is no telemetry. Your code never leaves your machine (beyond what Claude Code API calls include). However:

Review all generated code. AI-generated code can contain:

Logic errors that pass tests but fail edge cases
Security vulnerabilities (SQL injection, XSS, CSRF)
Hardcoded secrets or test credentials left in code
Overly permissive configurations
Dependencies with known vulnerabilities

Specific risks with GStack:

/ship creates PRs — make sure your CI pipeline includes security scanning
/qa tests happy paths better than adversarial paths
Browser cookies from /setup-browser-cookies are stored locally — secure your machine

11.5 Not a Replacement for Human Judgment

GStack's slash commands produce impressive output. It's tempting to trust them blindly. Don't.

Where AI judgment falls short:

Business context that isn't in the codebase (regulatory requirements, customer contracts)
Organizational politics and team dynamics
Long-term architectural decisions with multi-year implications
Security threat modeling against sophisticated attackers
Performance optimization for specific hardware or network conditions

The right mental model: GStack is a very fast, moderately skilled junior team member. It does excellent grunt work and catches obvious issues. But strategic decisions, security audits, and architectural calls need human expertise.

11.6 Team Adoption Considerations

Before rolling out GStack to a team, consider:

Process impact:

GStack assumes a specific sprint workflow — does it match your team's process?
PR volume increases — is your review capacity ready?
Branching strategy must be agreed upon team-wide

Training needs:

Every team member needs Claude Code proficiency first
GStack-specific training: when to use which command, how to interpret outputs
Establish guidelines for when to skip commands (not every bug fix needs /office-hours)

Governance:

Define which files should be frozen across the team
Set /careful as the default for production repositories
Establish code review standards for AI-generated PRs
Create a shared CLAUDE.md template for team projects

11.7 Version Updates

GStack is actively developed. Track the repository for updates:

bash

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

Important: Always re-run ./setup after pulling updates. The setup script may need to install new dependencies or update configurations.

Before updating:

Check the changelog for breaking changes
Test on a non-critical project first
Coordinate team-wide updates to maintain consistency

11. 重要注意事項與陷阱

本節涵蓋文件常常一筆帶過的內容——決定 GStack 是否真正適合你的實際因素。

11.1 成本：API 使用量放大效應

GStack 會顯著放大 Claude Code 的 API 使用量。每個 slash command 都會將詳細的 system prompt 加上你的專案上下文發送到 API。

每個 sprint 的大概成本估算（基於典型 Claude API 定價）：

組成部分	輸入 Token 數	輸出 Token 數	估算成本
`/office-hours`	約 5,000	約 2,000	約 $0.08
`/plan-ceo-review`	約 8,000	約 3,000	約 $0.13
`/plan-eng-review`	約 10,000	約 5,000	約 $0.20
建構（Claude Code）	約 20,000	約 10,000	約 $0.40
`/review`	約 15,000	約 5,000	約 $0.25
`/qa`	約 12,000	約 8,000	約 $0.25
`/ship`	約 5,000	約 2,000	約 $0.08
`/retro`	約 5,000	約 2,000	約 $0.08
每個 sprint 合計	約 80,000	約 37,000	約 $1.47

規模化使用時：

每天 5 個 sprint：約 $7.35/天，約 $147/月
10 個平行 sprint：每批約 $14.70
重度使用（每天 20 個 sprint）：約 $588/月

這些是粗略估算。實際成本取決於專案大小、程式碼庫複雜度，以及每個指令載入多少上下文。

成本管理技巧：

小 bug 修復時跳過 /office-hours 和 /plan-ceo-review
不需要自動修復時用 /qa-only 代替 /qa
只對變更的檔案執行 /review，而不是整個程式碼庫
定期監控你的 Anthropic API dashboard

11.2 Token 消耗模式

每個 slash command 會注入一個詳細的 system prompt。程式碼庫越大，每個指令的上下文 token 就越多。

消耗最多 token 的情境：

在大型程式碼庫上執行 /review —— 需要讀取許多檔案作為上下文
複雜瀏覽器 session 的 /qa —— 互動日誌很長
有許多現有元件的 /plan-eng-review —— 需要理解整體架構

優化策略：

保持 CLAUDE.md 聚焦——不要堆入不相關的資訊
使用 .claudeignore 排除 Claude 不需要讀取的檔案（build 輸出、node_modules 等）
執行有針對性的指令：/review src/components/NewFeature.tsx 而不是只用 /review

11.3 Git 衛生

GStack 會大量建立分支和 PR。沒有紀律的話，你的 git 歷史會變得一團糟。

最佳實踐：

使用一致的分支命名慣例：sprint/YYYYMMDD-feature-name
將 sprint PR squash merge 到 main
合併後刪除 sprint 分支
合併前審查 PR 描述——AI 產生的描述可能過於冗長
定期清理被放棄的 sprint 分支

bash

# 清理已合併的 sprint 分支
git branch --merged main | grep 'sprint/' | xargs git branch -d

# 清理遠端追蹤分支
git remote prune origin

11.4 安全考量

GStack 完全在本地運行。沒有遙測。你的程式碼不會離開你的機器（除了 Claude Code API 呼叫所包含的內容）。然而：

審查所有產生的程式碼。 AI 產生的程式碼可能包含：

通過測試但在邊緣情況下失敗的邏輯錯誤
安全漏洞（SQL injection、XSS、CSRF）
留在程式碼中的硬編碼密鑰或測試憑證
過於寬鬆的配置
具有已知漏洞的依賴

GStack 的特定風險：

/ship 建立 PR——確保你的 CI pipeline 包含安全掃描
/qa 測試 happy path 比對抗性路徑做得更好
/setup-browser-cookies 的瀏覽器 cookie 儲存在本地——保護好你的機器

11.5 不能替代人類判斷

GStack 的 slash command 產出令人印象深刻的結果。盲目信任它是很誘人的。不要這樣做。

AI 判斷不足的地方：

不在程式碼庫中的業務脈絡（法規要求、客戶合約）
組織政治和團隊動態
具有多年影響的長期架構決策
對抗複雜攻擊者的安全威脅建模
針對特定硬體或網路條件的效能優化

正確的心智模型： GStack 是一個速度極快、能力中等的初級團隊成員。它做出色的粗活，抓住明顯的問題。但策略決策、安全審計和架構決定需要人類的專業知識。

11.6 團隊採用考量

在團隊中推行 GStack 之前，請考慮：

流程影響：

GStack 假設一個特定的 sprint 工作流——它符合你團隊的流程嗎？
PR 數量增加——你的審查能力準備好了嗎？
分支策略必須在團隊中達成共識

培訓需求：

每個團隊成員首先需要 Claude Code 的熟練度
GStack 特定培訓：何時使用哪個指令、如何解讀輸出
建立何時跳過指令的準則（不是每個 bug 修復都需要 /office-hours）

治理：

定義團隊中哪些檔案應該被凍結
將 /careful 設為生產倉庫的預設值
為 AI 產生的 PR 建立程式碼審查標準
為團隊專案建立共享的 CLAUDE.md 模板

11.7 版本更新

GStack 正在積極開發中。追蹤倉庫以獲取更新：

bash

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

重要： 拉取更新後一定要重新執行 ./setup。setup 腳本可能需要安裝新依賴或更新配置。

更新前：

檢查 changelog 以了解有無破壞性變更
先在非關鍵專案上測試
協調團隊同步更新以保持一致性

12. Troubleshooting Common Issues

A reference for the most frequently encountered problems and their solutions.

Bun Not Found

Symptom: ./setup fails with "bun: command not found"

Fix:

bash

curl -fsSL https://bun.sh/install | bash
source ~/.zshrc  # or ~/.bashrc
bun --version

If Bun is installed but not found, check your PATH:

bash

echo $PATH | tr ':' '\n' | grep bun

If nothing appears, add Bun to your PATH:

bash

echo 'export PATH="$HOME/.bun/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Browser Daemon Won't Start

Symptom: /browse or /qa fails with connection errors

Diagnosis steps:

Check if Chromium process is running:

bash

ps aux | grep -i chromium

Check for port conflicts:

bash

lsof -i :9222

Kill orphaned processes:

bash

pkill -f chromium

Verify the Chromium binary exists:

bash

ls -la ~/.claude/skills/gstack/browse/chromium*

If the binary is missing, re-run setup:

bash

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

Slash Commands Not Recognized

Symptom: Typing /office-hours returns "Unknown command"

Diagnosis steps:

Verify directory structure:

bash

ls ~/.claude/skills/gstack/

Check for SKILL.md files:

bash

find ~/.claude/skills/gstack -name "SKILL.md" -type f

Verify Claude Code version (older versions may not support skills):

bash

claude --version

Restart Claude Code — skills are loaded at startup
Check if Claude Code is reading the correct skills directory:

bash

ls ~/.claude/skills/

Permission Errors

Symptom: ./setup fails with "Permission denied"

Fix:

bash

chmod +x ~/.claude/skills/gstack/setup

If the issue persists for the Chromium binary:

bash

chmod +x ~/.claude/skills/gstack/browse/chromium*

Git Worktree Conflicts (Parallelization)

Symptom: Conductor fails to create worktrees

Diagnosis:

bash

git worktree list

Fix: Clean up stale worktrees:

bash

git worktree prune

If worktree directories still exist on disk:

bash

# List and manually remove stale worktree directories
git worktree list | grep -v "main" | awk '{print $1}'

High Memory Usage

Symptom: System becomes slow during QA or parallel sprints

Quick fixes:

Close unnecessary applications
Kill the browser daemon between QA sessions:

bash

pkill -f chromium

Reduce parallel sprint count
Monitor memory usage:

bash

# macOS
vm_stat | head -5

# Linux
free -h

API Rate Limiting

Symptom: Commands fail with rate limit errors

Fixes:

Wait and retry — rate limits are temporary
Reduce parallel sprint count
Upgrade your Anthropic API plan
Spread sprints across the day instead of running all at once

12. 常見問題排除

最常遇到的問題及其解決方案的參考手冊。

Bun 未找到

症狀：./setup 失敗，顯示「bun: command not found」

修復：

bash

curl -fsSL https://bun.sh/install | bash
source ~/.zshrc  # 或 ~/.bashrc
bun --version

如果 Bun 已安裝但未找到，檢查你的 PATH：

bash

echo $PATH | tr ':' '\n' | grep bun

如果沒有任何輸出，將 Bun 添加到 PATH：

bash

echo 'export PATH="$HOME/.bun/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

瀏覽器 Daemon 無法啟動

症狀：/browse 或 /qa 失敗，出現連線錯誤

診斷步驟：

檢查 Chromium 進程是否正在運行：

bash

ps aux | grep -i chromium

檢查連接埠衝突：

bash

lsof -i :9222

終止孤立進程：

bash

pkill -f chromium

驗證 Chromium 二進位檔是否存在：

bash

ls -la ~/.claude/skills/gstack/browse/chromium*

如果二進位檔缺失，重新執行 setup：

bash

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

Slash Command 未被識別

症狀：輸入 /office-hours 返回「Unknown command」

診斷步驟：

bash

ls ~/.claude/skills/gstack/

檢查 SKILL.md 檔案：

bash

find ~/.claude/skills/gstack -name "SKILL.md" -type f

驗證 Claude Code 版本（較舊的版本可能不支援 skills）：

bash

claude --version

重新啟動 Claude Code —— skills 在啟動時載入
檢查 Claude Code 是否讀取了正確的 skills 目錄：

bash

ls ~/.claude/skills/

權限錯誤

症狀：./setup 失敗，顯示「Permission denied」

修復：

bash

chmod +x ~/.claude/skills/gstack/setup

如果 Chromium 二進位檔也有問題：

bash

chmod +x ~/.claude/skills/gstack/browse/chromium*

Git Worktree 衝突（平行化）

症狀：Conductor 無法建立 worktree

診斷：

bash

git worktree list

修復：清理過期的 worktree：

bash

git worktree prune

如果 worktree 目錄仍然存在於磁碟上：

bash

# 列出並手動移除過期的 worktree 目錄
git worktree list | grep -v "main" | awk '{print $1}'

記憶體使用量過高

症狀：QA 或平行 sprint 期間系統變慢

快速修復：

關閉不必要的應用程式
在 QA session 之間終止瀏覽器 daemon：

bash

pkill -f chromium

減少平行 sprint 數量
監控記憶體使用量：

bash

# macOS
vm_stat | head -5

# Linux
free -h

API 速率限制

症狀：指令失敗，出現速率限制錯誤

修復：

等待並重試——速率限制是暫時的
減少平行 sprint 數量
升級你的 Anthropic API 方案
將 sprint 分散到一天中，而不是一次全部執行

13. Maintenance and Updates

GStack is a living project. Staying current matters.

Update Workflow

bash

# 1. Check for updates
cd ~/.claude/skills/gstack
git fetch

# 2. See what changed
git log HEAD..origin/main --oneline

# 3. If updates look good, pull
git pull

# 4. Re-run setup (always do this after pulling)
./setup

Automating Update Checks

Add an alias to your shell profile for convenience:

bash

# Add to ~/.zshrc or ~/.bashrc
alias gstack-update='cd ~/.claude/skills/gstack && git pull && ./setup && cd -'
alias gstack-check='cd ~/.claude/skills/gstack && git fetch && git log HEAD..origin/main --oneline && cd -'

Then:

bash

gstack-check    # See if updates are available
gstack-update   # Pull and re-setup

Per-Project Update Process

For per-project installations, updating is more deliberate:

bash

# 1. Pull latest into temp location
git clone https://github.com/garrytan/gstack.git /tmp/gstack-latest

# 2. Compare versions
diff -r /path/to/project/.claude/skills/gstack /tmp/gstack-latest

# 3. If satisfied, replace
rm -rf /path/to/project/.claude/skills/gstack
cp -r /tmp/gstack-latest /path/to/project/.claude/skills/gstack

# 4. Run setup
cd /path/to/project/.claude/skills/gstack && ./setup

# 5. Commit the update
cd /path/to/project
git add .claude/skills/gstack
git commit -m "chore: update GStack to latest version"

Backup Before Updates

If you've customized any GStack files:

bash

cp -r ~/.claude/skills/gstack ~/.claude/skills/gstack-backup-$(date +%Y%m%d)

This ensures you can roll back if an update breaks your customizations.

13. 維護與更新

GStack 是一個持續發展的專案。保持最新版本很重要。

更新工作流

bash

# 1. 檢查更新
cd ~/.claude/skills/gstack
git fetch

# 2. 查看有什麼變更
git log HEAD..origin/main --oneline

# 3. 如果更新看起來沒問題，拉取
git pull

# 4. 重新執行 setup（拉取後一定要做這一步）
./setup

自動化更新檢查

在你的 shell 設定檔中添加別名以方便使用：

bash

# 添加到 ~/.zshrc 或 ~/.bashrc
alias gstack-update='cd ~/.claude/skills/gstack && git pull && ./setup && cd -'
alias gstack-check='cd ~/.claude/skills/gstack && git fetch && git log HEAD..origin/main --oneline && cd -'

然後：

bash

gstack-check    # 查看是否有可用更新
gstack-update   # 拉取並重新設定

專案內安裝的更新流程

對於專案內安裝，更新過程更需要慎重：

bash

# 1. 拉取最新版到臨時位置
git clone https://github.com/garrytan/gstack.git /tmp/gstack-latest

# 2. 比較版本
diff -r /path/to/project/.claude/skills/gstack /tmp/gstack-latest

# 3. 如果滿意，替換
rm -rf /path/to/project/.claude/skills/gstack
cp -r /tmp/gstack-latest /path/to/project/.claude/skills/gstack

# 4. 執行 setup
cd /path/to/project/.claude/skills/gstack && ./setup

# 5. 提交更新
cd /path/to/project
git add .claude/skills/gstack
git commit -m "chore: update GStack to latest version"

更新前備份

如果你自訂了任何 GStack 檔案：

bash

cp -r ~/.claude/skills/gstack ~/.claude/skills/gstack-backup-$(date +%Y%m%d)

這確保如果更新破壞了你的自訂內容，你可以回復。

14. Quick Reference Card

Keep this section bookmarked for daily use.

Installation (One-Liner)

bash

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

All Commands at a Glance

Command	What It Does	Phase
`/office-hours`	Strategic product thinking	Planning
`/plan-ceo-review`	CEO-level strategy review	Planning
`/plan-eng-review`	Architecture design review	Planning
`/review`	Code audit	Post-build
`/qa`	Browser QA + auto-fix	Post-build
`/qa-only`	Browser QA (report only)	Post-build
`/browse`	Browser automation	Anytime
`/ship`	Create PR and release	Release
`/retro`	Sprint retrospective	Post-release
`/careful`	Enable destructive warnings	Session start
`/freeze {path}`	Lock files from editing	Session start

Recommended Sprint Flow

/careful → /office-hours → /plan-ceo-review → /plan-eng-review
→ [build] → /review → /qa → /ship → /retro

Essential Troubleshooting

Problem	Quick Fix
Bun not found	`curl -fsSL https://bun.sh/install \| bash`
Browser won't start	`pkill -f chromium` then retry
Commands unknown	Check `~/.claude/skills/gstack/` exists, restart Claude Code
Permission denied	`chmod +x ~/.claude/skills/gstack/setup`
Port conflict	`lsof -i :9222` then `kill -9 {PID}`
Stale worktrees	`git worktree prune`

Update GStack

bash

cd ~/.claude/skills/gstack && git pull && ./setup

Cost Rule of Thumb

One full sprint (all 8 commands) costs roughly $1-2 in API usage. Plan accordingly.

14. 快速參考卡

將本節加入書籤，日常使用。

安裝（一行指令）

bash

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

所有指令一覽

指令	功能	階段
`/office-hours`	策略性產品思維	規劃
`/plan-ceo-review`	CEO 層級策略審查	規劃
`/plan-eng-review`	架構設計審查	規劃
`/review`	程式碼審計	建構後
`/qa`	瀏覽器 QA + 自動修復	建構後
`/qa-only`	瀏覽器 QA（僅報告）	建構後
`/browse`	瀏覽器自動化	任何時候
`/ship`	建立 PR 並發佈	發佈
`/retro`	Sprint 回顧	發佈後
`/careful`	啟用破壞性警告	Session 開始
`/freeze {path}`	鎖定檔案不可編輯	Session 開始

基本問題排除

問題	快速修復
Bun 未找到	`curl -fsSL https://bun.sh/install \| bash`
瀏覽器無法啟動	`pkill -f chromium` 然後重試
指令未知	確認 `~/.claude/skills/gstack/` 存在，重啟 Claude Code
權限拒絕	`chmod +x ~/.claude/skills/gstack/setup`
連接埠衝突	`lsof -i :9222` 然後 `kill -9 {PID}`
過期的 worktree	`git worktree prune`

更新 GStack

bash

cd ~/.claude/skills/gstack && git pull && ./setup

成本經驗法則

一個完整的 sprint（全部 8 個指令）大約花費 $1-2 的 API 使用量。請據此規劃。

GStack Setup, Deployment, and Practical Guide ​

With Key Considerations ​

GStack 建置部署與實戰注意事項完全指南 ​

從環境準備到生產級工作流 ​

Why GStack? ​

為什麼選 GStack？ ​

1. Prerequisites Checklist ​

Installing Missing Dependencies ​

Pre-Flight Verification Script ​

1. 環境需求檢查清單 ​

安裝缺少的依賴 ​

預檢腳本 ​

2. Installation ​

Option A: Global Installation (Recommended) ​

Option B: Per-Project Installation ​

Verifying the Installation ​

2. 安裝 ​

方案 A：全域安裝（推薦） ​

方案 B：專案內安裝 ​

驗證安裝 ​

3. Post-Installation: CLAUDE.md Configuration ​

Check Your Existing CLAUDE.md ​

Manual Configuration ​

Customizing CLAUDE.md for GStack Workflows ​

CLAUDE.md Best Practices for GStack ​

3. 安裝後配置：CLAUDE.md 設定 ​

檢查現有的 CLAUDE.md ​

手動配置 ​

為 GStack 工作流自訂 CLAUDE.md ​

針對 GStack 的 CLAUDE.md 最佳實踐 ​

4. The Nine Slash Commands — A Complete Reference ​

Sprint Workflow Commands ​

Testing Commands ​

Safety Commands ​

Command Details ​

4. 九個 Slash Command——完整參考 ​

Sprint 工作流指令 ​

測試指令 ​

安全指令 ​

指令詳解 ​

5. Verifying Installation — Testing Each Command ​

Quick Smoke Test ​

Verification Checklist ​

If a Command Isn't Recognized ​

5. 驗證安裝——測試每個指令 ​

快速冒煙測試 ​

驗證清單 ​

如果指令未被識別 ​

6. Browser Daemon Setup and Configuration ​

How the Browser Daemon Works ​

Configuring Authenticated Testing ​

Browser Daemon Resource Management ​

Port Conflicts ​

6. 瀏覽器 Daemon 設定與配置 ​

瀏覽器 Daemon 的運作方式 ​

配置認證測試 ​

瀏覽器 Daemon 資源管理 ​

連接埠衝突 ​

7. Sprint Workflow Walkthrough — A Practical Example ​

Step 1: Start with /office-hours ​

Step 2: Strategy Review with /plan-ceo-review ​

Step 3: Architecture with /plan-eng-review ​

Step 4: Build the Feature ​

Step 5: Code Audit with /review ​

Step 6: QA Testing with /qa ​

Step 7: Ship It with /ship ​

Step 8: Retrospective with /retro ​

Time Investment ​

7. Sprint 工作流實戰演練——一個完整的實際案例 ​

步驟 1：從 /office-hours 開始 ​

步驟 2：用 /plan-ceo-review 進行策略審查 ​

步驟 3：用 /plan-eng-review 進行架構規劃 ​

步驟 4：建構功能 ​

步驟 5：用 /review 進行程式碼審計 ​

步驟 6：用 /qa 進行 QA 測試 ​

步驟 7：用 /ship 發佈 ​

步驟 8：用 /retro 回顧 ​

時間投入 ​

8. Safety Features Configuration ​

/careful — Destructive Command Warnings ​

GStack Setup, Deployment, and Practical Guide

With Key Considerations

GStack 建置部署與實戰注意事項完全指南

從環境準備到生產級工作流

Why GStack?

為什麼選 GStack？

1. Prerequisites Checklist

Installing Missing Dependencies

Pre-Flight Verification Script

1. 環境需求檢查清單

安裝缺少的依賴

預檢腳本

2. Installation

Option A: Global Installation (Recommended)

Option B: Per-Project Installation

Verifying the Installation

2. 安裝

方案 A：全域安裝（推薦）

方案 B：專案內安裝

驗證安裝

3. Post-Installation: CLAUDE.md Configuration

Check Your Existing CLAUDE.md

Manual Configuration

Customizing CLAUDE.md for GStack Workflows

CLAUDE.md Best Practices for GStack

3. 安裝後配置：CLAUDE.md 設定

檢查現有的 CLAUDE.md

手動配置

為 GStack 工作流自訂 CLAUDE.md

針對 GStack 的 CLAUDE.md 最佳實踐

4. The Nine Slash Commands — A Complete Reference

Sprint Workflow Commands

Testing Commands

Safety Commands

Command Details

4. 九個 Slash Command——完整參考

Sprint 工作流指令

測試指令

安全指令

指令詳解

5. Verifying Installation — Testing Each Command

Quick Smoke Test

Verification Checklist

If a Command Isn't Recognized

5. 驗證安裝——測試每個指令

快速冒煙測試

驗證清單

如果指令未被識別

6. Browser Daemon Setup and Configuration

How the Browser Daemon Works

Configuring Authenticated Testing

Browser Daemon Resource Management

Port Conflicts

6. 瀏覽器 Daemon 設定與配置

瀏覽器 Daemon 的運作方式

配置認證測試

瀏覽器 Daemon 資源管理

連接埠衝突

7. Sprint Workflow Walkthrough — A Practical Example

Step 1: Start with `/office-hours`

Step 2: Strategy Review with `/plan-ceo-review`

Step 3: Architecture with `/plan-eng-review`

Step 4: Build the Feature

Step 5: Code Audit with `/review`

Step 6: QA Testing with `/qa`

Step 7: Ship It with `/ship`

Step 8: Retrospective with `/retro`

Time Investment

7. Sprint 工作流實戰演練——一個完整的實際案例

步驟 1：從 `/office-hours` 開始

步驟 2：用 `/plan-ceo-review` 進行策略審查

步驟 3：用 `/plan-eng-review` 進行架構規劃

步驟 4：建構功能

步驟 5：用 `/review` 進行程式碼審計

步驟 6：用 `/qa` 進行 QA 測試

步驟 7：用 `/ship` 發佈

步驟 8：用 `/retro` 回顧

時間投入

8. Safety Features Configuration

`/careful` — Destructive Command Warnings