gstack 트러블슈팅 5가지 — 1~2시간 날리기 전에 확인할 것들

gstack 깔고 워크플로우 따라가다 막히는 지점이 5군데에 거의 다 몰립니다.
검색해도 한국 자료가 거의 없어서 영문 GitHub Issues를 뒤지다 1~2시간을 날리는 경우가 흔합니다.
gstack 시리즈 7편을 정리하고 30분 MVP까지 직접 돌려본 환경에서 마주친 gstack 트러블슈팅 사례 5가지를 증상·원인·해결 3단으로 묶었습니다.

이 순서대로 가면 같은 에러가 떴을 때 30분 안에 풀고 작업으로 돌아갈 수 있습니다.

어떤 에러가 가장 자주 뜨나 — gstack 트러블슈팅 5가지 한눈에

#	증상 키워드	핵심 원인	평균 해결 시간
1	/ship 도중 멈춤·파일 일부만 생성	Pro 플랜 토큰 한계	5분
2	/plan-eng-review가 Drizzle·Redis 권유	제약 미명시	1분
3	wsl --install 시 0x80370102	BIOS 가상화 OFF	10분 (재부팅 포함)
4	/qa 헤드리스 브라우저 실행 실패	Chromium 미설치	3분
5	gstack 응답 점점 느려짐·맥락 깨짐	CLAUDE.md 컨텍스트 비대	2분

트러블 1 — /ship이 토큰 한계로 중간에 멈출 때

증상: /ship 명령 실행 도중 일부 파일만 생성되고 작업이 종료됨. 에러 메시지는 안 뜨고 "Done" 같은 신호도 없이 그냥 끊김.
원인: Claude Pro($20/월)는 5시간 윈도우 안 토큰 한도가 작아서, /ship처럼 한 번에 1만 줄 가까이 쓰는 명령이 한도에 걸려 잘림. Max($100)는 5배 한도라 거의 안 걸림.
해결:

1. 즉시 푸는 법 — 같은 /ship 프롬프트에 "백엔드만 먼저"라고 명시해 작업 쪼갬. 그다음 새 /ship으로 "프론트만"
2. 근본 해결 — Max 플랜 업그레이드 (월 $80 차이로 5배 토큰)

저는 메인 워크플로우는 Max로 돌리고, Pro 환경 테스트할 때만 작업을 쪼개서 씁니다.

트러블 2 — /plan-eng-review가 풀스펙 권유로 30분 MVP를 깨뜨릴 때

증상: 단순 단일 페이지 만들 건데 /plan-eng-review가 "Drizzle ORM·Redis 캐시·인증 미들웨어 추가하라"고 권유. 시키는 대로 가면 30분 MVP가 4시간 작업이 됨.
원인: /plan-eng-review는 프로덕션 시나리오를 기본 가정해서 답함. 제약을 안 적으면 풀스펙으로 답.
해결: 프롬프트 첫 줄에 제약을 명시하기.

제약: 30분 안에 동작하는 MVP. 외부 DB·인증·캐시·테스트 프레임워크 없음.
단일 라우트, 단일 HTML.

이 한 줄만 넣으면 /plan-eng-review도 "그러면 Hono serveStatic 한 줄 + Chart.js CDN으로 충분합니다" 식으로 명확해집니다.

트러블 3 — Windows에서 wsl --install 시 0x80370102 에러

증상: gstack 사전 환경 잡으려고 PowerShell에서 wsl --install -d Ubuntu 실행 시 다음 메시지로 실패.

WslRegisterDistribution failed with error: 0x80370102
Please enable the Virtual Machine Platform Windows feature and ensure
virtualization is enabled in the BIOS.

원인: BIOS에서 가상화(Intel VT-x / AMD-V)가 꺼져 있음. 노트북·새 데스크탑에 기본값 OFF인 경우가 많음.
해결:

1. 재부팅 후 BIOS 진입 (Dell F2, HP F10, MSI Delete, Lenovo F1 등 제조사별 다름)
2. "CPU Configuration" 또는 "Advanced" 메뉴 → Virtualization Technology / VT-x / SVM Mode 항목 → Enable
3. Save & Exit → 재부팅 후 다시 wsl --install

처음 세팅 시 이 단계에서 막혀 1시간을 날린 적 있어, 이젠 새 PC면 BIOS부터 확인하는 순서로 갑니다.

트러블 4 — /qa가 헤드리스 브라우저 실행 실패

증상: /qa 명령 실행 시 다음 비슷한 에러로 종료.

browserType.launch: Executable doesn't exist at
C:\Users\<user>\AppData\Local\ms-playwright\chromium-xxxx\chrome.exe

원인: gstack /qa가 내부에서 Playwright + Chromium을 호출하는데, 첫 사용 시 Chromium 바이너리가 미설치 상태.
해결: 한 줄 실행.

npx playwright install chromium

회사 보안 정책으로 Playwright 다운로드 차단이라면, Chrome·Edge가 깔린 시스템 브라우저를 쓰도록 --system-browser 옵션을 /qa 다음에 명시.

트러블 5 — gstack이 점점 느려지고 답변이 엉뚱해질 때

증상: 같은 세션에서 몇 시간 작업하다 보면 응답 속도가 눈에 띄게 느려지고, 이전 결정과 다른 답이 나옴. "방금 정한 컬러 팔레트는?" 같은 질문에 새로 답.
원인: 세션 누적으로 컨텍스트가 200K 토큰 가까이 채워짐. CLAUDE.md가 두꺼우면 더 빨리 도달. Claude는 컨텍스트 70% 이상 차면 정밀도가 떨어짐.
해결:

1. 즉시 — /clear로 세션 초기화 후 새 세션 시작. 핵심 결정 사항만 /memory 또는 CLAUDE.md에 적어두고 재시작.
2. 작업 중 압축 — /compact API 변경사항만 유지 식으로 선택 압축
3. 환경 변수 — CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=50 넣어 자동 압축을 50%에서 발동

가장 효과 좋은 건 30~45분 집중 세션 + 끝나면 /clear 루틴입니다. 긴 세션 한 번보다 짧고 정밀한 세션 여러 번이 결과가 좋습니다.

gstack 트러블슈팅 시작 전 5분 점검 체크리스트

새 PC에서 gstack 처음 돌리거나 오랜만에 켤 때 5분 점검:

점검	명령	정상 응답
WSL2 작동	wsl --status	Default Version: 2
Bun 버전	bun --version	1.3.x 이상
Playwright Chromium	npx playwright --version	버전 출력
Claude 플랜	Claude 앱 → 설정 → Billing	Pro 또는 Max
CLAUDE.md 크기	wc -l CLAUDE.md	100줄 이하 권장

Q&A — 자주 보는 질문 5개

Q. Pro 플랜으로 gstack 못 쓰나요?
A. 씁니다. 다만 /ship 큰 작업은 트러블 1처럼 잘려요. 작업을 쪼개거나 30분 안에 끝나는 작은 MVP만 시도하세요. 한 달에 5~6번 이상 막히면 Max 업그레이드 ROI가 나옵니다.

Q. WSL2 대신 Windows 네이티브로 gstack 못 돌리나요?
A. Bun 1.3 이후로는 네이티브 지원이 안정화돼 일부 작업은 가능합니다. 다만 gstack의 /ship이 내부에서 호출하는 npm 패키지 일부가 Linux 의존성이 있어 WSL2가 안전합니다.

Q. 트러블 5(컨텍스트 비대) 자동으로 막을 방법은?
A. .env에 CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=50 적어두면 자동 압축이 일찍 발동. CLAUDE.md를 100줄 이하로 슬림하게 유지하는 게 더 효과적입니다.

Q. 5가지 외에 자주 막히는 게 있나요?
A. /browse가 한국 사이트 일부에서 SSL 인증서 오류로 안 뜨는 케이스가 가끔 있습니다. 빈도가 낮아 이 글에선 뺐고, 발생 시 --ignore-ssl-errors 옵션 추가로 회피.

Q. gstack 트러블슈팅 매뉴얼을 자기 환경에 맞게 정리하려면?
A. gstack 워크플로우 7편 시리즈를 보고 자기 작업 패턴에 자주 막히는 지점을 따로 모아두세요. 시리즈 첫 글 "gstack 설치 가이드 (Windows)"부터 순서대로 보면 흐름이 잡힙니다.

마무리

#	트러블	한 줄 해결
1	/ship 멈춤	작업 쪼개기 또는 Max 업그레이드
2	풀스펙 권유	첫 줄에 "MVP·30분·단일 라우트" 명시하기
3	WSL2 0x80370102	BIOS Virtualization Technology Enable
4	/qa Chromium 미설치	npx playwright install chromium
5	컨텍스트 비대	/clear + 짧은 세션 루틴

5가지 다 한 번씩만 겪으면 그다음부터는 1분 안에 진단되니까, 첫 만남에서 시간 날리지 않게 위 매트릭스를 책갈피로 두면 좋습니다. 같은 환경이면 위 순서대로 따라가도 무리 없습니다.

---

📎 이 카테고리의 다른 글

• gstack 실전 사례 — 30분 안에 MVP 만들기 (Pomodoro 타이머 + 통계 위젯) — 2026-05-11
• gstack 설치 가이드 (Windows) — 2026-03-24
• gstack 실전 워크플로우 — 2026-03-31

같은 gstack 시리즈에서 이어서 읽기

검증 환경: Windows 11 (24H2), WSL2 + Ubuntu 24.04, Bun 1.3.11, Node v24, Claude Max + gstack v0.x, Playwright 1.x