비개발자인 내가 AI 파트너 써니와 GateKit을 설치해본 과정
2026.10.05

소개
이번 주에는 새로운 서비스를 바로 만드는 대신, 앞으로 AI와 함께 개발할 때 사용할 작업 방식을 먼저 정리했다. 내가 선택한 것은 GateKit이었다.
나는 개발자가 아니다. AI를 활용해 프로젝트를 진행하고 있지만 Python, hook, sandbox, CLI, 테스트 같은 표현은 여전히 낯설다. 그래서 이번 설치는 명령어를 그대로 따라 치는 방식이 아니라, 내가 AI 파트너인 써니에게 목표와 조건을 설명하고 써니가 내 Mac에서 Codex와 GateKit을 활용해 실행하는 방식으로 진행했다. 나는 중간중간 결과를 확인하고 중요한 선택과 설치 진행 여부를 승인했다.
GateKit은 한 번 실행하는 단일 스크립트라기보다 프로젝트 진행 순서를 표준화하는 작업 체계에 가까웠다. 인터뷰로 요구사항을 정리하고, 작업을 나누고, 완료 기준을 정한 뒤 구현과 검증으로 넘어가는 흐름을 프로젝트 안에 남길 수 있다는 점이 인상적이었다.
진행 방법
1️⃣ 먼저 설치 기준부터 정했다
설치를 시작하기 전에 써니와 함께 어떤 방식으로 설치할지 먼저 정했다.
- 공식 저장소와 문서를 기준으로 설치할 것
- 전역 설치와 프로젝트별 설치를 구분할 것
- 자동 업데이트와 sandbox 우회 기능은 사용하지 않을 것
- 기존 프로젝트 파일을 함부로 수정하지 않을 것
- 설치 후에는 doctor와 실제 테스트로 동작을 확인할 것
예전 같으면 일단 설치부터 했겠지만, 이번에는 먼저 조건을 정하고 그 기준에 맞춰 진행했다. 이 과정 자체가 GateKit이 지향하는 방식과 닮아 있었다.
2️⃣ 프로젝트 밖과 안을 나눠 설치했다
GateKit은 두 단계로 설치했다.
- 전역 설치: Codex가 GateKit 명령과 스킬을 인식할 수 있도록 플러그인을 설치
- 프로젝트 설치: 현재 프로젝트에 .gatekit, spec, AGENTS.md 같은 구조를 생성
처음에는 설치가 프로그램 하나를 추가하는 단순한 과정이라고 생각했다. 하지만 실제로는 AI가 사용할 공통 도구를 준비하는 일과 각 프로젝트에 필요한 규칙과 문서를 만드는 일이 분리돼 있었다.
3️⃣ 설치 여부와 hook 상태를 확인했다
설치가 끝난 뒤 써니가 doctor 진단을 실행해 플러그인 파일, hook 등록, 프로젝트 상태, spec 문서, Python 환경 등을 확인했다.
설치 파일은 정상적으로 들어갔지만 처음에는 Codex가 이전 설정을 들고 있어 hook이 바로 활성화되지 않았다. /hooks 화면에는 아무것도 나타나지 않았고 doctor는 hook이 등록되지 않았다고 경고했다.


4️⃣ 재시작만으로 해결되지 않아 원인을 좁혔다
Codex를 재시작해도 hook이 바로 나타나지 않았다. 이후 설정 파일의 hook 구문이 현재 환경과 맞지 않는 것을 확인했고, 써니가 관련 문서와 실행 기록을 대조해 호환되는 형식으로 수정했다.
여기서 중요했던 점은 경고 문구를 없애는 데서 멈추지 않은 것이다. 설정이 실제로 작동하는지 확인하기 위해 일부러 실패하는 테스트를 만들었다.
테스트 내용:
Python으로 종료 코드 1을 반환하도록 실행
확인 결과:
- 일반 셸에서는 실패 코드 1
- GateKit hook 환경에서는 해당 실패가 차단돼 코드 2로 변경
- Stop hook 로그까지 생성됨
즉 화면에 Active라고 표시되는 것뿐 아니라 실제 차단 기능까지 동작하는 것을 확인했다.
5️⃣ 기능을 하나씩 직접 호출했다
설치가 끝난 뒤에는 실제 프로젝트 흐름에서 사용할 기능도 확인했다.
- /gatekit:interview: 아이디어를 질문으로 구체화
- /gatekit:tasks: 명세를 실행 가능한 작업으로 분해
- /gatekit:gate: 완료 기준 정의
- /gatekit:verify: 구현 결과 검증
- /gatekit:doctor: 설치와 환경 진단
또한 써니에게 다음과 같이 요청해 실제 프로젝트 파일이 생성되는 것도 확인했다.
“비개발자도 이해할 수 있게 인터뷰해줘. 아직 실제 구현은 시작하지 말고 PRD와 기술 스펙만 작성해줘.”
그 결과 프로젝트 폴더에 요구사항 문서, 기술 스펙, 작업 목록, 완료 기준 파일이 만들어졌다.
결과와 배운 점
결과
- GateKit 플러그인 설치 완료
- 프로젝트 초기화 완료
- hook 활성화와 실제 차단 동작 확인
- 프로젝트 요구사항 문서와 기술 스펙 생성
- 인터뷰 → 명세 → 작업 분해 → 완료 기준 → 구현 → 검증 순서로 프로젝트를 진행할 기반 마련
어려웠던 점
가장 어려웠던 것은 모르는 용어가 너무 많았다는 점이다. AI를 활용하고 있어도 전문 지식이 없기 때문에 AI의 설명을 바로 이해하거나 판단하기 어려운 순간이 있었다. Python이 왜 필요한지, hook이 무엇을 막는지, sandbox가 왜 중요한지 하나씩 다시 물어봐야 했다.
또 설치 완료라는 말을 어디까지 믿어야 하는지도 고민됐다. 화면에 설치됐다고 보이는 것과 실제 기능이 작동하는 것은 달랐다. 이번에는 일부러 실패하는 테스트를 만들어 확인하면서, AI가 성공했다고 말하는 것만 듣지 않고 내가 확인할 수 있는 근거를 남기는 것이 중요하다는 점을 배웠다.
놀랍고 유용했던 점
가장 놀라웠던 점은 GateKit이라는 체계를 따로 만들어 프로젝트 진행 순서를 정형화했다는 것이다. 좋은 작업 순서를 머릿속에만 두는 것이 아니라 문서와 규칙으로 만들면 다른 사람이나 다른 AI도 같은 틀에 맞춰 일하게 할 수 있었다.
이번 설치를 통해 GateKit과 스크립트의 차이도 조금 이해하게 됐다.
- 스크립트는 설치, 검사, 파일 생성처럼 특정 작업을 자동으로 실행하는 도구다.
- GateKit은 여러 스크립트와 명령, 문서, 규칙을 묶어 프로젝트 전체의 진행 순서를 관리하는 체계다.
즉 GateKit 안에도 스크립트가 들어가지만 GateKit 전체를 하나의 스크립트라고 보기는 어렵다. 내가 이해한 가장 쉬운 비유는 스크립트가 개별 도구라면, GateKit은 그 도구를 언제 어떤 순서로 사용할지 정한 작업 매뉴얼이라는 것이다.
써니와 함께한 방식에서 배운 점
이번 작업에서 나는 Codex CLI를 직접 조작하기보다 AI 파트너 써니에게 목표와 조건을 설명했다. 써니는 Codex 실행 환경과 GateKit을 이용해 설치, 진단, 테스트, 기록을 수행했고 나는 중간 결과를 확인하며 진행 여부를 결정했다.
이 과정에서 AI를 활용한다는 것이 단순히 명령어를 대신 입력하게 하는 것은 아니라는 점을 느꼈다. 내가 목표, 금지 조건, 확인 기준을 분명하게 전달해야 AI도 더 안전하고 일관되게 움직였다. 반대로 모르는 부분을 그대로 넘기지 않고 쉬운 말로 다시 설명해달라고 요청하는 것도 내 역할이었다.
다음에 개선할 점
- 설치 전에 생소한 용어를 비개발자용 언어로 먼저 정리하기
- 성공 화면뿐 아니라 중간 경고와 해결 과정도 함께 캡처하기
- AI에게 설치를 맡길 때 목표, 금지 조건, 검증 기준을 한 번에 전달하기
- 설치 완료 보고를 받으면 실제 실패 테스트까지 확인하기
- 다음 프로젝트에서는 처음부터 GateKit 흐름에 맞춰 기록 남기기
도움 받은 글
- GateKit 공식 GitHub 저장소와 설치 문서
- GateKit doctor와 각 기능의 안내 문서
- Codex 공식 문서
이번 글은 특정 사례글을 그대로 따라 하기보다 공식 문서와 실제 설치·검증 기록을 바탕으로 작성했습니다.
로그인하고 댓글을 남겨 주세요
짠샨님, 설치부터 서두르지 않고 공식 문서·수정 금지 범위·검증 기준을 먼저 정하신 과정이 인상적이에요. 비개발자로서 모르는 용어를 그냥 넘기지 않고 하나씩 다시 질문하신 점도요.
doctor의 경고를 없앤 뒤에도 실제로 실패 코드 1을 실행해 hook 환경에서는 코드 2로 바뀌고 로그가 남는지 확인하신 부분이 특히 좋았어요. ‘설치됨’이라는 표시보다 동작 근거를 남기셨으니까요.
인터뷰에서 완료 기준과 검증까지 이어지는 다음 프로젝트도 기대할게요. 고롱고롱… 차근차근 확인하시는 모습에 저도 힘이 나요 ✨




AI파트너 써니도 궁금하네요 :) 1주차 gatekit 설치 완료하였다니 축하드립니다 😀