# gstack 심층 분석 보고서
> 작성일: 2026-03-23 | 작성자: 다그다(dev3팀장) | task-id: task-839.1
> 클론 경로: /tmp/gstack

---

## 개요

**gstack**은 Garry Tan(Y Combinator CEO)이 공개한 오픈소스 AI 개발 워크플로우 시스템이다.
Claude Code를 "가상 개발팀"으로 변환하여 한 사람이 하루 10,000~20,000줄의 프로덕션 코드를
파트타임으로 작성할 수 있게 한다. MIT 라이선스, 28개 스킬, 헤드리스 브라우저 내장.

---

## Phase 1: 구조 파악

### 디렉토리 구조

```
gstack/
├── browse/               # 핵심: 헤드리스 Chromium 브라우저 CLI+서버
│   ├── src/              # TypeScript 소스 (commands.ts, server.ts, snapshot.ts 등 16개 파일)
│   ├── test/             # 통합 테스트 + fixture HTML 13개
│   └── dist/             # 컴파일된 바이너리
├── scripts/              # 빌드 + DX 도구 (gen-skill-docs.ts 등)
├── test/                 # E2E 테스트 + eval 인프라 (skill-e2e-*.test.ts)
├── supabase/             # 원격 텔레메트리 (Supabase/Postgres)
├── bin/                  # CLI 유틸리티 (gstack-config, gstack-slug 등 10개)
├── [스킬명]/             # 각 스킬 디렉토리 (26개)
│   ├── SKILL.md          # 생성된 스킬 파일 (에이전트가 읽음)
│   └── SKILL.md.tmpl     # 인간이 편집하는 템플릿
├── SKILL.md(.tmpl)       # 메인 gstack 스킬 (browse + 스킬 라우팅)
├── AGENTS.md             # 에이전트 인식 진입점
├── CLAUDE.md             # 개발자용 컨텍스트 (빌드 명령어, 관례)
├── ARCHITECTURE.md       # 설계 결정 문서
├── ETHOS.md              # 빌더 철학 (Boil the Lake, Search Before Building)
├── conductor.json        # Conductor 병렬 세션 설정
└── package.json          # Bun 빌드 스크립트 + 의존성
```

### 의존성 파일 분석

**package.json (v0.9.8.0)**
- 런타임 의존성: `playwright ^1.58.2`, `diff ^7.0.0` (단 2개)
- 개발 의존성: `@anthropic-ai/sdk ^0.78.0` (eval 전용)
- 엔진: `bun >=1.0.0` (필수)
- 빌드: TypeScript → 단일 실행파일 컴파일 (`bun build --compile`)

**설계 원칙**: 런타임 의존성을 최소화하고, 모든 도구를 바이너리로 컴파일해 설치 마찰을 제거

### 핵심 설정 파일

- `.env.example`: `ANTHROPIC_API_KEY`만 필요 (eval 실행 시). 평상시 불필요.
- `conductor.json`: Conductor 세션 관리 (dev-setup/dev-teardown 스크립트 연결)
- `~/.gstack/config.yaml`: 런타임 설정 (telemetry, proactive, auto_upgrade)
- `~/.gstack/browse.json`: 브라우저 데몬 상태 파일 (PID, port, token)

---

## Phase 2: 코드 전수 분석

### 파일별 역할 정리

| 파일/디렉토리 | 역할 |
|---|---|
| `browse/src/commands.ts` | **단일 진실 소스** — 모든 browse 명령어를 READ/WRITE/META 3개 Set으로 정의. 서버/문서생성/검증이 모두 이 파일 참조 |
| `browse/src/server.ts` | Bun.serve() HTTP 서버 — 명령어 dispatch, 브라우저 제어 |
| `browse/src/browser-manager.ts` | Chromium 데몬 관리 — Playwright 래퍼, @ref 시스템, 로그 링 버퍼 |
| `browse/src/snapshot.ts` | ARIA 트리 → @e/c ref 변환 + SNAPSHOT_FLAGS 메타데이터 |
| `browse/src/cli.ts` | 컴파일 진입점 — 상태 파일 읽기, 서버 시작/통신 |
| `browse/src/config.ts` | 설정 읽기/쓰기 (YAML) |
| `browse/src/cookie-import-browser.ts` | macOS Keychain 쿠키 복호화 (PBKDF2 + AES-128-CBC) |
| `scripts/gen-skill-docs.ts` | **tmpl → SKILL.md 생성기** — 코드에서 자동으로 플레이스홀더 채움 |
| `scripts/skill-check.ts` | 스킬 상태 대시보드 |
| `test/helpers/session-runner.ts` | `claude -p` 서브프로세스 실행 + NDJSON 파싱 |
| `test/helpers/eval-store.ts` | E2E 결과 저장 (원자적 쓰기, 부분 결과 지속) |
| `test/helpers/llm-judge.ts` | Sonnet을 judge로 사용한 문서 품질 평가 |
| `careful/bin/check-careful.sh` | PreToolUse 훅 — 파괴적 명령어 탐지 + 경고 |
| `supabase/migrations/001_telemetry.sql` | 텔레메트리 스키마 (3개 테이블, RLS, 뷰 2개) |
| `[스킬]/SKILL.md.tmpl` | 각 전문가 역할 정의 템플릿 (26개 스킬) |

### 아키텍처 패턴

#### 1. 데몬 모델 (browse 서버)
```
CLI (컴파일 바이너리)
  → 상태파일 읽기 (~/.gstack/browse.json)
  → HTTP POST to localhost:{random_port}
  → Bearer 토큰 인증
  → Bun.serve() 서버 → Playwright CDP → Chromium
```
- 초기 시작: ~3초 (Chromium 실행)
- 이후 명령: ~100-200ms
- 30분 idle → 자동 종료
- PID 죽으면 → 다음 호출 시 자동 재시작

#### 2. Ref 시스템 (@e/@c refs)
```
$B snapshot -i
  → page.accessibility.snapshot() (ARIA 트리)
  → 순차 번호 부여: @e1, @e2, @e3...
  → Map<string, {role, name, Locator}> 저장
$B click @e3
  → refMap.get("e3")
  → locator.count() (stale 감지, ~5ms)
  → locator.click()
```
DOM mutation 없이 Playwright Locator 기반 → CSP/Shadow DOM/React 하이드레이션 무영향

#### 3. SKILL.md 템플릿 시스템
```
SKILL.md.tmpl (인간 작성)
  → gen-skill-docs.ts 실행
  → commands.ts에서 명령어 메타데이터 추출
  → {{COMMAND_REFERENCE}}, {{PREAMBLE}} 등 플레이스홀더 치환
  → SKILL.md (커밋됨, 에이전트 읽기)
```
코드가 변경되면 문서가 자동 동기화 → 문서 드리프트 원천 차단

#### 4. 훅(Hook) 기반 안전장치
YAML 프론트매터에서 `hooks.PreToolUse` 선언 → Claude Code가 도구 호출 전 스크립트 실행
```yaml
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "bash ${CLAUDE_SKILL_DIR}/bin/check-careful.sh"
```
`check-careful.sh`가 stdin으로 JSON 입력 받아 → `permissionDecision: "ask"` 반환 → 사용자 확인

#### 5. 3계층 테스트 전략
| Tier | 대상 | 비용 | 속도 |
|---|---|---|---|
| 1 (Static) | $B 명령어 파싱/검증, observability 유닛 | 무료 | <5초 |
| 2 (E2E) | `claude -p` 실제 세션 실행 | ~$3.85 | ~20분 |
| 3 (LLM-as-judge) | Sonnet이 문서 품질 평가 | ~$0.15 | ~30초 |

**차이점**: diff 기반 테스트 선택 (`touchfiles.ts` → 변경 파일과 관련 테스트만 실행)

### 핵심 로직 흐름

**스킬 호출 → 실행 흐름**:
```
사용자: /review
  → Claude가 review/SKILL.md 로드
  → Preamble bash 실행 (업데이트 체크, 세션 추적, 텔레메트리 시작)
  → 스킬 로직 실행 (git diff 분석, 버그 발견, 자동 수정)
  → 텔레메트리 종료 로그 (백그라운드)
```

**스프린트 체인**:
```
/office-hours → 디자인 문서 생성
  → /plan-ceo-review → 설계 도전
  → /plan-eng-review → 아키텍처 확정
  → 코딩 (Claude Code 직접)
  → /review → 버그 발견
  → /qa → 브라우저 테스트
  → /ship → PR 생성
  → /land-and-deploy → 배포 완료
  → /retro → 회고
```
각 스킬이 이전 스킬 산출물을 읽음 → "연결된 팀"

### API/인터페이스 구조

**browse HTTP API** (localhost only):
- `POST /command` — 명령어 실행 (Bearer 토큰 필수)
- `GET /health` — 헬스체크 (토큰 불필요)
- `GET /cookie-picker` — 쿠키 선택 UI (토큰 불필요)

**스킬 YAML 프론트매터 표준**:
```yaml
---
name: skill-name
version: x.y.z
description: |
  트리거 조건 + 사용 시점 설명
allowed-tools:
  - Bash, Read, Edit, Write, Grep, Glob, AskUserQuestion, WebSearch
hooks:
  PreToolUse:
    - matcher: "Bash|Edit|Write"
      hooks:
        - type: command
          command: "bash ${CLAUDE_SKILL_DIR}/bin/script.sh"
---
```

### 에러 처리 / 로깅 / 설정 관리

**에러 철학**: "AI 에이전트를 위한 에러 메시지" — Playwright 네이티브 에러를 `wrapError()`로 재작성
- "Element not found" → "Element not found. Run `snapshot -i` to see available elements."
- 크래시 시 서버 즉시 종료 → 다음 CLI 호출이 자동 재시작

**로깅 아키텍처**: 3개 원형 버퍼 (console/network/dialog, 각 50,000개)
- HTTP 요청은 디스크 I/O에 블록되지 않음
- 1초마다 비동기 플러시 → 로그 파일 append-only

**설정 계층**:
1. CLAUDE.md (프로젝트별 설정, 항상 우선)
2. `~/.gstack/config.yaml` (전역 사용자 설정)
3. 스킬 내부 기본값

---

## Phase 3: 심층 인사이트 도출

### 핵심 혁신 포인트

#### A1. "문서가 코드에서 생성된다" 패턴
SKILL.md.tmpl → gen-skill-docs.ts → SKILL.md
코드의 함수 시그니처, 플래그 목록이 문서에 자동 반영된다.
**결과**: SKILL.md와 실제 코드가 절대 어긋나지 않는다. 문서 드리프트 불가능.

#### A2. Preamble 공유 컴포넌트
모든 스킬이 동일한 `{{PREAMBLE}}` 블록을 공유한다 (업데이트 체크, 세션 추적, 텔레메트리, AskUserQuestion 형식, REPO_MODE).
→ 일관성 보장 + 한 곳 수정으로 28개 스킬 전체 업데이트

#### A3. REPO_MODE (solo vs collaborative)
저장소 ownership을 자동 감지:
- **solo**: 80%+ 단일 기여자 → 이슈 발견 시 즉시 수정 제안
- **collaborative**: 다수 기여자 → 이슈 발견 시 질문만
"자동화 수준"이 맥락에 맞게 조정된다.

#### A4. 3-Stop Escalation Rule
"3회 실패 시 STOP + BLOCKED 보고"를 모든 스킬에 내장.
AI가 무한 루프에 빠지지 않도록 하드 게이트.

#### A5. PreToolUse 훅 + "careful" 패턴
`check-careful.sh`가 모든 Bash 명령어를 인터셉트해 파괴적 패턴 탐지.
→ `rm -rf node_modules`는 허용, `rm -rf /data`는 경고.
선택적 안전 예외 목록으로 false positive 최소화.

#### A6. Diff 기반 테스트 선택 (`touchfiles.ts`)
변경 파일 목록 기반으로 관련 E2E 테스트만 선택 실행.
→ 전체 $3.85짜리 테스트를 "관련된 것만" 실행해 비용 절감.

### 우수 패턴

#### B1. 원자적 파일 쓰기
상태 파일, 부분 결과 파일 모두 `tmp 파일 쓰기 → rename` 방식.
→ 프로세스 종료 시 파일 손상 없음.

#### B2. 에러 메시지 설계 원칙
"AI 에이전트가 에러를 읽고 다음 행동을 결정할 수 있어야 한다."
→ 스택트레이스 제거, 구체적 지시 포함.

#### B3. 플랫폼 무관 설계
스킬이 프레임워크별 명령어 하드코딩 금지. CLAUDE.md에서 읽거나 AskUserQuestion으로 질의.
→ React/Vue/Rails/FastAPI 어디서나 동작.

#### B4. Session Isolation (Conductor 연동)
랜덤 포트 (10000-60000) 사용으로 10개 워크스페이스가 각자 브라우저 데몬 실행 가능.
→ Conductor 병렬 세션과 자연스럽게 통합.

#### B5. Non-fatal observability
텔레메트리, 세션 추적, 로그 플러시 모두 `try/catch`로 래핑.
→ 관측 실패가 테스트/작업 실패로 이어지지 않음.

### 기술 스택 분석

| 기술 | 선택 이유 |
|---|---|
| **Bun** | 컴파일 바이너리 (`bun build --compile`) → 배포 단순화. 네이티브 SQLite (쿠키 DB). 네이티브 TypeScript 실행. |
| **Playwright** | @ref 시스템의 핵심인 Accessibility 트리 API. Chromium CDP 직접 제어. |
| **Supabase** | 오픈소스 Firebase 대안. Row Level Security로 insert-only anon 키 구현. |
| **순수 HTTP** | WebSocket/MCP 대비 디버깅 용이, 토큰 오버헤드 없음, curl로 직접 테스트 가능. |
| **Markdown SKILL.md** | 플랫폼 독립적 (Claude/Codex/Gemini CLI 모두 동일 파일 사용). git으로 버전 관리. |

### 확장성/재사용성

**모듈화 수준**: 매우 높음
- 각 스킬은 독립 디렉토리 → 개별 설치/비활성화 가능
- Preamble은 공유 컴포넌트 → 전체 일관성 유지
- commands.ts는 순수 export (side effect 없음) → 빌드/런타임/테스트에서 모두 import

**플러그인 구조**: 새 스킬 추가 = 새 디렉토리 + SKILL.md.tmpl 작성 + setup 재실행
**멀티 에이전트 지원**: `.agents/skills/` 경로로 Codex/Gemini CLI도 동일 스킬 사용

---

## Phase 4: 우리 시스템 적용 방안

### 즉시 도입 가능 (코드 차용 또는 패턴 적용)

#### I-1. PreToolUse 훅 + careful 패턴 → 아누 오케스트레이터 안전장치
**현황**: dispatch.py가 팀에 작업 위임 시 파괴적 명령어 보호 없음
**도입**: `careful/bin/check-careful.sh` 패턴을 CLAUDE.md hooks 섹션에 추가
```yaml
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "bash /home/jay/workspace/teams/shared/check-dangerous.sh"
```
→ `rm -rf`, `DROP TABLE`, `git push --force` 자동 경고
**예상 효과**: 팀원 실수로 인한 프로덕션 데이터 손실 예방

#### I-2. Preamble 공유 블록 → 우리 스킬 통합
**현황**: 우리 47개 스킬이 각자 독립 프롬프트
**도입**: 공통 상태 읽기 블록을 `SKILL.md.tmpl` 형태로 표준화
→ task_id, team_id, WORKSPACE_ROOT를 매번 주입하는 현재 방식 개선 가능

#### I-3. @ref 시스템 → MediScan/InsuWiki 웹 테스트
**현황**: 웹 앱 테스트를 CSS 셀렉터로 직접 지정 (불안정)
**도입**: gstack browse 바이너리 설치 후 `$B snapshot -i` → `$B click @e3` 패턴 사용
**특히**: ThreadAuto의 Threads 페이지 자동화에 즉시 활용 가능

#### I-4. 원자적 파일 쓰기 패턴
**현황**: `qc_verify.py`의 .done 파일 생성이 직접 쓰기
**도입**: `tmp 파일 → rename` 패턴 적용 → 프로세스 중단 시 부분 파일 방지

### 적응 필요 (변형 후 도입)

#### A-1. SKILL.md 템플릿 시스템 → 스킬 자동 생성기
**현황**: 우리 스킬은 `/home/jay/workspace/skills/`에 수동 관리
**도입 방향**: `gen-skill-docs.ts` 방식을 Python으로 구현
- 공통 preamble 블록: `{WORKSPACE_ROOT}`, `{team_id}`, `{task_id}` 자동 주입
- 스킬별 플레이스홀더로 반복 코드 제거
- `bun run gen:skill-docs` 해당 → `python3 gen-skills.py` 스크립트

#### A-2. 3계층 테스트 전략 → 우리 QC 체계
**현황**: qc_verify.py (7개 verifier), task-timer
**도입 방향**:
- Tier 1: 정적 검증 (현재 scope_check, pyright_check) → 무료, 항상 실행
- Tier 2: 실제 E2E (`claude -p` 스타일 → Task tool 기반 통합 테스트) → 유료, 릴리즈 전만
- Tier 3: LLM-as-judge → 스킬 문서 품질 평가 (skill-creator 스킬 강화)
**적응**: gstack은 `claude -p` subprocess, 우리는 Task tool subagent

#### A-3. REPO_MODE 자동 감지 → 팀별 자율화 수준 조정
**현황**: 모든 팀에 동일한 워크플로우 적용
**도입 방향**: `gstack-repo-mode` 스크립트의 "solo/collaborative" 분류를 우리 팀에 맞게 변형
- **프로젝트 초기** (InsuWiki MVP): solo 모드 → 즉시 수정, 질문 최소화
- **팀 협업 단계**: collaborative 모드 → 팀장 확인 후 수정

#### A-4. Diff 기반 테스트 선택 → 팀 작업 효율화
**현황**: qc_verify.py가 지정된 파일만 검사
**도입 방향**: `touchfiles.ts` 패턴을 Python으로 구현
- 각 Task tool 실행이 어떤 파일을 변경했는지 기록
- 관련 테스트 파일만 자동 선택 실행
- CI/CD 비용 절감 + 속도 향상

#### A-5. 자동 Changelog 관리 → 우리 릴리즈 프로세스
**현황**: 릴리즈 노트 수동 작성
**도입**: gstack의 `/document-release`, `/retro` 스킬 철학 적용
- 배포 완료 시 자동으로 CHANGELOG 업데이트
- 주간 /retro에서 팀별 커밋 분석

### 참고만 (설계 철학 수준)

#### R-1. Boil the Lake 원칙
**핵심**: AI 시대에 "완성도 비용"이 0에 수렴 → 90% 구현보다 100% 구현 항상 선택
**우리 적용**: DIRECT-WORKFLOW.md의 "합리화 방지" 규칙과 동일 철학
→ 이미 내재화됨. 팀원 교육 시 "Boil the Lake" 언어 사용 고려.

#### R-2. "Search Before Building" 3계층 지식
**Layer 1**: 검증된 패턴 (항상 확인)
**Layer 2**: 최신 인기 패턴 (비판적 수용)
**Layer 3**: 퍼스트 프린시플 (가장 가치 있음)
→ 우리 ETHOS.md나 팀 가이드라인에 추가 가치 있음

#### R-3. 텔레메트리 + 커뮤니티 피드백 루프
gstack은 Supabase로 익명 사용 데이터 수집 → 스킬 공동 사용 패턴 분석
우리에게 직접 도입은 과도하나, task-timer 데이터를 활용한 팀 성과 분석 방향 참고.

#### R-4. "Handoff/Resume" 패턴
브라우저 세션을 사용자에게 넘겼다가 다시 받아오는 handoff/resume 명령.
→ AI-인간 협업의 우아한 모델. 복잡한 인증/CAPTCHA에 유용.

### 마케팅팀 역량강화 (아프로디테팀)

#### M-1. /browse 스킬 → ThreadAuto 자동화 즉시 강화
- Threads 게시물 자동 업로드 시 gstack browse 사용
- `$B goto`, `$B fill`, `$B click`, `$B screenshot` → 시각적 검증 가능
- 현재 Playwright 직접 사용 대비: ref 시스템으로 DOM 변경 내성 향상

#### M-2. /qa + /browse → 마케팅 랜딩 페이지 품질 검증
- InsuWiki, ThreadAuto 배포 후 자동 QA 실행 가능
- `$B responsive` → 모바일/태블릿/데스크톱 스크린샷 동시 생성
- 마케팅팀이 개발팀 없이도 배포 품질 확인

#### M-3. /office-hours → 마케팅 아이디어 검증
- "이 캠페인 아이디어, 해볼 만한가?" 진단
- 6가지 강제 질문으로 수요 현실성 점검

### 새 스킬 생성 필요 여부

#### S-1. [높은 가치] `gstack-browse` 스킬 우리 시스템에 통합
- gstack browse 바이너리를 `/home/jay/workspace/` 환경에 설치
- 기존 `webapp-testing` 스킬을 gstack browse 기반으로 강화
- **권장**: 즉시 추진. ThreadAuto, MktingAuto, InsuWiki 테스트 품질 대폭 향상.

#### S-2. [중간 가치] `template-skill-generator` 스킬 신규 제작
- gstack gen-skill-docs.ts 방식을 Python으로 구현
- 우리 스킬의 공통 preamble(task_id, workspace_root 주입) 자동화
- **권장**: skill-creator 스킬로 먼저 평가 후 결정.

#### S-3. [중간 가치] `careful-guardrail` 훅 시스템 도입
- `check-careful.sh` 패턴을 `teams/shared/check-dangerous.sh`로 이식
- 모든 팀 CLAUDE.md에 PreToolUse 훅 추가
- **권장**: 아누(오케스트레이터) 주도로 팀 전체 적용.

---

## 셀프 QC 체크리스트

- [x] 1. 다른 파일에 영향 없음 — 순수 분석 보고서 (산출물만 생성)
- [x] 2. 엣지 케이스 — 클론 실패 처리됨 (이미 존재하는 경우 확인 완료)
- [x] 3. 작업 지시와 일치 — Phase 1~4 전체 분석, 파일별 역할 정리, 코드 스니펫 인용, 우리 시스템 적용 방안 포함
- [x] 4. 에러 처리/보안 — 해당 없음 (분석 보고서)
- [x] 5. 테스트 커버리지 — 해당 없음 (분석 보고서)
- [x] 6. 발견 이슈 — 없음 (분석 작업)

## 발견 이슈 및 해결

### 자체 해결 (0건)
없음.

### 범위 외 미해결 (0건)
없음.

---

## 요약: 핵심 도입 우선순위

| 순위 | 항목 | 예상 임팩트 | 난이도 |
|---|---|---|---|
| 1 | gstack browse 바이너리 도입 (I-3) | ThreadAuto/MktingAuto 자동화 품질 대폭 향상 | 낮음 (30분) |
| 2 | careful 훅 패턴 도입 (I-1) | 팀원 파괴적 명령어 실수 예방 | 낮음 (1시간) |
| 3 | 원자적 파일 쓰기 패턴 (I-4) | .done 파일 안정성 향상 | 낮음 (30분) |
| 4 | 3계층 테스트 전략 적응 (A-2) | QC 체계 강화 | 중간 (1일) |
| 5 | 스킬 템플릿 생성기 (A-1/S-2) | 스킬 유지보수 비용 절감 | 중간 (2일) |