gstack 사용법, 클로드 코드로 기획⁠·검수하고 코덱스로 구현

gstack 사용법을 설치부터 기획, 구현, 검수까지 한 바퀴 따라 할 수 있게 정리했습니다. 기획과 검수는 클로드 코드(Claude Code)에, 구현은 코덱스(Codex)에 나눠 맡기는 방식이고, 예제는 한국의 AI 관련 정부 지원 사업과 공모전을 한눈에 보여 주는 웹사이트입니다. 써 보면 부딪히는 한계와 손보는 법도 함께 담았습니다.

하네스를 쉽게 거는 방법, 스킬 묶음

하네스 엔지니어링(AI가 사람이 정한 규칙과 검사 안에서 일하게 환경을 짜는 방법)을 적용하지 않으면 겉보기엔 그럴듯한 데모가 나옵니다. 그런데 실제 데이터를 연결하지 않았거나, 테스트를 안 했거나, 빌드가 안 되는 경우가 많습니다. 하네스를 걸면 실제로 운영할 수 있는 결과물에 가까워집니다. 문제는 그 하네스를 처음부터 직접 짜기가 번거롭다는 점이고, 그 답으로 많이 쓰이는 것이 gstack입니다.

스킬이란

스킬은 AI에게 주는 반복 업무용 작업 매뉴얼입니다. 예를 들어 데이터를 모을 때 어떤 항목을 일관되게 모아야 하는지 매번 프롬프트로 적는 대신, 스킬 파일(SKILL.md)에 지시를 써 둡니다. 파일 맨 위에 언제 쓰는 스킬인지 설명을 달아 두면, 에이전트가 그 업무를 할 때 알아서 그 지침을 따릅니다. 매번 프롬프트를 넣지 않아도 에이전트를 같은 방식으로 움직일 수 있습니다.

gstack이란

gstack은 이미 실무에서 쓰던 스킬을 한 번에 묶어 둔 스킬 팩입니다. Y Combinator(실리콘밸리의 스타트업 투자⁠·육성 회사) CEO가 자기 작업 방식을 공개한 것으로, 깃허브 저장소는 garrytan/gstack입니다. 별(관심 표시)은 2026년 10월 기준 약 13만 7천 개이고 MIT 라이선스입니다. CEO, 디자이너, 엔지니어링 매니저, QA 책임자, 릴리스 엔지니어처럼 역할을 나눈 23개 도구가 모두 슬래시(/) 명령으로 들어 있습니다. 전문적인 기획 경험이 없어도 이 역할들을 빌려 기획서를 다듬고 코드를 검수할 수 있습니다.

작업 순서와 역할 나누기

전체 흐름은 네 덩어리입니다.

• gstack 설치
• gstack으로 프로젝트 기획
• 기획서를 바탕으로 에이전트에게 구현 맡기기
• 다시 gstack으로 코드 리뷰와 검증

역할도 나눕니다. 기획과 검증은 클로드 코드, 구현은 코덱스입니다. 서로 다른 모델이 다른 관점에서 교차 검증하게 하려는 의도입니다. 실제 개발팀에서 기획하는 사람, 구현하는 사람, 리뷰하는 사람이 따로 있듯 그 구조를 AI 작업 흐름에 옮긴 것이고, 이것도 하네스 엔지니어링의 한 방식입니다.

준비물

• 클로드 코드: 기획과 검수에 씁니다.
• 코덱스: 구현에 씁니다.
• Git(코드 버전 관리 도구)과 Bun(자바스크립트 실행 도구) 1.4.2 이상. gstack 설치에 필요하고, Bun이 1.3.3보다 낮으면 설치가 멈춥니다. 버전은 터미널에서 bun --version으로 확인합니다.
• 윈도우라면 Node.js도 필요합니다.
• VS Code 같은 편집기: 생긴 폴더와 파일을 눈으로 확인할 때 편합니다.

1. gstack 설치

1. 검색창에 gstack을 검색해 깃허브 저장소 garrytan/gstack을 엽니다.
   • 확인: 저장소 첫 화면에 설명과 사용법, 설치 방법(Install)이 보입니다.
2. 설치 안내의 사전 준비 목록(Claude Code, Git, Bun, 윈도우는 Node.js)을 확인합니다.
   • 확인: 내 컴퓨터에 설치된 것과 안 된 것을 구분할 수 있습니다.
3. 빠진 프로그램이 있으면 목록의 이름을 눌러 각 공식 페이지에서 먼저 설치합니다.
   • 모두 설치돼 있으면 건너뜁니다.
4. 실습용 폴더를 하나 만듭니다. 예를 들어 바탕화면에 "workspace" 폴더를 만들고 VS Code로 엽니다.
5. VS Code에서 터미널을 엽니다(메뉴의 Terminal → New Terminal).
6. 아래 설치 명령을 붙여 넣고 엔터를 누릅니다. 내 사용자 폴더의 .claude/skills/gstack에 설치되고, 모든 프로젝트의 클로드 코드에서 쓸 수 있게 됩니다.
   • 확인: 설치가 끝나면 ~/.claude/skills/gstack 폴더 안에 office-hours, plan-ceo-review, plan-eng-review, design-review, design-shotgun, freeze 같은 하위 폴더가 보입니다.

git clone --single-branch --depth 1 https://github.com/garrytan/gstack.git ~/.claude/skills/gstack && cd ~/.claude/skills/gstack && ./setup

7. (선택) office-hours 폴더의 스킬 파일을 열어 봅니다.
   • 확인: Y Combinator의 오피스 아워(창업자와 마주 앉아 아이디어를 따져 묻는 상담 시간) 방식으로 아이디어를 기획한다는 설명과, 새 제품 아이디어를 말할 때 이 스킬을 쓰라는 안내가 적혀 있습니다.

설치 명령의 ./setup은 스킬 말고도 gstack 전용 브라우저를 만들고, ~/.claude/settings.json에 작업 기록용 훅(정해진 때 자동으로 도는 명령) 하나를 등록합니다. 이 훅이 필요 없으면 ./setup --no-timeline-stop-hook으로 설치합니다. 설치가 됐는지는 9단계처럼 클로드 코드 입력창에 /를 쳐서 office-hours 같은 이름이 보이는지로 확인합니다.

팀이 같이 쓰는 저장소라면 팀 모드도 있습니다. 내 컴퓨터에 gstack을 설치한 뒤 그 저장소 폴더 안에서 아래 명령을 실행하면, 팀 모드로 바뀌고 팀원이 저장소를 받을 때 gstack이 함께 깔리도록 설정한 뒤 그 변경을 커밋합니다. required 대신 optional을 쓰면 강제하지 않고 권하기만 합니다.

(cd ~/.claude/skills/gstack && ./setup --team) && ~/.claude/skills/gstack/bin/gstack-team-init required && git add .claude/ CLAUDE.md && git commit -m "require gstack for AI-assisted work"

지울 때는 터미널에서 아래 명령을 실행합니다. 스킬과 ~/.gstack/ 기록, 브라우저 프로세스까지 정리하고, 기록을 남기려면 --keep-state를 붙입니다. 프로젝트의 CLAUDE.md에 gstack 구획을 넣었다면 그 부분은 직접 지웁니다. 명령은 2026년 10월 기준 저장소 README를 따랐습니다.

~/.claude/skills/gstack/bin/gstack-uninstall

2. 기획: /office-hours로 기획서 만들기

8. 실습 폴더에서 클로드 코드를 엽니다(터미널에서 claude 입력).
9. 입력창에 슬래시(/) 하나를 입력합니다.
   • 확인: 쓸 수 있는 스킬 목록에 office-hours, plan-ceo-review, plan-design-review, design-review, design-shotgun 같은 이름이 보입니다.
10. /office-hours를 고르고, 만들고 싶은 것을 한 문장으로 적습니다. 끝에 "답변을 한글로 해라"를 붙입니다.
    • 이유: 스킬 파일이 모두 영어라서 그냥 입력하면 영어로 답하는 경우가 많습니다.

대한민국 AI 관련 정부 지원 사업, 공모전, 해커톤, 연구 과제 공고를 학생, 스타트업, 기업, 연구자 기준으로 나눠서 한 눈에 보여주는 웹사이트를 만들고 싶다

답변을 한글로 해라

11. 모델을 가볍고 저렴한 Haiku 계열로 바꿉니다(/model 입력 후 선택).
    • 이유: 기획 단계는 코드를 쓰는 단계가 아니라서 빠르고 싼 모델로도 충분합니다.
12. 엔터를 눌러 보냅니다.
    • 확인: 오피스 아워를 시작한다는 메시지가 나오고, 에이전트가 먼저 프로젝트 상태를 살핍니다.
13. 첫 질문(프로젝트의 궁극적인 목표)에서 보기 하나를 고릅니다.
    • 추천(Recommended) 표시가 붙은 답이 있지만, 기획하려는 방향에 맞춰 고르면 됩니다. 예를 들어 "스타트업 및 비즈니스 만들기"를 고를 수 있습니다.
14. 두 번째 질문(사람들이 이 서비스를 원한다는 증거)에 답합니다.
    • 최종 제품이 충분히 매력적인지 근거를 묻는 질문입니다. 실제 근거가 없다면 없다고 답하는 편이 기획서를 현실적으로 만듭니다.
15. 이어지는 질문마다 고르거나 답합니다.
    • 확인: 대화를 거칠수록 실제 수요가 있는지, 무엇을 만들지가 구체적으로 정리됩니다. 에이전트와 계속 대화하며 기획서를 날카롭게 다듬는 단계입니다.
16. 마지막에 최종 승인 여부를 묻는 질문에서 승인합니다.
    • 확인: 기획서가 파일로 만들어집니다.
17. 만들어진 기획서를 엽니다.
    • 확인: 제목, 생성일, 상태, 해결하려는 문제, 수요가 있다고 보는 근거, 현재 상황, 대상과 주 고객층, 제약과 전제 같은 항목이 들어 있습니다.

3. 기획 검토: CEO 리뷰와 엔지니어링 리뷰

18. 입력창에 /plan-ceo-review를 고르고 아래 문장을 보냅니다.
    • 확인: 오피스 아워에서 만든 기획서를 CEO 관점에서 검토하기 시작합니다. 플랜 CEO 리뷰는 요청 속에 숨은 더 나은 제품을 찾고, 범위를 넓힐지 줄일지 따져 봅니다.

지금까지 작성한 기획서를 검토해 주세요

19. 에이전트가 던지는 추가 질문에 고르거나 답합니다.
    • 확인: CEO 리뷰가 끝나 설계가 승인되고, 출시 이후 단계별 계획이 더해집니다.
20. 바로 구현할지 엔지니어링 리뷰를 할지 묻는 질문에서 엔지니어링 리뷰를 고르고 아래 문장을 보냅니다.
    • 확인: 이번에는 CTO 관점에서 기획서와 아키텍처(전체 구조), 데이터 흐름, 예외 상황, 테스트 계획에 대한 피드백이 나옵니다.

플랜 엔지니어링 리뷰 스킬을 사용해서 엔지니어링 리뷰도 해 주세요.

CEO 리뷰 다음에 엔지니어링 리뷰를 하는 순서를 지킵니다. 제품 방향이 바뀐 뒤에 기술 구조를 확정해야 다시 고칠 일이 적습니다. gstack에는 CEO·디자인⁠·엔지니어링 리뷰를 한 번에 이어서 돌리는 /autoplan도 있습니다.

4. 구현: 기획서를 코덱스에 넘기기

21. 엔지니어링 리뷰가 끝났는지 확인합니다.
    • 확인: 이제 구현하면 된다는 취지의 안내가 나옵니다.
22. 클로드 코드에게 기획 문서가 어디 저장됐는지 묻습니다.
    • 이유: gstack의 기획서는 프로젝트 폴더가 아니라 사용자 폴더의 ~/.gstack/projects/ 아래에 저장됩니다. 코덱스는 실습 폴더 안만 보기 때문에 경로를 알려 줘야 읽을 수 있습니다.
    • 확인: 기획서 파일 경로를 알려 줍니다.
23. 코덱스에서 실습 폴더를 열고, 그 경로를 넣어 구현을 요청합니다.
    • 확인: 코덱스가 기획서를 읽고 MVP(핵심 기능만 담은 첫 버전) 코드를 쓰기 시작합니다. 끝나면 작성이 끝났다고 알립니다.

이 경로에 기획서가 있으니 이걸 기반으로 구현 시작해라

코덱스에서도 gstack 스킬을 직접 쓰고 싶다면 두 방법이 있습니다. 하나는 코덱스로 실습 폴더를 열 때 클로드 스킬을 가져올지 묻는 창이 뜨면 가져오기를 고르는 것입니다. 그러면 .claude 옆에 .agents/skills 폴더가 생기고 같은 스킬이 복사됩니다. 다른 하나는 gstack 공식 안내대로 ./setup --host codex로 코덱스용을 따로 까는 것입니다. 저장소 안내 기준으로 코덱스 지원은 아직 실험 단계입니다.

5. 검수: /qa-only로 보고서 받기

24. 클로드 코드에서 QA 계열 스킬 가운데 하나를 고릅니다.
    • /qa: 실제로 실행해 보며 버그를 찾고, 고친 뒤 다시 확인까지 합니다.
    • /qa-only: 실행해 보며 문제를 찾아 보고서만 씁니다. 코드는 고치지 않습니다.
    • /design-review: 화면 디자인을 점검하고 고칩니다.
    • 구현과 검수를 다른 모델에 맡기려면 /qa-only가 맞습니다.
25. 모델을 Opus 계열 같은 상위 모델로 바꿉니다.
    • 이유: 코드를 실제로 실행하고 기능을 하나씩 확인하는 복잡한 작업이라서입니다.
26. 스킬을 실행합니다.
    • 확인: 에이전트가 서비스를 실행해 기능을 하나씩 확인한 뒤 보고서를 씁니다. 발견된 문제는 심각도별로 나뉘어 즉시 고칠 것부터 정리됩니다.
27. (선택) 보고서를 코덱스나 클로드 코드에 넘겨 고치라고 지시합니다.
    • 확인: 다른 모델이 찾은 문제를 구현 쪽이 고치는 교차 검증이 한 바퀴 돕니다.

끝나고 점검할 것

• ~/.claude/skills/gstack 폴더가 생겼다
• /office-hours로 기획서 파일이 만들어졌다
• CEO 리뷰와 엔지니어링 리뷰 피드백을 받았다
• 코덱스가 기획서를 읽고 코드를 작성했다
• /qa-only 검수 보고서가 만들어졌다

gstack을 그대로 쓸 때 부딪히는 한계

여러 번 써 보면 gstack이 늘 정답은 아니라는 점이 보입니다. 자주 부딪히는 문제는 네 가지입니다.

• 영어 결과물: 스킬 문서가 영어라 결과물도 영어로 나오곤 합니다. 웹사이트 문구가 전부 영어로 만들어지거나, 외국 사이트에서 데이터를 모으는 서비스가 나오기도 합니다.
• 토큰과 컨텍스트 부담: 만들어지는 문서가 많아 읽는 데 토큰(AI가 처리하는 글자 단위, 사용량과 비용의 기준)을 많이 씁니다. 에이전트가 한 번에 기억해야 할 내용이 늘어 오히려 성능이 떨어지기도 합니다.
• 윈도우 호환: 윈도우에서는 간혹 제대로 돌지 않습니다.
• 내 스타일과의 차이: 내가 자주 쓰는 색상이나 버튼 문구와 잘 맞지 않습니다.

그래서 gstack을 통째로 쓰기보다, 공개된 스킬 마크다운 파일을 열어 내 작업에 맞게 고쳐 쓰는 편이 낫습니다. 예를 들어 자주 쓰는 스킬 파일 앞에 "모든 답과 결과물 문구는 한국어로 쓴다", "데이터는 한국 공공기관 사이트에서 모은다" 같은 규칙을 넣거나, 쓰지 않는 스킬 폴더는 지워 목록을 줄입니다. 기획⁠·구현⁠·리뷰를 서로 다른 모델에 나눠 맡긴다는 구조만 가져가도 하네스로서 효과는 충분합니다.