# gstack 심층 분석 보고서

**작성일:** 2026-03-23
**분석자:** dev3-team bot
**Repository:** https://github.com/garrytan/gstack
**버전:** 0.9.8.0

---

## 1. 개요

### 1.1 gstack이란?

**gstack**은 Garry Tan (Y Combinator CEO)이 개발한 **AI 코딩 워크플로우 자동화 도구**입니다. Claude Code를 20명의 가상 엔지니어링 팀으로 변환하는 시스템으로, 단 1명의 개발자가 하루에 10,000~20,000줄의 코드를 작성할 수 있게 합니다.

### 1.2 핵심 철학

1. **"Boil the Lake" (호수를 끓여라)**
   - AI 코딩에서는 완전성의 한계 비용이 거의 0에 수렴
   - 80% 해결책이 아닌 100% 완전 구현을 항상 선택
   - 80줄 vs 150줄의 차이는 AI에게 무의미

2. **"Search Before Building" (만들기 전에 검색하라)**
   - Layer 1: 검증된 패턴 (재발명하지 마라)
   - Layer 2: 새롭고 인기 있는 것 (비판적으로 검토)
   - Layer 3: 제1원칙 추론 (가장 가치 있음)
   - "Eureka Moment": 통념이 왜 틀렸는지 발견하면 기록

3. **"Golden Age" (황금기)**
   - 1명 + AI = 과거 20명 팀의 생산력
   - 압축 비율: 보일러플레이트 100x, 테스트 50x, 기능 구현 30x

---

## 2. 아키텍처

### 2.1 브라우저 자동화 (browse)

**핵심 통찰:** AI 에이전트의 브라우저 상호작용은 **서브초 지연 시간**과 **지속 상태**가 필요

```
Claude Code                     gstack
─────────                      ──────
                               ┌──────────────────────┐
  Tool call: $B snapshot -i    │  CLI (컴파일된 바이너리)│
  ─────────────────────────→   │  • 상태 파일 읽기      │
                               │  • POST /command      │
                               │    to localhost:PORT   │
                               └──────────┬───────────┘
                                          │ HTTP
                               ┌──────────▼───────────┐
                               │  Server (Bun.serve)   │
                               │  • 명령 분배           │
                               │  • Chromium 통신       │
                               │  • plain text 반환     │
                               └──────────┬───────────┘
                                          │ CDP
                               ┌──────────▼───────────┐
                               │  Chromium (headless)   │
                               │  • 지속적 탭           │
                               │  • 쿠키 유지           │
                               │  • 30분 유휴 타임아웃   │
                               └───────────────────────┘
```

**첫 호출 ~3초, 이후 ~100-200ms**

### 2.2 Ref 시스템

CSS 선택자 대신 **접근성 트리 기반 참조** 사용:

```
1. Agent: $B snapshot -i
2. Playwright accessibility.snapshot() 호출
3. 순차적 ref 할당: @e1, @e2, @e3...
4. 각 ref → Playwright Locator: getByRole(role, { name }).nth(index)
5. Map<string, RefEntry> 저장

이후:
7. Agent: $B click @e3
8. @e3 → Locator → locator.click()
```

**장점:**
- CSP (Content Security Policy) 문제 없음
- React/Vue/Svelte hydration 충돌 없음
- Shadow DOM 접근 가능

### 2.3 보안 모델

1. **Localhost 전용** - 네트워크에서 접근 불가
2. **Bearer 토큰 인증** - UUID 토큰, 모드 0o600
3. **쿠키 보안**
   - 키체인 접근 시 사용자 승인 필요
   - 메모리 내 복호화만 (디스크에 평문 저장 안 함)
   - 읽기 전용 DB 액세스
   - 로그에 쿠키 값 없음

### 2.4 로깅 아키텍처

3개의 링 버퍼 (50,000 항목 each):
- Console messages
- Network requests
- Dialog events

**비동기 플러시 (1초마다)** - HTTP 요청 블로킹 없음

---

## 3. 스킬 시스템 (28개)

### 3.1 스킬 목록

| 카테고리 | 스킬 | 역할 |
|---------|------|------|
| **Think** | `/office-hours` | YC Office Hours - 6가지 강제 질문 |
| **Plan** | `/plan-ceo-review` | CEO/Founder - 문제 재정의 |
| | `/plan-eng-review` | Eng Manager - 아키텍처 고정 |
| | `/plan-design-review` | Senior Designer - 디자인 0-10 평가 |
| | `/design-consultation` | Design Partner - 디자인 시스템 구축 |
| | `/autoplan` | Review Pipeline - 자동 리뷰 파이프라인 |
| **Build** | (자체 빌드 스킬 없음 - /office-hours 산출물 사용) |
| **Review** | `/review` | Staff Engineer - 프로덕션 버그 탐지 |
| | `/codex` | Second Opinion - OpenAI Codex 독립 리뷰 |
| | `/design-review` | Designer Who Codes - 디자인 수정 |
| | `/cso` | Chief Security Officer - OWASP + STRIDE |
| **Test** | `/qa` | QA Lead - 테스트 + 수정 + 검증 |
| | `/qa-only` | QA Reporter - 버그 리포트만 |
| | `/benchmark` | Performance Engineer - 성능 베이스라인 |
| **Ship** | `/ship` | Release Engineer - PR 생성 |
| | `/land-and-deploy` | Release Engineer - PR 병합 + 배포 |
| | `/canary` | SRE - 배포 후 모니터링 |
| | `/document-release` | Technical Writer - 문서 업데이트 |
| **Reflect** | `/retro` | Eng Manager - 주간 회고 |
| | `/investigate` | Debugger - 근원 원인 디버깅 |
| **Power Tools** | `/browse` | QA Engineer - 헤드리스 브라우저 |
| | `/setup-browser-cookies` | Session Manager - 쿠키 가져오기 |
| | `/careful` | Safety Guardrails - 파괴적 명령 경고 |
| | `/freeze` | Edit Lock - 디렉토리 편집 제한 |
| | `/guard` | Full Safety - careful + freeze |
| | `/unfreeze` | Unlock - 제한 해제 |
| | `/setup-deploy` | Deploy Configurator - 배포 설정 |
| | `/gstack-upgrade` | Self-Updater - 자동 업그레이드 |

### 3.2 스킬 워크플로우 구조

모든 스킬은 공통 **Preamble**으로 시작:

```bash
# 1. 업데이트 체크
# 2. 세션 추적 (3+ 세션 → ELI16 모드)
# 3. Contributor 모드 체크
# 4. Proactive 설정
# 5. Branch 감지
# 6. Repo 모드 (solo/collaborative)
# 7. Lake intro (1회만)
# 8. Telemetry 프롬프트 (1회만)
```

### 3.3 AskUserQuestion 포맷 (공통)

1. **Re-ground** - 프로젝트, 브랜치, 현재 작업 재확인
2. **Simplify** - 16세도 이해할 수 있는 언어로
3. **Recommend** - `RECOMMENDATION: Choose X because Y`
4. **Options** - `A) ... B) ... C) ...` (노력 표시: human: ~X / CC: ~Y)

---

## 4. 주요 스킬 상세

### 4.1 `/office-hours` - YC Office Hours

**두 가지 모드:**

**Startup Mode (창업):**
- Q1: Demand Reality - "누가 진짜로 원하는가?"
- Q2: Status Quo - "현재 어떻게 해결하는가?"
- Q3: Desperate Specificity - "실제 사람 이름, 직책은?"
- Q4: Narrowest Wedge - "이번 주에 돈 받을 수 있는 최소 버전은?"
- Q5: Observation & Surprise - "실제 사용을 지켜봤는가?"
- Q6: Future-Fit - "3년 후 세상이 달라지면 더 중요해지는가?"

**Builder Mode (취미/학습):**
- "가장 멋진 버전은?"
- "누구에게 보여줄 것인가?"
- "가장 빠른 경로는?"

**산출물:** Design Doc (`~/.gstack/projects/{slug}/{user}-{branch}-design-{datetime}.md`)

### 4.2 `/review` - Pre-Landing PR Review

**단계:**
1. Base branch 감지
2. Scope Drift Detection - "요청한 대로 만들었나?"
3. Checklist 로드
4. Greptile 코멘트 확인 (있으면)
5. Diff 가져오기
6. **Two-pass review:**
   - Pass 1 (CRITICAL): SQL, Race Condition, LLM Trust Boundary, Enum Completeness
   - Pass 2 (INFORMATIONAL): Conditional Side Effects, Magic Numbers, Dead Code, Test Gaps
7. Design Review (frontend 변경 시)
8. Test Coverage Diagram (ASCII)
9. Fix-First Review (AUTO-FIX / ASK)
10. Adversarial Review (diff 크기에 따라 자동 스케일)

**Fix-First 원칙:** 모든 발견은 action - AUTO-FIX는 즉시 적용, ASK는 배치 질문

### 4.3 `/qa` - QA Testing

**모드:**
- **Diff-aware** (자동) - 브랜치 변경사항만 테스트
- **Full** - 전체 앱 탐색
- **Quick** - 30초 스모크 테스트
- **Regression** - 이전 baseline과 비교

**Phase:**
1. Initialize
2. Authenticate (필요 시)
3. Orient - 앱 맵핑
4. Explore - 체계적 페이지 방문
5. Document - 즉시 이슈 기록
6. Wrap Up - Health Score 계산
7. Triage - 심각도별 분류
8. Fix Loop - 수정 → 커밋 → 재테스트 → 회귀 테스트
9. Final QA
10. Report
11. TODOS.md 업데이트

**Health Score Rubric:**
- Console (15%), Links (10%), Visual (10%), Functional (20%)
- UX (15%), Performance (10%), Content (5%), Accessibility (15%)

### 4.4 `/ship` - PR 생성

**사전 체크:**
1. 테스트 실행
2. Coverage audit
3. Review 완료 확인
4. Base branch와 동기화

**PR 생성:**
- 제목, 설명 자동 생성
- 테스트 결과 포함
- Review 요약 포함

---

## 5. 기술 스택

### 5.1 왜 Bun인가?

1. **컴파일된 바이너리** - ~58MB 단일 실행 파일, node_modules 없음
2. **네이티브 SQLite** - 쿠키 DB 직접 읽기
3. **네이티브 TypeScript** - 컴파일 단계 없음
4. **내장 HTTP 서버** - 프레임워크 불필요

### 5.2 의존성

```json
{
  "dependencies": {
    "playwright": "^1.58.2",
    "diff": "^7.0.0"
  },
  "devDependencies": {
    "@anthropic-ai/sdk": "^0.78.0"
  }
}
```

### 5.3 명령 카테고리

| 카테고리 | 명령 |
|---------|-----|
| **Navigation** | goto, back, forward, reload, url |
| **Reading** | text, html, links, forms, accessibility |
| **Inspection** | js, eval, css, attrs, is, console, network, dialog, cookies, storage, perf |
| **Interaction** | click, fill, select, hover, type, press, scroll, wait, upload, viewport, cookie, dialog-accept, dialog-dismiss |
| **Visual** | screenshot, pdf, responsive, diff |
| **Snapshot** | snapshot (ref 시스템) |
| **Meta** | chain |
| **Tabs** | tabs, tab, newtab, closetab |
| **Server** | status, stop, restart, handoff, resume |

---

## 6. 템플릿 시스템

### 6.1 SKILL.md 자동 생성

```
SKILL.md.tmpl (사람이 작성한 prose + placeholders)
       ↓
gen-skill-docs.ts (소스 코드 메타데이터 읽기)
       ↓
SKILL.md (커밋됨, 자동 생성 섹션)
```

### 6.2 Placeholder

| Placeholder | 소스 | 생성 내용 |
|-------------|------|----------|
| `{{COMMAND_REFERENCE}}` | commands.ts | 명령 테이블 |
| `{{SNAPSHOT_FLAGS}}` | snapshot.ts | 플래그 참조 |
| `{{PREAMBLE}}` | gen-skill-docs.ts | 시작 블록 |
| `{{BROWSE_SETUP}}` | gen-skill-docs.ts | 바이너리 발견 + 설정 |
| `{{QA_METHODOLOGY}}` | gen-skill-docs.ts | QA 방법론 |
| `{{DESIGN_METHODOLOGY}}` | gen-skill-docs.ts | 디자인 감사 방법론 |

---

## 7. 테스트 인프라

### 7.1 테스트 계층

| 계층 | 내용 | 비용 | 속도 |
|-----|------|-----|------|
| Tier 1 | 정적 검증 ($B 명령 파싱) | 무료 | <5s |
| Tier 2 | E2E (claude -p) | ~$3.85 | ~20min |
| Tier 3 | LLM-as-judge | ~$0.15 | ~30s |

### 7.2 Session Runner

```typescript
// E2E 테스트는 독립적인 subprocess로 claude -p 실행
// Agent SDK 사용 안 함 (중첩 불가)

1. 프롬프트를 임시 파일에 작성
2. sh -c 'cat prompt | claude -p --output-format stream-json --verbose'
3. NDJSON 스트리밍
4. 타임아웃 경쟁
5. 전체 NDJSON 파싱
```

---

## 8. 원격 측정 (Telemetry)

### 8.1 옵트인 방식

- **기본값: OFF**
- 첫 실행 시 질문
- 전송 항목: skill name, duration, success/fail, version, OS
- **절대 전송 안 함:** code, file paths, repo names, prompts

### 8.2 설정

```bash
gstack-config set telemetry community  # device ID 포함
gstack-config set telemetry anonymous  # 카운터만
gstack-config set telemetry off        # 완전 차단
```

---

## 9. 우리 시스템과의 비교

### 9.1 유사점

| gstack | 우리 시스템 |
|--------|-----------|
| 28개 스킬 | 전문가 토론 시스템 |
| SKILL.md | SKILL.md |
| Preamble | Every Session 체크 |
| AskUserQuestion | 제이회장님 확인 |
| Design Doc | Spec JSON |
| Review → Fix → Verify | QC 프로세스 |

### 9.2 차이점

| gstack | 우리 시스템 |
|--------|-----------|
| 1인 개발자 대상 | 보험설계사 SNS 콘텐츠 |
| 범용 코딩 워크플로우 | 특화 도메인 (보험) |
| Claude Code 전용 | OpenClaw (다양한 모델) |
| Markdown 기반 스킬 | Python 스크립트 + Markdown |
| 단일 세션 | 다중 에이전트 (dev1~3팀) |
| Browse (Playwright) | Browser (OpenClaw) |
| Telemetry (Supabase) | 로컬 로그만 |

### 9.3 적용 가능한 패턴

1. **Ref 시스템** - 접근성 트리 기반 요소 선택
2. **Fix-First Review** - AUTO-FIX / ASK 분류
3. **Health Score** - 다차원 점수 계산
4. **Preamble** - 세션 시작 시 공통 체크
5. **Template 시스템** - 코드에서 문서 자동 생성
6. **Three Layers of Knowledge** - 검색 우선 원칙
7. **Boil the Lake** - 완전성 우선

---

## 10. 제언

### 10.1 즉시 적용 가능

1. **Preamble 표준화** - 모든 에이전트 시작 시 공통 체크
2. **Fix-First 분류** - QC에서 AUTO-FIX / ASK 명확히 구분
3. **Health Score** - 콘텐츠 품질 다차원 평가

### 10.2 중기 적용

1. **Ref 시스템** - 카드뉴스 렌더링 테스트 자동화
2. **Template 시스템** - 프롬프트 자동 생성
3. **Telemetry** - 익명 사용 통계 수집 (옵트인)

### 10.3 장기 검토

1. **Bun 기반 browse 서버** - 현재 OpenClaw Browser와 비교
2. **단일 세션 vs 다중 에이전트** - 효율성 비교
3. **Skill 표준화** - ClawHub 호환 SKILL.md 형식

---

## 11. 결론

**gstack은 "AI 시대의 소프트웨어 팩토리"입니다.**

- Garry Tan이 실제로 매일 사용하는 도구
- MIT 라이선스, 무료, 오픈소스
- 1명이 20명 팀의 생산력을 냄
- 철학: 완전성 우선, 검색 우선, Golden Age

**우리가 배울 점:**
- 워크플로우 표준화
- Fix-First 리뷰
- Preamble 자동화
- 다차원 품질 평가

---

**보고서 작성 완료**