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번 안에서 사용법 안내로 다루기로 함
숙소 배정 정보 → 외부에서 정확히 줄 수 있는지 미확인
AI에게 의견을 물어, 한국 특유의 공백(구글 지도 길찾기 제한과 네이버·카카오맵 사용법, 교통카드 구매·충전, 유심·eSIM, 해외 카드 결제, 번역·호출 앱, 계절별 날씨 대비)을 범위에 포함하기로 확정함.
결과:
spec/00-discovery.md생성. 선택한 불편, 판정(build), 기한(4주), 왜-사슬, 기존 공식 정보 사이트를 확인했지만 생활 정보가 얕았다는 실패 기록, 성공 기준(월 방문자 10만 명), 대화가 실제로 밝혀낸 사실 25개가 담김.가장 중요했던 점: 이 불편들이 직접 겪은 것이 아니라 짐작이라는 사실이 문서에 "사용자 추정·미확인"으로 그대로 남고, 확인 못 한 항목(빈도·소요시간)이 따로 표시되며, 남은 숙제는 "누가 확인할 수 있는지"까지 적힘.
6️⃣ /gatekit:interview — 화면과 기능 정리
발굴 결과를 바탕으로 어떤 화면이 필요하고 각 화면이 무엇을 하는지 정리함.
사용자가 추가로 제안: 방문자끼리 정보를 주고받고 동행을 찾는 커뮤니티. "게시판은 선점 효과가 크다"고 보아 일찍 열어 자리 잡는 전략을 우선순위로 둠.
정리된 첫 버전 범위: 첫 화면 / 생활 가이드 글 10편 / 커뮤니티(주제 게시판 4개 — 질문과 답변, 동행 구하기, 정보 공유와 후기, 자유, 국가·지역은 꼬리표로 모아 보기, AI 자동 번역과 AI 1차 필터) / 구글·애플 로그인 / 관리 화면. 지원 언어는 12개로 시작(30개 이상 전체 개방은 보류), 광고는 애드센스와 제휴 링크를 가이드 글·게시판에만 배치. 지역 상세 화면은 다음 버전으로 미룸.
문제: 인터뷰에서 정한 내용이 아직 파일로 저장되지 않고 대화 안에만 있다는 사실을 확인함. 저장된 것은 발굴 결과뿐이고 PRD·기술 스펙은 미생성 상태임.
시행착오 ⚠️
슬래시 명령 두 개를 한 번에 붙여 넣어 설치가 진행되지 않음 → 하나씩 실행해 해결함. 인증이 끊겨
/login도 다시 거침.doctor의
unverified3개를 설치 실패로 오해함 → 홈 폴더에서 실행한 위치 문제였음.Python, hook, sandbox, 워커, 백엔드 같은 용어가 생소해 바로 판단하기 어려웠음 → 쉬운 말로 다시 설명을 요청해 이해한 뒤 선택했고, Codex 백엔드는 필요하지 않다고 보아 켜지 않음.
설치 "완료" 표시와 실제 동작이 다를 수 있다고 보아 훅을 확인했고, AI의 Bash 명령이 실제로 차단되는 것을 직접 봄.
가장 아쉬운 부분: 발굴 결과는 파일로 남았는데 인터뷰에서 정한 화면·기능·언어·광고 방침은 대화 안에만 남아 있었음. 다른 창에서 이어 작업하려다 알게 됐고, 대화가 길어지면 잃을 수 있는 상태였음.
배운 점 📚
GateKit은 특정 작업을 자동 실행하는 스크립트가 아니라, 진행 순서를 문서와 규칙으로 고정하는 작업 매뉴얼 체계임을 이해함. 머릿속 구상이 문서로 남으니 다른 사람이나 다른 AI도 같은 틀에서 이어 작업할 수 있음.
짐작과 확인된 사실을 구분해 기록하는 것이 생각보다 중요했음. 내 아이디어의 근거 대부분이 추정이었고, 문서에 그렇게 남기니 무엇을 더 검증해야 하는지가 분명해짐.
unverified는 실패가 아니라 "아직 판단할 근거가 없음"을 뜻했고, 모르는 것을 모른다고 적는 방식이 오히려 신뢰를 줌.AI에게 일을 맡길 때는 목표뿐 아니라 하지 말 것(예: Codex 백엔드 켜지 않기)과 확인 기준을 함께 주는 편이 결과가 일관됨.
문서가 있어야 다음 단계로 넘어가는 구조라, 기획을 건너뛰고 코드로 뛰어드는 습관을 구조적으로 막아 줌.
향후 계획 🧭
인터뷰에서 정한 내용을 먼저 파일로 확정해 PRD와 기술 스펙을 생성할 계획임.
이후 디자인 → 작업분해 → 완료 기준 → 빌드 → 검증까지 한 번 통과시켜 볼 계획이며, 완료 기준은 승인 전에 명령을 하나씩 직접 읽고 판단할 계획임.
발굴 문서의 "남은 것" 4개를 실제로 확인해 짐작을 사실로 바꾸는 일을 우선할 계획임.
커뮤니티 게시판은 선점 효과가 크다고 보아, 성수기보다 한참 앞서 첫 버전을 열어 검색 색인과 사용자를 먼저 모으는 일정으로 잡을 계획임.
진행 기록을 git에 커밋하고, 설치 단계에서 생소했던 용어를 비개발자용 메모로 따로 정리해 둘 계획임.
도움이 필요한 점 🤝
1️⃣ 대화 단계의 결과가 파일로 남지 않는 문제
현재 상황: 발굴 단계는 파일로 저장되는데, 인터뷰에서 긴 대화로 정한 화면 구성·기능·지원 언어·광고 방침은 문서가 완성되기 전까지 대화 안에만 있었습니다. 창을 닫거나 대화가 길어지면 잃을 수 있는 구간이 생깁니다.
시도한 방법: 같은 폴더에서
claude --continue로 이전 대화를 이어 가는 방법을 확인하고, 중간 진행 상황을 별도 파일로 저장하는 방법을 검토했습니다.필요한 도움: 긴 인터뷰의 중간 결과를 안전하게 저장하며 진행하는 권장 방법에 대한 조언이 필요합니다.
2️⃣ 짐작으로 시작한 아이디어의 검증 방법
현재 상황: 대상 사용자가 실제로 무엇을 찾고 어디서 막히는지 직접 확인한 적이 없어 발굴 문서의 핵심 근거가 추정입니다. 월 방문자 10만 명이 광고 수익으로 어느 정도인지도 확인하지 못했습니다.
시도한 방법: 기존 공식 정보 사이트를 확인해 정보 공백을 가늠하고, 확인되지 않은 항목은 문서에 미확인으로 표시했습니다.
필요한 도움: 실제 사용자를 만나기 어려운 주제에서 적은 비용으로 수요를 확인하는 방법에 대한 조언이 필요합니다.




위올라이님, 안녕하세요! 글 잘 읽었어요.
doctor의 unverified 3개를 설치 실패로 오해했다가 홈 폴더에서 실행한 위치 문제였다는 걸 알아낸 과정이 생생했어요. "모르면 ok로 적지 않고 unverified로 남기는" GateKit의 방식을 이해하고 나서 "모르는 것을 모른다고 적는 방식이 오히려 신뢰를 준다"고 정리하신 부분이 좋았습니다.
AI의 Bash 명령이 실제로 차단되는 걸 눈으로 확인하신 점, 그리고 발굴 문서에 "사용자 추정·미확인"이 그대로 남는다는 걸 가장 중요한 점으로 꼽으신 것도 인상적이었어요. 도움이 필요한 점에 적어 주신 두 가지 중 인터뷰 중간 결과 저장은 대화가 길어지기 전에 단계마다 파일로 내려받는 습관으로 풀릴 가능성이 있어 보여요. 다른 분들 경험도 댓글로 모이면 좋겠어요.
PRD가 만들어지는 다음 단계 후기도 기다릴게요. 고롱고롱 ✨