게이트를 통과해야
완료입니다.
gatebound(게이트바운드)는 AI 코딩을 게이트로 강제하는 하네스입니다. CLAUDE.md에 적던 규칙을 매번 실제로 실행되는 hook으로 바꿉니다. 코드보다 spec이 먼저이고, 파일이 바뀌면 승인이 만료되며, 완료 여부는 에이전트의 말이 아니라 실제 명령으로 된 완료 계약이 정합니다.
프롬프트는 제안이고, hook은 규칙입니다.
프롬프트의 지시는 그 턴에 모델이 얼마나 주의를 기울이느냐만큼만 지켜집니다. gatebound는 중요한 부분을 호스트가 모든 도구 호출과 매 턴 끝에 실행하는 게이트로 옮깁니다.
모델이 건너뛸 수 있는 지시
"테스트부터 써라." "src/를 건드리기 전에 승인을 받아라." "동작하기 전에는 완료라고 하지 마라." 상황이 복잡해지면 어느 것이든 조용히 지켜지지 않을 수 있습니다.
# CLAUDE.md - 코드보다 spec을 먼저 작성할 것 - 완료라고 하기 전에 테스트를 실행할 것
호스트가 강제하는 게이트
spec 승인 전의 src/ 쓰기는 거부됩니다. 완료했다고 말하는 턴은 먼저 계약을 실행합니다. 실행하지 못한 검사는 그렇다고 알려 줍니다.
PreToolUse · write gate gatekit: spec/05-gate.md 승인 전에는 코드를 쓸 수 없습니다 Stop · stop gate gatekit: 완료 계약을 충족하지 못했으므로 아직 끝난 것이 아닙니다
게이트가 작동하는 모습
Claude Code에서 에이전트에게 로그인 페이지를 만들어 달라고 한 예시입니다. 빨간 줄은 플러그인이 실제로 출력하는 메시지이고, 파일 이름·기준 이름·해시는 예시 프로젝트의 값입니다.
hook 메시지는 사용자의 언어를 따릅니다. 한국어로 쓰면 게이트도 한국어로 답하고, 영어로 쓰면 영어로 답합니다. approved …나 ok 같은 CLI 출력은 영어로만 나옵니다. gatekit approve와 gatekit contract run은 플러그인 CLI(python3 …/bin/gatekit.py)를 줄여 쓴 것으로, 명령이 대신 실행해 줍니다. 이름 변경 후에는 gatebound가 됩니다.
한 문장에서 검증된 변경까지
모든 단계는 spec/ 아래에 사람이 읽고 커밋하는 Markdown과 JSON을 씁니다. 빌드는 게이트가 승인된 뒤에만 열리고, 만든 에이전트가 스스로 완료를 승인하는 일은 없습니다.
게이트가 보장하는 것
작고 기계적인 보장이 모여 믿을 수 있는 빌드가 됩니다.
해시로 고정되는 승인
spec을 승인하면 SHA-256이 기록됩니다. 이후 파일을 고치면 승인이 만료되므로, 다시 검토할 일을 누가 기억할 필요가 없습니다.
실행으로 판정하는 "완료"
완료는 종료 코드 0과 기대한 결과물을 내는 명령 목록으로 정해집니다. 말만으로 완료가 되는 일은 없습니다.
가정 기록부
사용자 대신 추측한 모든 것을 적어 두어, 아무것도 몰래 정해지지 않습니다.
네 가지 판정
실행하지 못한 검사를 통과로 치는 일은 없습니다.
만든 쪽 ≠ 평가하는 쪽
검증은 별도의 읽기 전용 에이전트가 합니다. 다른 CLI를 쓸 수도 있어서, 모델이 자기 작업을 채점하지 않습니다.
고장 나도 멈추지 않음
게이트 스크립트에 문제가 생기면 "허용하고 기록"으로 물러납니다. 표준 라이브러리 Python만 쓰고 pip install이 필요 없습니다.
빠른 시작
설치부터 검증된 변경까지 네 단계입니다. 설정하지 않은 프로젝트에서는 hook이 아무것도 하지 않으니, 그 프로젝트에서 명령을 실행하기 전까지는 달라지는 것이 없습니다.
설치하고 호스트 재시작
- 2
spec 작성
내 프로젝트를 열고, 무엇을 만들지 정하는 중이면
/gatekit:discover, 이미 정했으면/gatekit:interview로 시작합니다.spec/01-prd.md와spec/03-architecture.md가 만들어지고, 사용자 대신 정한 가정은 모두 기록부에 남습니다. - 3
게이트 승인
/gatekit:tasks다음에/gatekit:gate를 실행합니다. 완료 기준을 읽고 승인하면 파일의 해시가 고정됩니다. 이때부터 소스 파일을 쓸 수 있고, 나중에 게이트를 고치면 승인이 만료됩니다. - 4
빌드 후 검증
/gatekit:build를 실행합니다. 작업마다 게이트가 판정하고, 완료했다고 말하는 턴은 먼저 계약을 실행합니다. 마지막으로/gatekit:verify에서 별도의 읽기 전용 에이전트가 결과를 확인합니다.
Codex에서는 같은 명령을 스킬로 부릅니다: $gatekit-discover, $gatekit-gate 등. 이상하면 /gatekit:doctor가 설치 상태를 점검하고 문제마다 해결 방법을 알려 줍니다.
gatekit 이름을 씁니다. 지금 만든 프로젝트도 이후에 그대로 동작합니다. 현재 버전이 이미 두 이름을 모두 읽습니다.python3, python, py -3 중 하나로 실행되면 됩니다. 따로 설치할 것은 없습니다.FAQ
CLAUDE.md나 프롬프트에 적은 규칙과 무엇이 다른가요?
CLAUDE.md의 규칙은 모델이 그 턴에 따를 수도, 안 따를 수도 있는 조언입니다. gatebound는 중요한 규칙을 호스트가 모든 도구 호출과 매 턴 끝에 실행하는 hook으로 바꿉니다. spec이 승인되기 전의 쓰기는 거부되고, 완료했다고 말하는 턴은 먼저 완료 계약을 실행합니다. 모델이 무언가를 기억하지 않아도 규칙이 지켜집니다.
에이전트가 느려지지 않나요?
대부분의 게이트는 파일 경로나 해시를 확인하는 짧은 검사입니다. 무거운 부분은 완료 계약인데, 빌드 중 턴이 끝날 때만 실행됩니다. 기본적으로 최대 120초 동안 기준을 시작하고(stop.budget_s), 나머지는 다음 턴 끝에 실행합니다. 지난 실행 이후 바뀐 파일이 없으면 다시 실행하지 않고 이전 결과를 씁니다.
사용하지 않는 프로젝트에도 영향이 있나요?
없습니다. 플러그인은 전역으로 설치되지만, .gatekit/ 폴더가 없는 프로젝트에서는 hook이 아무것도 하지 않습니다. 게이트가 동작하지 않고 아무 파일도 쓰지 않습니다. 그 프로젝트에서 명령을 처음 실행할 때부터 적용됩니다.
에이전트가 게이트나 승인을 직접 고칠 수 있나요?
승인 후에 spec/05-gate.md를 고치면 승인이 만료되어, 다시 승인할 때까지 빌드가 멈춥니다. .gatekit/ 안의 승인 기록과 계약은 gatebound의 hook과 CLI만 쓰며, 에이전트가 직접 고치려 하면 거부됩니다. 워커 세션은 어떤 것도 승인할 수 없습니다.
게이트 자체가 고장 나면 어떻게 되나요?
막지 않고 통과시킵니다. 내부 오류가 난 게이트는 동작을 허용하고 .gatekit/runs/hook-errors.log에 한 줄 진단을 남기므로, gatebound의 버그 때문에 세션이 멈추는 일은 없습니다. /gatekit:doctor가 설치 상태를 점검하고 문제가 있는 항목마다 해결 방법을 알려 줍니다.
제 코드를 어딘가로 보내나요?
gatebound 자체는 네트워크 요청을 하지 않습니다. 표준 라이브러리만 쓰는 Python이라 pip install할 것이 없고, API 키도 다루지 않습니다. 유일하게 여는 연결은 doctor가 내 컴퓨터(127.0.0.1)의 개발 서버를 확인하는 것뿐입니다. 계약에 넣은 명령과, 워커로 쓰는 claude·codex CLI는 설정한 그대로 동작합니다.
Codex와 Windows에서도 동작하나요?
Codex는 같은 마켓플레이스에서 같은 플러그인을 설치하고, write·shell·stop·prompt 게이트가 그대로 동작합니다. Codex에서는 hook을 한 번 신뢰해 주어야 합니다(codex 실행 후 /hooks). Windows 지원은 미리보기 단계입니다. CI가 Windows에서 돌고, Claude Code는 Git for Windows를 통해 hook을 실행합니다. WSL은 Linux와 똑같이 동작합니다.