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/             # 체계적인 근본 원인 디버깅 (철칙: 조사 없이는 수정도 없다)
├── 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 교차 모델 분석 (제2의 의견)
├── browse/                 # 브라우저 자동화 (지속성 Chromium, 명령당 ~100ms)
├── setup-browser-cookies/  # 실제 브라우저에서 쿠키 가져오기 (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 등)

제품 디자인부터 아키텍처 검토, 개발, 보안, QA, 배포, 회고에 이르는 전체 수명 주기를 아우르는 28가지 기술입니다.

---

단계별 가이드

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개의 필수 질문을 통해 제품에 대한 아이디어를 재정의합니다. 핵심은 기능을 직접 설명하는 것이 아니라 **실제 페인 포인트(Pain Point)**를 말하는 것입니다.

대화 예시:

사용자: 매일 아침 캘린더를 기반으로 브리핑을 생성하는 기능이 필요해요.

gstack: 프레임워크를 다시 검토 중입니다. 당신은 "브리핑 생성기"라고 말했지만, 실제로 설명한 통증은 다음과 같습니다:
1. 여러 Google 캘린더로 인한 정보 파편화
2. 준비 시간의 과도한 소요
3. 결과물의 퀄리티 부족
당신이 실제로 구축하려는 것은 "개인용 수석 비서 AI"입니다.

범위를 재정의할까요? 아니면 왜 원래 범위가 맞는지 알려주시겠어요?

디자인 대화가 끝나면 gstack은 설계 문서를 생성하며, 이는 후속 검토 기술로 자동 전달됩니다.

2.2 /plan-ceo-review로 제품 전략 검토하기

/plan-ceo-review

gstack이 이전 단계의 설계 문서를 읽고 CEO/창업자 시각에서 사분면 검토를 수행합니다:

• 확장: 범위를 어디까지 넓힐 것인가?
• 선택적 확장: 핵심은 남기고 무엇을 쳐낼 것인가?
• 범위 유지: 현재 크기가 딱 적당함
• 축소: 가장 좁은 진입점에 집중

또한 3가지 구현 경로를 제시하며, 각 경로별로 사람과 AI의 작업 시간(Man-day)을 비교해 줍니다:

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] Refresh 루프 내 레이스 컨디션 — 권장 수정안:
A) Mutex lock 추가 (더 안전함, +15줄)
B) Debounce 추가 (더 간단함, +5줄)
동시성 시나리오의 완벽한 처리를 위해 A안을 추천합니다.

2.4 /qa로 애플리케이션 테스트하기

# 자신의 staging 주소로 교체하세요
/qa https://staging.myapp.com

gstack의 /qa는 지속성 Chromium 브라우저(쿠키 및 로그인 상태 재사용)를 실행하여 다음을 자동으로 수행합니다:

1. 페이지 접속 및 스크린샷 캡처
2. 주요 경로 클릭 (로그인 → 핵심 기능 → 엣지 케이스)
3. 버그 발견 → 원자적 커밋으로 수정 → 재검증
4. 각 수정 사항에 대한 회귀 테스트 생성

일반 자동화 테스트와의 차이점: 일반 테스트는 작성된 단언(Assertion)만 확인합니다. /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는 통과하지만 프로덕션에서 터질 버그를 찾는 것"입니다. Linter를 대체하는 것이 아니라 의미론적 분석을 수행합니다:

• 로직 오류 (조건 누락, 불균형한 브랜치)
• 동시성 문제 (Race condition, Deadlock 패턴)
• 보안 리스크 (인젝션, 인증 우회)

**/investigate**는 디버깅 전용입니다. 특정 버그가 반복될 때 실행하세요:

/investigate

gstack의 동작:

1. 가설 수립
2. 하나씩 검증 (수정하지 않고 조사만 수행)
3. 근본 원인 발견 시 중단 (철칙: 조사 없이 수정 없다)

3.3 출시 단계: ship, land-and-deploy, canary

/ship          # 코드 리뷰 통과 후 → PR 생성
/land-and-deploy  # PR 병합 → 배포 → 프로덕션 상태 확인
/canary        # 배포 후 30분간 지속 모니터링

/canary는 세 가지 지표를 모니터링합니다:

• 콘솔 에러율: 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 플래그는 unified diff 형식을 출력하여 작업 후 어떤 요소가 나타나고 사라졌는지, 내용이 어떻게 변했는지 알려줍니다.

4.3 로그인 상태 테스트

실제 브라우저에서 쿠키 가져오기:

# 인터랙티브 선택기 (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 인스턴스가 한 명의 "사람"이라면, 여러 인스턴스를 통해 각기 다른 Sprint 단계를 병렬로 실행할 수 있습니다.

gstack 공식 추천 도구인 Conductor를 사용하면 여러 Claude Code 인스턴스를 동시에 구동할 수 있습니다:

• 인스턴스 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 해제

---

자주 묻는 질문(FAQ)

1. 기술(Skill)이 보이지 않아요

# 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 관련 알려진 버그(bun#4253)로 인해, gstack은 자동으로 Node.js로 대체하여 실행합니다.

5. 쿠키 가져오기 실패

쿠키 가져오기는 macOS(시스템 Keychain 활용)만 지원합니다. Linux와 Windows는 현재 지원되지 않습니다.

Linux에서 로그인 상태가 필요한 페이지를 테스트하려면 쿠키를 JSON으로 수동 내보내기 하세요:

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

그 다음 명령어를 사용합니다:

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

6. 버전 업그레이드

# 방법 1: 업그레이드 기술 실행
/gstack-upgrade

# 방법 2: 수동으로 최신 코드 풀
cd ~/.claude/skills/gstack && git pull && ./setup

gstack-upgrade는 전역 설치인지 Vendored 설치인지 감지하여 각각 처리합니다.

---

확장 읽기 / 심화 학습

ETHOS.md — gstack의 핵심 철학 문서입니다. "Boil the Lake" 원칙: AI를 통해 완벽한 구현의 한계 비용을 0으로 만들어, "적당히" 타협하지 말 것을 강조합니다. 또한 "Search Before Building" 지식 체계를 설명합니다.

Autoplan — 명령어 한 번으로 CEO 검토 → 디자인 검토 → 엔지니어링 검토를 자동으로 연쇄 실행합니다. 기술을 일일이 호출하기 번거로울 때 유용하며, 주요 결정 노드에서 사용자의 컨펌을 기다립니다.

Conductor — gstack 공식 다중 세션 병렬 관리 도구입니다. 여러 Claude Code 인스턴스를 하나의 엔지니어링 팀처럼 조직하여 여러 기능을 동시에 추진할 수 있게 돕습니다.

소스 코드 읽기 경로:

1. browse/src/commands.ts — 모든 브라우저 명령의 등록부이자 단일 진실 공급원(SSOT)
2. browse/src/snapshot.ts — Ref 시스템의 핵심 구현 (ARIA 트리 → Playwright Locator)
3. scripts/gen-skill-docs.ts — SKILL.md 자동 생성 파이프라인
4. ARCHITECTURE.md — 전체 아키텍처 설계 문서

---