본문으로 건너뛰기

GateKit으로 코드보다 기획 문서를 먼저 만든 사례

위올라이

2026.10.06

하려던 것 📝

  • 비개발자가 Claude Code에 GateKit을 설치하고, 코드를 쓰기 전에 기획 문서부터 만든 사례

  • 외국인 관광객에게 한국 여행·생활 정보를 자기 언어로 제공해 검색 유입과 광고·제휴 수익을 만드는 다국어 정보 사이트를 구상하고 있었음.

  • 다만 "무엇을 만들지"가 머릿속 구상 수준이어서, 바로 개발로 들어가면 방향이 흔들릴 것이라 판단함.

  • 그래서 GateKit을 설치해 발굴(discover) → 인터뷰(interview) 순서로 진행하며, 짐작과 확인된 사실을 구분해 문서로 남기는 방식을 시도함.

활용한 툴 ⚒️

  • Claude Code (CLI 2.1.284, WSL2): GateKit 플러그인을 설치하고 /gatekit:* 명령을 실행하는 개발 환경.

  • GateKit (0.11.2): 프로젝트 순서를 발굴 → 인터뷰 → 디자인 → 작업분해 → 완료기준 → 빌드 → 검증으로 표준화하고, 훅(hook)으로 단계를 건너뛰지 못하게 막는 작업 체계.

  • Python 3.14.4: GateKit의 게이트 스크립트 6개가 Python으로 동작하므로 점검 대상에 포함됨.

  • AI 파트너(Claude): 설치 명령 실행, 진단 결과 해석, 발굴·인터뷰 질문 진행, 생소한 용어 설명을 맡음. 선택과 승인은 사용자가 직접 함.

진행 세부 내용 🔍

1️⃣ 플러그인 전역 설치

  • 저장소를 마켓플레이스로 등록한 뒤 플러그인을 설치함 (/plugin marketplace add … → /plugin install gatekit@gatekit).

  • 문제: 두 명령을 한 번에 붙여 넣어 진행되지 않음 → 하나씩 나눠 실행해 해결함. 중간에 인증이 끊겨 /login을 다시 거쳐야 했음.

  • 결과: ~/.claude/settings.json에 플러그인 활성화가 기록되고 0.11.2가 설치됨.

2️⃣ doctor로 설치 상태 진단

  • /gatekit:doctor로 8개 항목(플러그인 파일, 훅 등록, 프로젝트 상태, 기획 문서, 완료 기준, 워커, Python, 호스트 계층)을 점검함.

  • 결과: 플러그인 파일·훅 등록·워커·Python·호스트 계층은 ok, 프로젝트 상태·기획 문서·완료 기준은 unverified.

  • 문제: 미확인 3개를 설치 실패로 오해함 → 원인은 설치가 아니라 실행 위치였음. 홈 폴더에서 돌려 프로젝트가 없었던 것이고, "모르면 ok로 적지 않고 unverified로 남긴다"는 GateKit의 방식임을 이해함.

3️⃣ 프로젝트 설치와 백엔드 선택

  • 테스트 폴더로 이동해 /gatekit:setup을 실행하니 .gatekit/config.json이 생성됨.

  • 기록된 설정: 기획 문서 없이 코드를 못 쓰게 하는 옵션(enforce_spec_before_code) 활성, 워커 백엔드 claude 활성, 재시도 2회·동시 실행 3개·작업당 15분 제한.

  • 판단: Codex 백엔드는 샌드박스 설정이 필요한 선택 기능이라 켜지 않고 비활성으로 둠. 지금 필요한 것은 기획 단계이고 코드를 대신 쓰는 워커는 쓸 일이 없다고 보았음.

4️⃣ 훅이 실제로 막는지 확인

  • 등록된 훅을 직접 확인함 — 프롬프트 제출, 파일 쓰기·편집 전, Bash 실행 전, 대화 압축 전, 응답 종료 시점에 각각 게이트가 걸려 있음.

  • 작업 중 AI가 Bash로 인라인 Python 코드를 실행하려 했을 때, GateKit이 "이 명령이 어떤 파일에 쓰는지 알 수 없어 차단한다"며 실제로 막음. 설치 완료 표시만 믿지 않고 차단 동작을 눈으로 확인함.

5️⃣ /gatekit:discover — 만들 것 발굴

  • 고정된 질문 목록이 아닌 자유로운 대화로 불편 3개를 뽑고 하나를 고름.

    1. 외국인이 한국의 교통·지도·결제 같은 생활 정보와 지역 정보를 자기 언어로 찾기 어렵다 → 선택

    2. 길찾기 도구 → 지도 앱이 이미 있어 1번 안에서 사용법 안내로 다루기로 함

    3. 숙소 배정 정보 → 외부에서 정확히 줄 수 있는지 미확인

  • AI에게 의견을 물어, 한국 특유의 공백(구글 지도 길찾기 제한과 네이버·카카오맵 사용법, 교통카드 구매·충전, 유심·eSIM, 해외 카드 결제, 번역·호출 앱, 계절별 날씨 대비)을 범위에 포함하기로 확정함.

  • 결과: spec/00-discovery.md 생성. 선택한 불편, 판정(build), 기한(4주), 왜-사슬, 기존 공식 정보 사이트를 확인했지만 생활 정보가 얕았다는 실패 기록, 성공 기준(월 방문자 10만 명), 대화가 실제로 밝혀낸 사실 25개가 담김.

  • 가장 중요했던 점: 이 불편들이 직접 겪은 것이 아니라 짐작이라는 사실이 문서에 "사용자 추정·미확인"으로 그대로 남고, 확인 못 한 항목(빈도·소요시간)이 따로 표시되며, 남은 숙제는 "누가 확인할 수 있는지"까지 적힘.

6️⃣ /gatekit:interview — 화면과 기능 정리

  • 발굴 결과를 바탕으로 어떤 화면이 필요하고 각 화면이 무엇을 하는지 정리함.

  • 사용자가 추가로 제안: 방문자끼리 정보를 주고받고 동행을 찾는 커뮤니티. "게시판은 선점 효과가 크다"고 보아 일찍 열어 자리 잡는 전략을 우선순위로 둠.

  • 정리된 첫 버전 범위: 첫 화면 / 생활 가이드 글 10편 / 커뮤니티(주제 게시판 4개 — 질문과 답변, 동행 구하기, 정보 공유와 후기, 자유, 국가·지역은 꼬리표로 모아 보기, AI 자동 번역과 AI 1차 필터) / 구글·애플 로그인 / 관리 화면. 지원 언어는 12개로 시작(30개 이상 전체 개방은 보류), 광고는 애드센스와 제휴 링크를 가이드 글·게시판에만 배치. 지역 상세 화면은 다음 버전으로 미룸.

  • 문제: 인터뷰에서 정한 내용이 아직 파일로 저장되지 않고 대화 안에만 있다는 사실을 확인함. 저장된 것은 발굴 결과뿐이고 PRD·기술 스펙은 미생성 상태임.

시행착오 ⚠️

  • 슬래시 명령 두 개를 한 번에 붙여 넣어 설치가 진행되지 않음 → 하나씩 실행해 해결함. 인증이 끊겨 /login도 다시 거침.

  • doctor의 unverified 3개를 설치 실패로 오해함 → 홈 폴더에서 실행한 위치 문제였음.

  • Python, hook, sandbox, 워커, 백엔드 같은 용어가 생소해 바로 판단하기 어려웠음 → 쉬운 말로 다시 설명을 요청해 이해한 뒤 선택했고, Codex 백엔드는 필요하지 않다고 보아 켜지 않음.

  • 설치 "완료" 표시와 실제 동작이 다를 수 있다고 보아 훅을 확인했고, AI의 Bash 명령이 실제로 차단되는 것을 직접 봄.

  • 가장 아쉬운 부분: 발굴 결과는 파일로 남았는데 인터뷰에서 정한 화면·기능·언어·광고 방침은 대화 안에만 남아 있었음. 다른 창에서 이어 작업하려다 알게 됐고, 대화가 길어지면 잃을 수 있는 상태였음.

배운 점 📚

  • GateKit은 특정 작업을 자동 실행하는 스크립트가 아니라, 진행 순서를 문서와 규칙으로 고정하는 작업 매뉴얼 체계임을 이해함. 머릿속 구상이 문서로 남으니 다른 사람이나 다른 AI도 같은 틀에서 이어 작업할 수 있음.

  • 짐작과 확인된 사실을 구분해 기록하는 것이 생각보다 중요했음. 내 아이디어의 근거 대부분이 추정이었고, 문서에 그렇게 남기니 무엇을 더 검증해야 하는지가 분명해짐.

  • unverified는 실패가 아니라 "아직 판단할 근거가 없음"을 뜻했고, 모르는 것을 모른다고 적는 방식이 오히려 신뢰를 줌.

  • AI에게 일을 맡길 때는 목표뿐 아니라 하지 말 것(예: Codex 백엔드 켜지 않기)과 확인 기준을 함께 주는 편이 결과가 일관됨.

  • 문서가 있어야 다음 단계로 넘어가는 구조라, 기획을 건너뛰고 코드로 뛰어드는 습관을 구조적으로 막아 줌.

향후 계획 🧭

  • 인터뷰에서 정한 내용을 먼저 파일로 확정해 PRD와 기술 스펙을 생성할 계획임.

  • 이후 디자인 → 작업분해 → 완료 기준 → 빌드 → 검증까지 한 번 통과시켜 볼 계획이며, 완료 기준은 승인 전에 명령을 하나씩 직접 읽고 판단할 계획임.

  • 발굴 문서의 "남은 것" 4개를 실제로 확인해 짐작을 사실로 바꾸는 일을 우선할 계획임.

  • 커뮤니티 게시판은 선점 효과가 크다고 보아, 성수기보다 한참 앞서 첫 버전을 열어 검색 색인과 사용자를 먼저 모으는 일정으로 잡을 계획임.

  • 진행 기록을 git에 커밋하고, 설치 단계에서 생소했던 용어를 비개발자용 메모로 따로 정리해 둘 계획임.

도움이 필요한 점 🤝

1️⃣ 대화 단계의 결과가 파일로 남지 않는 문제

  • 현재 상황: 발굴 단계는 파일로 저장되는데, 인터뷰에서 긴 대화로 정한 화면 구성·기능·지원 언어·광고 방침은 문서가 완성되기 전까지 대화 안에만 있었습니다. 창을 닫거나 대화가 길어지면 잃을 수 있는 구간이 생깁니다.

  • 시도한 방법: 같은 폴더에서 claude --continue로 이전 대화를 이어 가는 방법을 확인하고, 중간 진행 상황을 별도 파일로 저장하는 방법을 검토했습니다.

  • 필요한 도움: 긴 인터뷰의 중간 결과를 안전하게 저장하며 진행하는 권장 방법에 대한 조언이 필요합니다.

2️⃣ 짐작으로 시작한 아이디어의 검증 방법

  • 현재 상황: 대상 사용자가 실제로 무엇을 찾고 어디서 막히는지 직접 확인한 적이 없어 발굴 문서의 핵심 근거가 추정입니다. 월 방문자 10만 명이 광고 수익으로 어느 정도인지도 확인하지 못했습니다.

  • 시도한 방법: 기존 공식 정보 사이트를 확인해 정보 공백을 가늠하고, 확인되지 않은 항목은 문서에 미확인으로 표시했습니다.

  • 필요한 도움: 실제 사용자를 만나기 어려운 주제에서 적은 비용으로 수요를 확인하는 방법에 대한 조언이 필요합니다.

1

함께 이야기해요 1

로그인하고 댓글을 남겨 주세요

뽀짝이 프로필 이미지
뽀짝이2026.10.06

위올라이님, 안녕하세요! 글 잘 읽었어요.

doctor의 unverified 3개를 설치 실패로 오해했다가 홈 폴더에서 실행한 위치 문제였다는 걸 알아낸 과정이 생생했어요. "모르면 ok로 적지 않고 unverified로 남기는" GateKit의 방식을 이해하고 나서 "모르는 것을 모른다고 적는 방식이 오히려 신뢰를 준다"고 정리하신 부분이 좋았습니다.

AI의 Bash 명령이 실제로 차단되는 걸 눈으로 확인하신 점, 그리고 발굴 문서에 "사용자 추정·미확인"이 그대로 남는다는 걸 가장 중요한 점으로 꼽으신 것도 인상적이었어요. 도움이 필요한 점에 적어 주신 두 가지 중 인터뷰 중간 결과 저장은 대화가 길어지기 전에 단계마다 파일로 내려받는 습관으로 풀릴 가능성이 있어 보여요. 다른 분들 경험도 댓글로 모이면 좋겠어요.

PRD가 만들어지는 다음 단계 후기도 기다릴게요. 고롱고롱 ✨

필요한 AI 정보만
메일함에 쏙쏙 넣어드려요.

지금 핫한 AI 소식부터 직접 해 본 사례까지, 월요일마다 무료로 받아보세요

이런 사례도 있어요

사례 전체 보기