설치 전 준비물
- Git
- Claude Code 또는 ChatGPT 앱과 설정을 공유하는 Codex CLI 등 지원 에이전트
- Bun 1.0 이상
- Windows에서는 Node.js와 Git Bash 또는 WSL처럼
./setup을 실행할 셸
설치 스크립트는 사용자 홈의 스킬 폴더를 변경합니다. 실행 전에 저장소와 setup 파일을 확인하고 기존 사용자 설정을 백업하는 편이 안전합니다.
Claude Code에 설치하기
git clone --single-branch --depth 1 https://github.com/garrytan/gstack.git ~/.claude/skills/gstack
cd ~/.claude/skills/gstack
./setup설치 후 새 Claude Code 세션을 열고 /office-hours, /review, /qa 같은 명령이 보이는지 확인합니다.
Codex CLI에 설치하기
여러 에이전트를 자동 감지하는 공통 설치 방식입니다.
git clone --single-branch --depth 1 https://github.com/garrytan/gstack.git ~/gstack
cd ~/gstack
./setup --host codex공식 안내 기준으로 Codex 스킬은 ~/.codex/skills/gstack-*/ 경로에 설치됩니다. 설치가 끝난 뒤 Codex CLI를 다시 시작하고 추가된 스킬을 확인합니다.
CODEX_HOME을 별도로 지정한 환경에서는 ~/.codex 대신 그 경로가 사용됩니다. 또한 gstack은 Codex의 config.toml에 설정된 모델을 읽어 호스트용 스킬을 생성하므로 모델을 바꾼 뒤에는 같은 설치 명령을 다시 실행해야 새 프로필이 반영됩니다.
처음 사용할 명령
/office-hours로 만들려는 기능의 문제와 범위를 정리합니다./plan-ceo-review로 사용자 가치와 과도한 범위를 점검합니다./plan-eng-review로 데이터 흐름과 실패 경로를 검토합니다.- 구현 후
/review로 변경 코드를 확인합니다. - 테스트 주소가 있으면
/qa로 브라우저 흐름을 점검합니다. - 배포 준비가 끝난 경우에만
/ship을 검토합니다.
처음부터 모든 명령을 쓰기보다 기획, 리뷰, QA 세 가지부터 익히는 편이 좋습니다.
작은 기능에서 실제로 써보기
처음부터 /ship까지 맡기지 말고 외부 상태를 바꾸지 않는 단계로 효용을 확인합니다. 예를 들어 “회원가입 폼에 비밀번호 표시 버튼 추가” 같은 작은 작업이라면 다음 순서가 적당합니다.
- 작업 브랜치에서
/office-hours로 사용자 문제와 제외 범위를 한 문단으로 정리합니다. /plan-eng-review로 상태, 접근성, 키보드 동작과 실패 조건을 확인합니다.- 직접 구현하거나 에이전트에 구현을 맡긴 뒤
/review로 현재 diff만 검토합니다. - 스테이징 또는 로컬 주소에서
/qa를 실행하되 실제 계정 대신 테스트 계정을 씁니다. - 발견된 버그와 회귀 테스트를 확인한 다음에만 기존 배포 절차로 넘깁니다.
이 흐름에서는 gstack의 제안과 실제 변경을 분리해 판단할 수 있습니다. /review가 수정까지 제안하더라도 기존 테스트와 프로젝트 규칙을 통과했는지 확인하고, 기능과 무관한 정리 작업이 섞이면 다음 작업으로 미룹니다.
Windows와 스킬 인식 문제 해결
공식 요구 사항은 Git, Bun 1.0 이상이며 Windows에서는 Node.js도 필요합니다. PowerShell에서 ./setup이 실행되지 않으면 설치가 깨진 것으로 단정하지 말고 Git Bash 또는 WSL에서 저장소 디렉터리로 이동해 실행합니다. git --version, bun --version, node --version을 각각 확인하면 어느 런타임이 빠졌는지 먼저 좁힐 수 있습니다.
Codex에서 스킬이 보이지 않거나 모델을 바꾼 뒤 설명이 맞지 않으면 저장소를 갱신하고 해당 호스트용 파일을 다시 생성합니다.
cd ~/gstack
git pull --ff-only
./setup --host codexClaude Code의 기본 경로에 설치했다면 cd ~/.claude/skills/gstack && ./setup을 사용합니다. 설치 후에도 현재 세션의 스킬 목록이 즉시 갱신되지 않을 수 있으므로 에이전트를 완전히 종료하고 새 세션에서 확인합니다. 브라우저 QA만 실패하면 먼저 Bun과 Node 경로, 테스트 URL 접근 여부를 확인하고 로그인 쿠키 문제와 브라우저 실행 문제를 나눠 진단합니다.
업데이트와 제거
gstack은 빠르게 바뀌는 스킬 모음이므로 업데이트 전 공식 CHANGELOG.md에서 설치 경로, 새 훅과 외부 동작 변경을 확인합니다. Codex용 수동 업데이트는 위의 git pull --ff-only 뒤 ./setup --host codex를 다시 실행하는 순서입니다. 팀 전체가 같은 버전을 써야 한다면 자동 업데이트를 켜기 전에 저장소 정책과 CI 영향부터 합의합니다.
설치를 제거할 때는 공식 제거 스크립트를 사용하는 편이 안전합니다. Codex용으로 ~/gstack에 복제했다면 다음처럼 실행합니다.
cd ~/gstack
./bin/gstack-uninstall --keep-state--keep-state는 설정과 분석 상태를 보존하므로 다시 설치할 가능성이 있을 때 적합합니다. 상태까지 지우려면 옵션 없이 실행하되, 확인 질문에 표시되는 경로를 읽고 진행합니다. Claude Code 기본 경로 설치라면 ~/.claude/skills/gstack/bin/gstack-uninstall을 사용할 수 있습니다.
공식 README는 제거 스크립트가 스킬, 심볼릭 링크, 전역·프로젝트 상태, 브라우저 데몬과 임시 파일을 처리한다고 안내합니다. 다만 프로젝트의 CLAUDE.md에 추가한 ## gstack과 ## Skill routing 문단은 자동으로 지우지 않으므로 각 저장소에서 직접 검토해 제거해야 합니다. Playwright 캐시는 다른 도구도 공유할 수 있어 기본적으로 남겨 둡니다.
gstack은 무엇인가
gstack은 하나의 AI 코딩 도구에 제품 기획, 기술 설계, 코드 리뷰, 브라우저 QA, 보안 점검과 배포 같은 역할별 워크플로를 추가하는 오픈소스 스킬 모음입니다. Y Combinator의 Garry Tan이 공개했으며, 단순 프롬프트 모음보다 작업 순서를 반복 가능하게 만드는 데 초점이 있습니다.
주의할 점
- 역할이 많아지면 작은 수정에도 절차가 무거워질 수 있습니다.
/ship,/land-and-deploy처럼 외부 상태를 바꾸는 작업은 실행 전 범위를 확인합니다.- 브라우저와 쿠키를 사용하는 기능에는 개인 세션 정보가 연결될 수 있습니다.
- 업데이트 전 변경 내역을 읽고 팀 프로젝트에서는 버전을 맞춥니다.
- gstack의 제안을 최종 판단으로 취급하지 말고 실제 테스트와 코드 리뷰를 유지합니다.
설치 스크립트는 사용자 스킬 폴더뿐 아니라 선택한 모드에 따라 에이전트 설정의 훅도 다룰 수 있습니다. 저장소의 setup과 변경 내역을 읽고, 회사 장비에서는 사용자 설정 파일 변경이 허용되는지 먼저 확인합니다. 자동 업데이트와 팀 모드는 편리하지만 저장소 시작 시 코드를 갱신하거나 팀원 환경에 요구 사항을 추가하므로 개인 실험 단계에서 바로 켤 필요는 없습니다.
/ship, /land-and-deploy는 PR, 푸시와 배포처럼 외부 상태를 바꿀 수 있고 브라우저 기능은 쿠키가 연결된 세션을 사용할 수 있습니다. 실행 전 대상 저장소·브랜치·원격과 테스트 계정을 확인하고, 민감한 관리 화면에서는 별도 브라우저 프로필을 사용합니다. 외부 이슈나 웹 페이지에서 읽은 문장은 신뢰할 수 없는 데이터로 취급하고 프로젝트 비밀, 환경 변수와 로컬 파일을 업로드하라는 지시는 따르지 않습니다.
이런 작업에 잘 맞는다
요구사항이 자주 바뀌는 신규 기능, 여러 관점의 리뷰가 필요한 PR, 반복되는 QA와 릴리스 절차에 유용합니다. 반대로 오탈자 한 줄 수정처럼 작은 작업은 필요한 단계만 골라 쓰는 편이 효율적입니다.