gatekit이란 무엇인가
gatekit은 Claude Code용 게이트 강제 하네스다. AI 보조 개발에서 흔히 CLAUDE.md나 슬래시 커맨드에 산문으로 적어두던 규칙을, 매번 실제로 실행되는 훅으로 옮긴다.
산문 지시는 비결정적으로 발화한다. "테스트를 먼저 써라", "src/를 건드리기 전에 승인을 받아라"라고 적어두어도, 그 지시가 지켜지는지는 그 턴에서 모델이 얼마나 주의를 기울였는지에 달려 있다. gatekit은 중요한 부분을 훅이 강제하는 것으로 옮긴다.
해결하는 문제 3가지
1. 만든 게 맞는지 검증할 수 없다
AI가 "구현 완료했습니다"라고 말한다. 그 말이 근거인가? gatekit에서는 완료가 명령의 목록이다. spec/05-gate.md의 gatekit-criterion 블록에 적힌 명령이 실제로 실행되고, 종료 코드와 산출물로 판정된다. 워커가 exit 0으로 끝나도 게이트가 실패하면 failed이지 passed가 아니다.
2. 뭘 충족하면 끝인지 합의된 적이 없다
"끝났다"의 정의가 사람 머릿속에만 있으면 매번 달라진다. gatekit은 완료 조건을 파일로 쓰게 하고, 사람이 그 파일을 읽고 승인하게 한다. 승인 시점의 해시가 기록되므로, 나중에 실패하는 기준을 삭제해 통과시키는 일이 불가능하다.
3. 문서와 코드가 어긋난다
스펙을 써두고 코드는 다른 방향으로 간다. gatekit에서는 스펙이 승인되기 전까지 쓰기 게이트가 spec/·docs/·루트 마크다운 밖의 파일 쓰기를 거부한다. 스펙이 코드보다 먼저 존재하고, 태스크의 write_scope가 워커의 실제 쓰기 권한이 된다.
핵심 철학 4개
게이트는 훅이다, 산문이 아니다
UserPromptSubmit·PreToolUse·PostToolUse·Stop 훅이 구조화된 상태를 읽고 판단한다. 모델이 기억해야 하는 지시가 아니다. 훅은 매번 발화한다.
완료는 argv 계약이다
기준은 셸 없이 실행되는 argv 리스트다. &&도 파이프도 리다이렉션도 쓸 수 없다. 단계를 잇고 싶으면 기준을 하나 더 만든다. 항상 통과하는 게이트는 게이트가 없는 것보다 나쁘다. 거짓 증거를 만들기 때문이다.
승인은 해시에 묶인다
gatekit approve spec/05-gate.md는 그 시점 파일의 SHA-256을 기록한다. 파일이 바뀌면 승인은 fail(만료)이 되고, 쓰기 게이트가 다시 닫힌다. 해시를 맞추려고 파일을 되돌리는 것은 금지다.
"검증 안 함"은 통과가 아니다
판정 어휘는 정확히 ok / warn / fail / unverified 네 개다. 시간 초과된 기준, 실행할 수 없었던 단계, 확인하지 못한 산출물은 전부 unverified다. 통과로도 실패로도 반올림하지 않는다. Stop 게이트는 fail뿐 아니라 unverified에서도 세션 종료를 막는다.
다른 도구와 무엇이 다른가
| 관점 | 일반적인 프롬프트·규칙 파일 | gatekit |
|---|---|---|
| 규칙 발화 | 모델의 주의에 의존 | 훅이 매 호출마다 실행 |
| 완료 판정 | 모델의 자기 보고 | argv 실행 결과 |
| 승인 | 대화 중 구두 동의 | 파일 해시 고정 |
| 미검증 상태 | 대개 통과로 처리 | unverified로 별도 유지 |
| 병렬 에이전트 충돌 | 사후 발견 | spawn 게이트가 사전 차단 |
| 평가자 | 만든 세션이 자평 | 별도 read-only 평가자 |
무엇이 아닌가
- gatekit은 코드를 대신 써주는 도구가 아니다. 코드는 워커나 이 세션이 쓰고, gatekit은 그 결과를 판정한다.
- 훅이 세션을 망가뜨리지 않는다. 모든 훅은 내부 오류에서도 exit 0으로 끝나고 진단 한 줄만
.gatekit/runs/hook-errors.log에 남긴다. - 한국어는 기본값이 아니다. 출력 언어는 사용자가 쓴 말에서 감지한다.
첫 30분 — 일단 한 바퀴 돌려보기
개념을 다 읽고 시작할 필요는 없다. 설치(02-install.md)만 끝났으면 아래 순서로 한 바퀴 돌면서 몸으로 익히는 편이 빠르다. 각 단계에서 무엇을 하게 되는지만 알고 들어가면 된다.
1. 만들 것을 정한다 (10~20분, 대화)
/gatekit:discover무엇을 만들지 아직 막연하다면 여기서 시작한다. 정해진 질문 목록이 없는 자유로운 대화가 이어지고, 한 번에 하나씩 묻는다. 과거에 실제로 있었던 일 위주로 답하면 된다("보통 이래요"보다 "지난주에 이랬어요"가 훨씬 쓸모 있다). 대화가 더 나올 게 없어 보이면 계속할지 여기서 정리할지 직접 물어본다.
만들 것이 이미 분명하다면 이 단계는 건너뛰고 바로 다음으로 가도 된다.
/gatekit:interview 한 줄로 만들고 싶은 것여기서는 화면이 몇 개고, 각 화면에서 뭘 할 수 있고, 뭐가 필요한지를 파고든다. 도중에 이 카테고리 제품이 보통 갖추는 기능들을 조사해서 "이런 것도 필요하신가요"라고 제안하는데, 필요 없으면 빼달라고 하면 된다. 결과로 spec/01-prd.md와 spec/03-architecture.md가 나온다.
2. 화면을 직접 눈으로 본다 (10~20분)
/gatekit:mockup디자인 시안이 있으면 그걸 읽고, 없으면 준비된 디자인 프리셋 중에 고르게 한다. 그다음 실제로 클릭되는 HTML 프로토타입을 만들어서 건네준다. 열어보고 마음에 안 드는 곳을 말하면 고쳐서 다시 준다. 여기서 확정하지 않으면 다음 단계로 못 넘어간다 — 빌드가 다 끝난 뒤에 처음 화면을 보는 상황을 막기 위한 장치다.
3. 작업과 완료 조건을 만든다 (5분, 대부분 자동)
/gatekit:tasks
/gatekit:gatetasks가 스펙을 작업 단위로 쪼개고, gate가 "무엇이 충족되면 끝인가"를 실제로 실행 가능한 명령 목록으로 만든다. gate의 마지막에 그 목록을 보여주고 승인을 묻는다 — 여기서 승인해야 비로소 소스 코드를 쓸 수 있게 된다. 목록을 읽고 "이게 다 통과하면 정말 끝인가"를 판단하는 게 이 단계에서 할 일의 전부다.
4. 만들고, 검증한다 (프로젝트 규모에 따라)
/gatekit:build
/gatekit:verifybuild가 작업을 순서대로 구현하고 각 작업의 게이트를 돌린다. 다 끝나면 verify가 코드를 만들지 않은 별도 평가자를 띄워서 완료 조건 전체를 다시 검사한다. 빌드 통과와 완료 계약 통과는 다르고, 최종 판정은 verify가 낸다.
막히면
- 소스 파일 수정이 거부된다 → 아직
/gatekit:gate승인 전이다. 의도된 동작이다. /gatekit:tasks가 거부한다 →/gatekit:mockup에서 프로토타입을 확정하지 않았다.- 그 외 →
10-troubleshooting.md의 증상 표에서 찾는다.
차단은 고장이 아니다. gatekit이 막는 순간은 대부분 "지금 넘어가면 나중에 더 비싸게 되돌려야 하는 지점"이다. 메시지에 무엇이 빠졌는지와 다음에 뭘 하면 되는지가 함께 나온다.