gstack 실전 가이드 — Claude Code를 가상 엔지니어링 팀으로 만드는 법

Evan Kang·2026년 4월 9일

Claude Code를 쓰면서 "리뷰해줄 시니어가 없다"고 느낀 적 있다면, 이 글이 도움이 될 겁니다.

gstack이 뭔가

gstack은 Y Combinator 대표 Garry Tan이 공개한 Claude Code 슬래시 커맨드 팩입니다. GitHub 스타 54K를 넘긴 오픈소스 프로젝트로, Claude Code를 가상 엔지니어링 팀으로 바꿔줍니다.

핵심 철학은 단순합니다. "만능 AI 하나에게 다 시키기"를 그만두고, CEO, 엔지니어링 매니저, QA 리드, 릴리즈 매니저 역할을 분리하자는 겁니다.

왜 역할 분리가 중요할까요? 같은 AI에게 설계-구현-리뷰-배포를 한 세션에서 시키면, 각 단계에 필요한 인지 모드가 다르기 때문에 품질이 떨어집니다. CEO는 "왜 이걸 만들어야 하는가"를 생각하고, QA 엔지니어는 "이게 실제로 작동하는가"를 생각합니다. 같은 사람이 동시에 두 모드로 작업하면 둘 다 어중간해지는 것과 같습니다.

gstack은 이 문제를 슬래시 커맨드로 해결합니다. /plan-ceo-review를 치면 Claude가 CEO 모드로 전환되고, /qa를 치면 QA 리드 모드로 전환됩니다. 각 모드마다 고유한 우선순위, 체크리스트, 제약조건이 적용됩니다.

설치와 초기 세팅

요구사항

Bun v1.0 이상
Node.js
Git
Claude Code

확인 방법:

echo "=== Bun ===" && (bun --version 2>/dev/null || echo "NOT INSTALLED")
echo "=== Node.js ===" && (node --version 2>/dev/null || echo "NOT INSTALLED")
echo "=== Git ===" && (git --version 2>/dev/null || echo "NOT INSTALLED")
echo "=== Claude Code ===" && (claude --version 2>/dev/null || echo "NOT INSTALLED")

Bun이 없다면:

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

전역 설치 vs 프로젝트별 설치

gstack은 두 가지 설치 방식을 지원합니다.

전역 설치 — ~/.claude/skills/gstack에 설치되어 모든 Claude Code 세션에서 사용 가능합니다. 개인 역량 강화 목적이라면 이쪽입니다.

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

프로젝트별 설치 — 프로젝트의 .claude/skills/에 복사해서 git에 커밋합니다. 팀원이 git clone만 하면 바로 gstack을 사용할 수 있습니다.

cp -Rf ~/.claude/skills/gstack .claude/skills/gstack && rm -rf .claude/skills/gstack/.git && cd .claude/skills/gstack && ./setup

혼자 쓸 거라면 전역 설치로 시작하고, 팀에 공유할 때 프로젝트별로 옮기면 됩니다.

셋업 질문과 추천 선택

설치 중에 몇 가지 질문이 나옵니다. 각각의 의미와 추천 선택을 정리합니다.

Skill naming — Short names vs Namespaced

/qa로 쓸지 /gstack-qa로 쓸지 선택합니다. 다른 스킬팩을 병행하지 않는다면 Short names가 타이핑이 빠릅니다. 충돌이 생기면 나중에 gstack-config로 변경 가능합니다.

💡 주의: 이 단계에서 Cmd+C를 누르면 복사가 아니라 터미널 인터럽트 신호가 발생합니다. 타임아웃이 걸려있어서 기본값(Short names)으로 진행됩니다. 당황하지 마세요 — 대부분의 경우 기본값이 적절합니다.

Telemetry — Community mode vs Off

사용 통계(어떤 스킬을 얼마나 썼는지)를 gstack 개발팀에 보낼지 선택합니다. 코드나 파일 경로는 보내지 않는다고 명시하고 있지만, 굳이 켤 필요는 없습니다. Off를 선택하면 이어서 "최소한 카운터만이라도?"라고 다시 물어보는데, 이것도 편한 대로 선택하면 됩니다.

Proactive — On vs Off

작업 중에 gstack이 문맥을 읽고 적절한 커맨드를 제안해주는 기능입니다. "이거 되나?" 같은 말을 하면 /qa를 제안하고, 버그를 만나면 /investigate를 제안합니다. On을 추천합니다. 아직 각 커맨드의 적절한 타이밍을 모를 때, 자동 제안이 학습을 도와줍니다.

Cross-project learnings — Enable vs Project-scoped

gstack이 프로젝트별로 학습한 내용을 다른 프로젝트에서도 참조할지 선택합니다. 솔로 개발자라면 Enable이 유리합니다. A 프로젝트에서 배운 패턴이 B 프로젝트 작업할 때 자동으로 참조됩니다. 여러 클라이언트 코드를 다루는 에이전시/프리랜서라면 Project-scoped로 격리하세요.

Routing rules — CLAUDE.md에 추가 여부

프로젝트의 CLAUDE.md에 라우팅 규칙을 추가하면, Claude가 대화 맥락에 따라 적절한 스킬을 자동 호출합니다. Proactive 모드와 함께 쓸 때 효과적입니다. 본인 프로젝트라면 추가하세요.

핵심 커맨드 3개와 언제 쓰는가

gstack은 20개 이상의 커맨드를 제공하지만, 처음에는 3개만 알면 충분합니다.

/retro — "지금 내 프로젝트 상태가 어떤가?"

git 히스토리를 분석해서 엔지니어링 회고를 생성합니다.

분석 항목:

커밋 수, LOC, 테스트 비율, PR 수 등 정량 지표
시간대별 작업 패턴 (언제 가장 많이 코딩하는지)
출하 속도와 유형 분포 (feat, fix, refactor 비율)
코드 핫스팟 (가장 많이 변경된 파일)
출하 일관성과 streak

언제 쓰나: 프로젝트를 처음 인수받았을 때, 스프린트 종료 시점, 또는 "요즘 내가 얼마나 생산적인가?" 궁금할 때.

/plan-eng-review — "내 코드에 구조적 문제가 있나?"

코드베이스 전체를 엔지니어링 매니저 관점으로 스캔합니다.

제시하는 것:

보안: 키 노출, 인증 부재, 인젝션 가능성
성능: 불필요한 순차 처리, 과도한 데이터 조회, 캐시 미설정
버그: 실제 동작하지 않는 코드, 크래시 가능성
코드 품질: DRY 위반, 패턴 불일치, 에러 처리 미흡

각 이슈마다 P1/P2/P3 우선순위, 구체적 파일:라인번호, 수정 방법, 예상 소요시간, 완성도 점수까지 포함됩니다. 그리고 이슈별로 "수정하겠다 / 보류하겠다"를 선택할 수 있고, 보류한 것은 TODOS.md로 자동 생성됩니다.

언제 쓰나: 배포 전 검수, 새 팀원이 코드베이스를 파악할 때, "기술 부채가 어디에 있지?" 확인할 때.

/review — "이 PR을 머지해도 되나?"

현재 브랜치와 main의 diff를 기반으로 코드 리뷰를 수행합니다. 스태프 엔지니어 관점에서 프로덕션 버그, 보안 취약점, 성능 이슈를 잡습니다.

언제 쓰나: PR 머지 전. 솔로 개발자라면 git checkout -b feat/thing → 작업 → /review → /ship 흐름을 습관화하면 코드 품질이 올라갑니다.

/plan-eng-review가 실제로 잡아주는 것들

실제 프로젝트에서 /plan-eng-review를 돌렸을 때 발견된 이슈들을 카테고리별로 정리합니다. 여러분의 프로젝트에서도 비슷한 패턴이 나올 수 있습니다.

보안

클라이언트 사이드 DB 직접 쿼리. NEXT_PUBLIC_ 키를 사용해 브라우저에서 Supabase에 직접 쿼리를 보내는 코드. RLS(Row Level Security)가 없으면 누구든 브라우저 개발자 도구로 테이블을 조회할 수 있습니다. → API route를 경유하도록 변경.

인증 없는 API 엔드포인트. 외부 API를 호출하는(=돈이 나가는) 라우트에 인증이 없으면, URL만 알면 누구나 호출 가능합니다. → API 키 헤더 체크 추가.

모듈 레벨 서비스 키 초기화. 같은 프로젝트 안에서 한 파일은 lazy-init 패턴을 쓰고, 다른 파일은 모듈 최상단에서 초기화하는 불일치. → 기존 좋은 패턴으로 통일.

성능

순차 쿼리를 Promise.all로 병렬화. 서로 의존성 없는 DB 쿼리 3~4개를 await로 순차 실행하고 있는 경우. Promise.all로 감싸면 같은 데이터를 가져오는 시간이 3배 이상 줄어듭니다. 2분짜리 수정.

SSR 캐시 미설정. Next.js App Router는 기본적으로 빌드 시점에 페이지를 캐시합니다. 라이브 데이터를 보여주는 페이지에 export const revalidate = 300을 추가하면 5분마다 갱신됩니다. 한 줄 수정.

버그

읽기만 있고 쓰기가 없는 코드. sessionStorage에서 데이터를 읽는 코드는 있는데, 어디에서도 쓰지 않는 경우. 생성 후 페이지 이동했다가 돌아오면 데이터가 사라집니다. → 생성 성공 시 sessionStorage.setItem 추가.

중복 데이터 삽입. 캐시된 결과가 있는데도 매번 INSERT를 실행하는 코드. 같은 버튼을 두 번 클릭하면 중복 행이 생깁니다. 같은 프로젝트의 다른 핸들러에 이미 존재하는 체크 패턴을 그대로 적용.

URL 파싱 크래시. new URL(source).hostname을 SSR 렌더링 내 .map()에서 호출하는 코드. 소스 URL이 유효하지 않으면 전체 페이지가 500 에러로 죽습니다. → try/catch 3줄 추가.

코드 품질

에러 응답에 스택 트레이스 노출. catch 블록에서 에러 객체를 그대로 클라이언트에 반환하면, 내부 구현 상세가 외부에 노출됩니다. → console.error로 서버 로그는 유지하고, 클라이언트에는 일반 에러 메시지만 반환.

인상 깊었던 개념 — LLM 신뢰 경계(Trust Boundary)

gstack이 단순히 "이 코드가 이상하다"를 넘어서 구조적 설계 개념을 짚어준 사례가 있었습니다.

AI(LLM)가 생성한 텍스트를 여러 시스템에 전달할 때, 각 목적지마다 다른 위험이 존재합니다.

Slack에 보낼 때: @channel, <!everyone> 같은 특수 문법이 포함되면 의도하지 않은 전체 멘션이 발생할 수 있습니다.
DB에 저장할 때: 문자열 그대로 저장하면 대체로 안전하지만, 타입 검증은 필요합니다.
브라우저에 보여줄 때: XSS 방지를 위한 이스케이프, 마크다운 파싱을 위한 렌더러가 필요합니다.

AI 출력은 예측 가능해 보이지만 100% 통제할 수 없습니다. 외부 시스템에 넘기기 전에 "이 출력이 해당 시스템에서 위험한 동작을 유발할 수 있는가?"를 체크하는 경계를 두는 것이 신뢰 경계입니다. AI 앱을 만드는 개발자라면 설계 시점에 고려해야 할 원칙입니다.

실전 운용 팁

커맨드 체인

gstack 커맨드는 독립적으로도 쓸 수 있지만, 체인으로 연결하면 더 강력합니다. 앞 단계의 산출물이 뒷 단계의 입력이 됩니다.

/office-hours (아이디어 정의)
    ↓
/plan-ceo-review (전략 검토)
    ↓
/plan-eng-review (아키텍처 검토)
    ↓
/review (코드 리뷰)
    ↓
/qa (브라우저 테스트)
    ↓
/ship (배포)
    ↓
/retro (회고)

처음부터 풀 체인을 돌릴 필요는 없습니다. 파이프라인 중간 어디에서든 시작할 수 있고, /plan-eng-review는 design doc 없이 기존 코드베이스를 분석하는 것도 가능합니다.

스코프 관리

/plan-eng-review는 한 번에 10개 이상의 이슈를 찾아줄 수 있습니다. 전부 고치려는 충동을 참으세요. 실전에서 효과적인 판단 기준:

지금 고친다: 1~2분짜리 패턴 통일, 실제 동작하는 버그, 크래시 방지
기록하고 넘긴다: 아키텍처 변경, 테스트 인프라 구축, 대규모 리팩토링

보류한 이슈는 gstack이 TODOS.md를 자동 생성해주니, 다음 스프린트에서 꺼내면 됩니다.

한국어 설정

gstack의 출력은 기본적으로 영어입니다. 한국어로 받으려면 CLAUDE.local.md에 한 줄만 추가하세요.

echo "\n## Language\nAlways respond in Korean (한국어)." >> ~/.claude/CLAUDE.local.md

CLAUDE.local.md는 .gitignore에 포함되므로 gstack 원본이나 팀 설정에 영향을 주지 않습니다.

누구에게 추천하나

솔로 개발자 — 시니어 리뷰어 없이 시니어 관점 피드백을 받을 수 있습니다. 보안, 성능, 아키텍처를 혼자서는 놓치기 쉬운데, gstack이 체계적으로 잡아줍니다.

주니어 개발자 — 각 커맨드가 "시니어 엔지니어는 코드의 어디를 보는가"를 보여주는 학습 도구가 됩니다. P1/P2/P3 분류, 완성도 점수, 수정 방법까지 포함되어 있어서 "왜 이게 중요한지"를 같이 배울 수 있습니다.

팀 리드 — 프로젝트 .claude/skills/에 커밋하면 팀 전체가 같은 리뷰 기준을 공유합니다. 코드 리뷰의 일관성이 올라가고, 반복적인 피드백을 자동화할 수 있습니다.