gatebound
Claude Code · Codex 플러그인 · MIT

게이트를 통과해야
완료입니다.

CLAUDE.md의 규칙은 제안일 뿐입니다.
gatebound(게이트바운드)는 그 규칙을 hook으로 바꿉니다.
승인된 spec 없이는 코드를 쓸 수 없고, 실제 명령이 통과하기 전에는 완료라고 할 수 없습니다.

표준 라이브러리 Python, pip install 할 것 없음 · GitHub에서 Star

프롬프트는 제안이고, hook은 규칙입니다.

프롬프트의 지시는 그 턴에 모델이 얼마나 주의를 기울이느냐만큼만 지켜집니다.
gatebound는 중요한 부분을 호스트가 모든 도구 호출과 매 턴 끝에 실행하는 게이트로 옮깁니다.

모델이 건너뛸 수 있는 지시

"테스트부터 써라." "src/를 건드리기 전에 승인을 받아라." "동작하기 전에는 완료라고 하지 마라." 상황이 복잡해지면 어느 것이든 조용히 지켜지지 않을 수 있습니다.

# CLAUDE.md
- 코드보다 spec을 먼저 작성할 것
- 완료라고 하기 전에 테스트를 실행할 것

호스트가 강제하는 게이트

spec 승인 전의 src/ 쓰기는 거부됩니다. 완료했다고 말하는 턴은 먼저 계약을 실행합니다. 실행하지 못한 검사는 그렇다고 알려 줍니다.

PreToolUse · write gate
  gatebound: spec/05-gate.md 승인 전에는
  코드를 쓸 수 없습니다
Stop · stop gate
  gatebound: 완료 계약을 충족하지 못했으므로
  아직 끝난 것이 아닙니다

게이트가 작동하는 모습

Claude Code에서 에이전트에게 로그인 페이지를 만들어 달라고 한 예시입니다.
빨간 줄은 플러그인이 실제로 출력하는 메시지이고, 파일 이름·기준 이름·해시는 예시 프로젝트의 값입니다.

claude — ~/login-demo
› 로그인 페이지 추가해 줘 ● Write(src/login.tsx) ✗ 거부됨 (PreToolUse · write gate) gatebound: spec/05-gate.md 승인 전에는 코드를 쓸 수 없습니다 (현재 상태: unverified). /gatebound:gate 파이프라인을 실행해 사용자 승인을 받거나, 먼저 spec/·docs/·*.md 에 작성하세요. 차단된 경로: src/login.tsx ● 아직 승인된 spec이 없어서 spec부터 작성하겠습니다. /gatebound:interview → /gatebound:tasks → /gatebound:gate › /gatebound:gate (완료 기준을 읽고 승인) ● Bash(gatebound approve spec/05-gate.md) approved spec/05-gate.md 3f9a1c0b7e2d › /gatebound:build ● Write(src/login.tsx) ✓ ● Write(tests/login.spec.ts) ✓ ● 로그인 페이지를 완성했습니다. ✗ 차단됨 (Stop · stop gate) gatebound: 완료 계약을 충족하지 못했으므로 아직 끝난 것이 아닙니다 (기준 3개 중 1개 실패 또는 미검증): - login-e2e: fail (exit 1) 원인을 고친 뒤 계약을 다시 실행하세요. 'unverified' 는 검증하지 않았다는 뜻이며 통과가 아닙니다. ● 빈 비밀번호에서 e2e 테스트가 실패합니다. 입력 검증을 고치겠습니다. ● Edit(src/login.tsx) ✓ ● Bash(gatebound contract run) ok ● 기준 3개를 모두 통과했습니다. 다음은 /gatebound:verify로 독립 검증을 합니다.

hook 메시지는 사용자의 언어를 따릅니다. 한국어로 쓰면 게이트도 한국어로 답하고, 영어로 쓰면 영어로 답합니다. approved …나 ok 같은 CLI 출력은 영어로만 나옵니다. gatebound approve와 gatebound contract run은 플러그인 CLI(python3 …/bin/gatebound.py)를 줄여 쓴 것으로, 명령이 대신 실행해 줍니다.

한 문장에서 검증된 변경까지

모든 단계는 spec/ 아래에 사람이 읽고 커밋하는 Markdown과 JSON을 씁니다.
빌드는 게이트가 승인된 뒤에만 열리고, 만든 에이전트가 스스로 완료를 승인하는 일은 없습니다.

discover정해진 질문 없이, 만들 가치가 있는 문제를 찾습니다.
interview제품 분야를 실시간으로 조사해 PRD와 아키텍처를 씁니다.
mockup · designFigma, URL, 스크린샷, HTML에서 화면과 토큰을 뽑습니다.
tasks쓰기 범위가 겹치지 않는 수직 슬라이스로 나눕니다.
gate실행 가능한 기준을 사용자가 승인하고, 해시가 고정됩니다.
build → verify게이트가 작업마다 판정하고, 독립 평가자가 확인합니다.

게이트가 보장하는 것

작고 기계적인 보장이 모여 믿을 수 있는 빌드가 됩니다.

해시로 고정되는 승인

spec을 승인하면 SHA-256이 기록됩니다. 이후 파일을 고치면 승인이 만료되므로, 다시 검토할 일을 누가 기억할 필요가 없습니다.

실행으로 판정하는 "완료"

완료는 종료 코드 0과 기대한 결과물을 내는 명령 목록으로 정해집니다. 말만으로 완료가 되는 일은 없습니다.

가정 기록부

사용자 대신 추측한 모든 것을 적어 두어, 아무것도 몰래 정해지지 않습니다.

네 가지 판정

실행하지 못한 검사를 통과로 치는 일은 없습니다.

okwarnfailunverified

만든 쪽 ≠ 평가하는 쪽

검증은 별도의 읽기 전용 에이전트가 합니다. 다른 CLI를 쓸 수도 있어서, 모델이 자기 작업을 채점하지 않습니다.

고장 나도 멈추지 않음

게이트 스크립트에 문제가 생기면 "허용하고 기록"으로 물러납니다. 표준 라이브러리 Python만 쓰고 pip install이 필요 없습니다.

빠른 시작

설치부터 검증된 변경까지 네 단계입니다.
설정하지 않은 프로젝트에서는 hook이 아무것도 하지 않으니, 그 프로젝트에서 명령을 실행하기 전까지는 달라지는 것이 없습니다.

1

설치

# 터미널에서 $ curl -fsSL https://claude.ai/install.sh | bash $ claude plugin marketplace add gatebound/gatebound $ claude plugin install gatebound@gatebound

첫 줄은 Claude Code 자체를 설치합니다. claude --version이 이미 된다면 건너뛰세요.
git과 Python 3.9 이상도 필요하며, macOS에서는 xcode-select --install 한 번으로 둘 다 설치됩니다.
설치 후 새 터미널을 여세요. Claude 데스크톱 앱에도 같은 플러그인이 적용됩니다.

macOS · Linux 단계별 설치 안내

Codex를 쓴다면
# 터미널에서 $ codex plugin marketplace add gatebound/gatebound $ codex plugin add gatebound@gatebound

Codex는 사용자가 신뢰한 hook만 실행하므로, 이 단계를 한 번 하기 전까지는 게이트가 하나도 돌지 않습니다. codex를 실행하고(os error 5로 멈추면 codex --no-daemon) /hooks를 입력한 뒤, gatebound hook마다 t를 눌러 신뢰하고 새 세션을 시작하세요. Codex 0.167 이후는 시작할 때 “Hooks need review”를 먼저 물으니, Trust all and continue를 고르면 됩니다. 업데이트할 때마다 다시 해야 합니다. Codex 앱도 이 신뢰를 함께 쓰지만 아직 앱에서는 기록하지 못하니 터미널에서 하세요.

설치 확인

터미널을 열고 프로젝트 폴더로 이동한 뒤(cd my-project) claude를 실행해 로그인하고, 프롬프트에 /gatebound:doctor를 입력하세요(Codex에서는 $gatebound-doctor). 1번과 2번이 ok면 됩니다. 나머지는 spec을 시작하기 전까지 unverified로 남습니다. Claude Code 안에서 입력하고 싶다면 /plugin marketplace add https://github.com/gatebound/gatebound, 이어서 /plugin install gatebound@gatebound도 같은 일을 합니다.

  1. 2

    spec 작성

    내 프로젝트를 열고, 무엇을 만들지 정하는 중이면 /gatebound:discover, 이미 정했으면 /gatebound:interview로 시작합니다. spec/01-prd.md와 spec/03-architecture.md가 만들어지고, 사용자 대신 정한 가정은 모두 기록부에 남습니다.

  2. 3

    게이트 승인

    /gatebound:tasks 다음에 /gatebound:gate를 실행합니다. 완료 기준을 읽고 승인하면 파일의 해시가 고정됩니다. 이때부터 소스 파일을 쓸 수 있고, 나중에 게이트를 고치면 승인이 만료됩니다.

  3. 4

    빌드 후 검증

    /gatebound:build를 실행합니다. 작업마다 게이트가 판정하고, 완료했다고 말하는 턴은 먼저 계약을 실행합니다. 마지막으로 /gatebound:verify에서 별도의 읽기 전용 에이전트가 결과를 확인합니다.

Codex에서는 같은 명령을 스킬로 부릅니다: $gatebound-discover, $gatebound-gate 등. 이상하면 /gatebound:doctor가 설치 상태를 점검하고 문제마다 해결 방법을 알려 줍니다.

Claude Code 또는 Codex유료 플랜의 Claude Code, 또는 Codex 앱이나 CLI.
Python 3.9 이상과 git직접 설치해야 합니다(macOS: xcode-select --install, Windows: 위 설치 스크립트). python3, python, py -3 중 하나로 실행되면 됩니다. pip로 설치할 것은 없습니다.
macOS · Linux · WindowsWindows는 한 줄 설치를 지원하며 미리보기 단계이고, WSL은 Linux처럼 동작합니다.

FAQ

CLAUDE.md나 프롬프트에 적은 규칙과 무엇이 다른가요?

CLAUDE.md의 규칙은 모델이 그 턴에 따를 수도, 안 따를 수도 있는 조언입니다. gatebound는 중요한 규칙을 호스트가 모든 도구 호출과 매 턴 끝에 실행하는 hook으로 바꿉니다. spec이 승인되기 전의 쓰기는 거부되고, 완료했다고 말하는 턴은 먼저 완료 계약을 실행합니다. 모델이 무언가를 기억하지 않아도 규칙이 지켜집니다.

에이전트가 느려지지 않나요?

대부분의 게이트는 파일 경로나 해시를 확인하는 짧은 검사입니다. 무거운 부분은 완료 계약인데, 빌드 중 턴이 끝날 때만 실행됩니다. 기본적으로 최대 120초 동안 기준을 시작하고(stop.budget_s), 나머지는 다음 턴 끝에 실행합니다. 지난 실행 이후 바뀐 파일이 없으면 다시 실행하지 않고 이전 결과를 씁니다.

사용하지 않는 프로젝트에도 영향이 있나요?

없습니다. 플러그인은 전역으로 설치되지만, .gatebound/ 폴더도 gatebound의 spec 파일도 없는 프로젝트에서는 hook이 아무것도 하지 않습니다. 게이트가 동작하지 않고 아무 파일도 쓰지 않습니다. 그 프로젝트에서 명령을 처음 실행할 때부터 적용됩니다.

에이전트가 게이트나 승인을 직접 고칠 수 있나요?

승인 후에 spec/05-gate.md를 고치면 승인이 만료되어, 다시 승인할 때까지 빌드가 멈춥니다. .gatebound/ 안의 승인 기록과 계약은 gatebound의 hook과 CLI만 쓰며, 에이전트가 직접 고치려 하면 거부됩니다. 워커 세션은 어떤 것도 승인할 수 없습니다.

게이트 자체가 고장 나면 어떻게 되나요?

막지 않고 통과시킵니다. 내부 오류가 난 게이트는 동작을 허용하고 .gatebound/runs/hook-errors.log에 한 줄 진단을 남기므로, gatebound의 버그 때문에 세션이 멈추는 일은 없습니다. /gatebound: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와 똑같이 동작합니다.

gatekit을 쓰고 있었나요?

gatebound 0.17.0은 gatekit 0.16.15를 새 이름으로 이어 가는 버전이며, gatekit으로 설정한 프로젝트도 그대로 읽습니다. 플러그인만 바꾸면 하던 작업을 계속할 수 있고, 방법은 gatekit에서 옮겨 오기에 있습니다. 현재 스터디에서 쓰는 gatekit 0.16.x는 github.com/loganmakes/gatekit에서 계속 제공합니다.