커맨드 레퍼런스

각 커맨드를 언제 쓰는지 / 무슨 일이 벌어지는지 / 무엇이 남는지 / 막히면 어떻게 하는지 순서로 적었다. 전부 /gatekit:<이름> 슬래시 커맨드이며, CLI를 직접 칠 필요는 없다.

gatekit 0.16.14 · docs/manual 767bccc 커밋에서 생성

요약#

/gatekit:discover#

언제 쓰나: 뭘 만들지 아직 막연할 때. "챗봇 같은 거 만들고 싶은데"처럼 만들 물건만 있고 그게 누구의 어떤 불편을 푸는지는 아직 없을 때가 정확히 이 단계다. 선택 단계라서 건너뛰어도 나머지는 그대로 돈다.

무슨 일이 벌어지나: 정해진 질문 목록도, "3/6" 같은 진행률 표시도 없다. 한 번에 하나씩 묻는 자유로운 대화가 이어진다. 과거에 실제 있었던 일을 물으므로("지난번에 그 일 했을 때 실제로 어떻게 하셨어요?") 그대로 답하면 된다 — "보통 이래요"보다 "지난주 화요일에 이랬어요"가 훨씬 쓸모 있다. 해결책을 말하면("검색 기능이 있으면 좋겠어요") 그 기능 없이 지금은 어떻게 하는지 되묻는다.

대화가 더 나올 게 없어 보이면 계속할지 여기서 정리할지 직접 물어본다. 혼자 판단해서 정리로 넘어가지 않는다. "알아서 해줘"라고 하면 그 시점까지 나온 것으로 바로 정리한다.

정리 단계에서는 나온 이야기를 개선과제 몇 개로 요약해서 보여주고, 이게 맞는지 확인받는다. 하나를 고르면 "이걸 직접 만드는 게 맞는지"에 대한 판단(build/reuse/eliminate/unknown)을 제안하고, 사용자가 확정한다.

남는 것: spec/00-discovery.md 하나.

막히면: 확정한 판단이 eliminate(만들 필요 없음)나 reuse(이미 있는 걸 쓰면 됨)면 /gatekit:interview가 막힌다 — 의도된 동작이다. 다른 개선과제를 고르거나, 판단을 바꾼다.

다음: /gatekit:interview. 여기서 고른 개선과제를 다시 묻지 않고 그대로 이어받는다.

/gatekit:interview#

언제 쓰나: 만들 것은 정해졌는데 화면이 몇 개고 각각 뭘 하는지가 아직 없을 때. discover를 거쳤으면 자동으로 이어지고, 안 거쳤으면 /gatekit:interview 만들고 싶은 것 한 줄로 시작한다. 이미 spec/01-prd.md가 있으면 새로 쓰는 게 아니라 고치는 모드로 동작한다.

무슨 일이 벌어지나: 두 단계다.

첫째, 화면·기능·데이터를 파고드는 대화. 화면이 몇 개인지, 각 화면에서 사용자가 뭘 할 수 있는지, 그 기능이 동작하려면 뭐가 있어야 하는지, 그리고 잘 안 풀리는 경우(목록이 비었을 때, 실패했을 때, 두 사람이 동시에 같은 걸 건드릴 때)를 하나씩 묻는다. 질문 개수 제한은 없다.

둘째, 이 카테고리 제품이 보통 갖추는 기능 조사. 대화에서 나온 기능들을 먼저 고정해두고(이게 이 제품만의 차별점이므로 건드리지 않는다), 이 제품이 속한 분야를 웹에서 조사해 대화에서 한 번도 안 나온 표준 기능을 찾아 제안한다. 여러 출처에서 반복 확인된 것은 "기본기 후보", 한 곳에서만 본 것은 "참고 아이디어"로 나눠서 보여준다.

여기서 할 일은 제안을 쳐내는 것이다. "이건 빼주세요", "나중에요", "이건 이렇게 바꿔주세요" 전부 완전한 답이고 이유를 댈 필요 없다. 빈 양식을 채우는 게 아니라 제안된 목록을 다듬는 방식이다.

마지막으로 대화에서 나온 기능과 조사로 추가된 기능을 하나의 목록으로 합쳐 보여주고, 이대로 만들지 최종 확인을 받는다.

남는 것: spec/01-prd.md(문제·목표·기능 목록·수용 기준·가정 원장), spec/03-architecture.md(스택·데이터 모델·제약).

막히면: 확인받지 못한 판단은 spec/01-prd.md의 가정 원장에 번호와 함께 남는다. 그중 핵심 기능의 품질을 좌우하는 것(Blocking: y)이 확인되지 않은 채 남아 있으면 나중에 /gatekit:gate가 진행을 거부한다. 보고에 어떤 가정이 그런지 나오므로, 그때 확인해주면 된다.

다음: /gatekit:mockup.

/gatekit:mockup#

언제 쓰나: 인터뷰가 끝난 뒤, 만들기 전에 화면을 눈으로 확인할 때. UI가 있는 프로젝트라면 사실상 필수다 — 여기서 프로토타입을 확정하지 않으면 /gatekit:tasks가 진행을 거부한다.

무슨 일이 벌어지나: 먼저 디자인 방향을 정한다. Figma 링크·HTML 파일·스크린샷이 있으면 그걸 읽고, 없으면 준비된 디자인 프리셋 몇 개를 보여주고 고르게 한다. 여기서 아무것도 안 고르고 넘어가는 경로는 없다 — 디자인을 안 정한 채 화면을 만들면 결과물이 밋밋해지기 때문이다.

그다음 실제로 클릭되는 HTML 프로토타입을 만들어서 파일 경로로 건네준다. 모든 화면과 모든 상태(정상·비어있음·오류·로딩)가 실제로 눌러서 이동 가능하고, 빈 폼이 아니라 그럴듯한 샘플 데이터로 채워져 완성된 제품 화면처럼 보인다.

열어보고 고칠 곳을 말하면 고쳐서 다시 준다. 이 왕복은 원하는 만큼 반복한다. 확정 직전에 "이 프로토타입이 원하시는 걸 충분히 담고 있나요, 빠진 기능이 있나요"를 따로 묻는다 — 목록으로 볼 때는 안 보이던 누락이 실제 화면을 눌러보면 드러나기 때문이다. 빠졌다고 답하면 /gatekit:interview로 돌아가 그 기능을 제대로 정의한 뒤 프로토타입을 다시 만든다.

남는 것: spec/02-screens.md(화면 목록·흐름·상태), spec/tokens.json(색·간격 등 디자인 값), spec/design/prototype-<이름>.html(확정된 프로토타입). 확정하면 02-screens.md에 프로토타입 확정 <날짜> 줄이 추가된다.

막히면: Figma 연동 도구를 못 쓰는 환경이면 그 사실을 말하고 내보내기 파일이나 스크린샷을 달라고 한 뒤 멈춘다 — URL만 보고 디자인을 추측하지는 않는다. 그리고 목업은 보통 4개 상태를 다 보여주지 않으므로, 빠진 상태는 설계해서 채우되 전부 "가정"으로 표시된다.

다음: /gatekit:tasks.

/gatekit:design#

언제 쓰나: 화면별 목업이 아니라 화면을 가로지르는 규칙("카드는 그림자 없이 테두리만", "위험한 동작은 항상 확인 한 번")이나 참고할 사이트가 있을 때. 선택 단계이고, 파이프라인 어느 시점에서든 실행할 수 있다 — 빌드 도중이어도 된다.

무슨 일이 벌어지나: 주는 것(Figma 링크, 스크린샷, HTML, 라이브 사이트 URL, 프리셋 이름, 직접 쓴 규칙 파일)을 읽어서 디자인 패턴과 토큰을 뽑아낸다. 라이브 사이트는 캡처해서 spec/design/에 저장한 뒤 그 파일을 근거로 삼는다 — URL은 언제든 바뀌므로 저장소 안의 파일만 근거가 된다.

이미 디자인 파일이 있으면 덮어쓰지 않고 합친다. 새 출처가 기존 내용과 충돌해도 기존 행을 지우지 않고 "무엇이 무엇을 대체했는지"를 남긴다.

빌드 도중에 실행하면 작업 파일을 직접 고치지 않고, 영향받는 작업 목록만 알려준다. 실제 반영은 /gatekit:tasks와 /gatekit:gate를 다시 거쳐야 한다.

남는 것: spec/02-design.md, spec/tokens.json(mockup과 공유).

막히면: 웹 접근 도구를 못 쓰는 환경(Codex 등)이면 로컬 캡처를 요청하고 멈춘다. 스크린샷이 1MB를 넘으면 줄이거나 거절한다.

/gatekit:tasks#

언제 쓰나: 스펙이 준비됐고 이제 작업 단위로 쪼갤 때. UI가 있는데 프로토타입을 확정하지 않았으면 여기서 막힌다 — /gatekit:mockup으로 돌아가라는 메시지가 나온다.

무슨 일이 벌어지나: 대부분 자동이다. 기능·화면·스택·실제 저장소 구조를 읽어서 작업 목록을 만든다. 묻는 게 거의 없는 단계다.

작업은 "DB 모델 전부 만들기" 같은 층이 아니라 "폼을 제출하면 저장된 값이 보인다" 같은 세로 조각으로 쪼갠다. 같은 순번(라운드)의 작업끼리는 같은 파일을 건드리지 않게 배치하고, 충돌하면 범위를 넓히는 대신 순번을 나눈다. 화면을 만드는 작업에는 결과 스크린샷을 남기는 조건이 자동으로 붙는다 — 나중에 /gatekit:verify가 그 이미지를 직접 보고 판정한다. 작업의 e2e 게이트는 그 작업의 스펙 파일 하나와 뷰포트 하나만 돌리고(예: Playwright --project mobile), 개발·프로덕션 서버는 한 번 띄워 재사용한다(reuseExistingServer). 실측한 빌드에서 작업 게이트가 두 프로젝트를 모두 돌려 한 바퀴에 약 299초가 들었고, 게이트는 preflight·jobs complete·recheck마다 다시 돈다. 전체 스위트는 05-gate.md의 기준으로 한 번만 돌린다.

남는 것: spec/04-tasks.md.

막히면: 기능 중에 담당 작업이 없는 게 있으면 그 사실을 보고한다. 작업 범위가 겹치면 다시 쪼개지 범위를 넓히지 않는다.

다음: /gatekit:gate.

/gatekit:gate#

언제 쓰나: 작업 목록이 나온 뒤, 만들기 시작하기 직전. 여기서 승인해야 소스 코드를 쓸 수 있게 된다 — 이 파이프라인에서 가장 중요한 한 순간이다.

무슨 일이 벌어지나: 수용 기준과 작업 목록을 읽어서 "무엇이 충족되면 끝인가"를 실제로 실행 가능한 명령 목록으로 만든다. 각 기준은 셸 기교 없이 바로 실행되는 명령 하나이고, 쓰기 전에 실제로 한 번씩 돌려본다 — 돌려보지 않은 기준은 추측일 뿐이고, 나중에 세션을 끝낼 때 진짜로 실행되기 때문이다.

승인을 묻기 전에 기준 전체를 한 번 실행해(contract baseline) 각 기준이 지금 어떤 상태인지 함께 보여준다. 예산만 고친 경우에도 매번 다시 실행하며, 작업 전 트리에서 돌리므로 기준이 만든 파일은 그대로 남는다. 작업 전부터 통과하는 기준은 새 동작을 정말 시험하는지 확인해달라고 표시하고, 명령 자체가 잘못된 기준은 고친 뒤에야 승인을 묻는다.

그다음 그 목록 전체를 표로 보여주고 승인을 묻는다. 여기서 사용자가 할 일은 하나다: "이게 전부 통과하면 정말 끝난 건가?" 아니라고 생각되면 기준을 고치거나 추가해달라고 하면 되고, 반영 후 다시 보여준다.

승인하면 무엇이 바뀌나 — 이게 핵심이라 미리 알아두는 게 좋다.

1. 그 파일의 해시가 고정된다.
2. 소스 파일을 쓸 수 있게 된다 (그전까지는 spec/·docs/·루트 마크다운만 쓸 수 있었다).
3. 세션을 끝내려 할 때 이 명령들이 실제로 실행되고, 하나라도 fail이나 unverified면 종료가 막힌다.
4. 이후 이 파일을 고치면 승인이 자동으로 만료되고, 다시 승인해야 한다.
5. 기준을 채점하는 테스트 파일(argv에 적힌 테스트·스크립트)의 해시도 함께 고정된다. 그 파일이 나중에 바뀌면 해당 기준은 unverified가 되고, 다시 derive만 해서는 풀리지 않는다. 의도한 변경이면 /gatekit:gate를 다시 실행해 재승인하고, 아니면 변경을 되돌린다(ADR-0023). 쓰기는 막지 않는다. 워커는 승인할 수 없다.

남는 것: spec/05-gate.md, 그리고 승인 기록.

막히면: 승인하지 않으면 그대로 두고 "쓰기 게이트가 여전히 닫혀 있다"고 알려준다. 대신 승인해주는 일은 없다. /gatekit:interview의 가정 원장에 확인 안 된 핵심 가정이 남아 있으면 여기서 진행이 거부된다 — 그 가정을 확인해주면 풀린다.

다음: /gatekit:build.

/gatekit:build#

언제 쓰나: 게이트 승인이 끝난 뒤. 실제로 코드가 만들어지는 단계다.

무슨 일이 벌어지나: 작업을 순번대로 구현하고, 각 작업이 끝날 때마다 그 작업의 게이트를 돌려서 통과/실패를 기록한다. 판정은 항상 게이트가 내린다 — 구현한 쪽이 "다 됐습니다"라고 해도 게이트가 실패하면 실패다.

누가 실제로 코드를 쓰는지는 .gatekit/config.json의 build.execution이 정한다. 기본값 host는 이 세션이 직접 구현하고, "execution": "worker"로 바꾸면 작업마다 별도 프로세스를 띄운다. 어느 쪽이든 게이트와 기록은 똑같다. 워커는 같은 모델의 새 세션이라 프로젝트를 매번 처음부터 파악해야 해서, 모델이 실제로 달라야 하거나(적대적 검증) 병렬성이 값을 할 만큼 독립 작업이 많을 때만 쓴다. host에서는 작업을 구현한 뒤 jobs complete <작업id>를 한 번 부르면 그것이 게이트를 돌린다. 그 전에 작업의 게이트 명령을 직접 돌려 보지 않는다 — 실측한 빌드에서 세션이 e2e 게이트를 먼저 돌리고(작업당 24–62초) jobs complete가 같은 게이트를 다시 돌려 시간을 두 번 냈다. 개발 중에 좁은 단위 테스트를 돌리는 것은 괜찮지만 게이트의 전체 명령은 아니다.

작업 시작 전에 게이트를 먼저 한 번 돌린다. 이미 통과하면 아무것도 만들지 않고 넘어가고, 게이트 명령 자체가 잘못됐으면(없는 경로를 가리키는 등) 만들기 시작하지도 않고 그 사실을 알린다 — 잘못된 조건을 향해 몇 분씩 작업하는 걸 막기 위해서다.

진행 상황 보는 법: python3 "${CLAUDE_PLUGIN_ROOT}/bin/gatekit.py" jobs results --compact가 작업당 한 줄로 상태를 보여준다. 워커의 전체 출력 로그는 매우 길어서 읽지 않는 게 좋다.

남는 것: 작업별 상태 기록, spec/PROGRESS.md.

막히면:

• 작업이 실패했다 → 기본 host 모드에서는 이 세션이 코드를 고치고 jobs complete <작업id>를 다시 부른다. 워커를 쓰면 재시도(jobs redelegate <작업id>)하고, 실패한 게이트의 출력이 다음 시도 프롬프트에 자동으로 붙는다.
• 게이트 명령 자체가 틀렸다 → spec/04-tasks.md를 고친 뒤, 재시도 말고 jobs recheck로 고친 게이트만 다시 돌린다. 코드가 이미 맞다면 몇 초 만에 끝난다.
• 같은 작업이 계속 실패한다 → 연속 3회(기본값)에서 자동으로 멈추고 spec/RECOVERY.md에 진단을 남긴다. 이 카운터는 새 작업을 시작해도 리셋되지 않으므로, 원인을 고쳤다면 jobs start --force-retry <작업id>로 그 작업만 초기화한다. 직접 구현하는 기본 모드의 jobs complete도 같은 한도에서 exit 3으로 멈춘다.
• 같은 작업이 똑같이 두 번 실패했다 → 재시도가 남아 있어도 exit 3으로 멈춘다. 게이트 출력(시각·소요 시간 등은 무시)이 같다면 그대로 다시 해도 수렴하지 않으므로, 게이트가 틀렸으면 고친 뒤 jobs recheck, 지시가 틀렸으면 작업을 고친다.
• 작업이 blocked다 → 의존하는 다른 작업이 아직 통과하지 못했다는 뜻이다. 재시도 대상이 아니라 그 의존 작업을 먼저 해결해야 한다.
• 중간에 멈추고 싶다 → jobs stop.

다음: 전부 통과했으면 /gatekit:verify. 빌드 통과와 완료 계약 통과는 다르다.

/gatekit:verify#

언제 쓰나: 모든 작업이 통과한 뒤. 빌드가 다 끝났다고 완료가 아니다 — 최종 판정은 여기서 난다.

무슨 일이 벌어지나: 코드를 만들지 않은 별도의 평가자를 띄운다. 이게 이 단계의 존재 이유다 — 만든 쪽이 자기 결과를 채점하면 통과할 이유를 찾게 되기 때문이다. 평가자는 읽고 실행할 수는 있지만 쓸 수 없고, 가능하면 만든 것과 다른 모델이 맡는다(예: Claude가 만들었으면 Codex가 채점). 다른 모델이 없으면 같은 모델의 읽기 전용 에이전트로 물러나되, 그 사실을 경고로 알려준다.

평가자는 완료 조건을 전부 실행하고, spec/05-gate.md에 적힌 사용자 시나리오도 손으로 직접 따라 한다(서버를 띄우고 실제 요청을 보내는 식). 그다음 이 세션이 완료 조건을 한 번 더 독립적으로 실행한다. 두 결과가 다르면 더 좋은 쪽을 고르지 않고 불일치 자체를 보고한다.

화면을 만드는 작업이 남긴 스크린샷이 있으면, 평가자가 그 이미지를 실제로 눈으로 보고 디자인 방향에 맞는지, 흔한 "AI가 만든 티 나는" 패턴에 빠지지 않았는지 판정한다.

결과 읽는 법: 판정은 ok/warn/fail/unverified 넷이고, unverified는 통과가 아니다. 시간이 모자라 못 돌린 검사, 확인 못 한 산출물이 전부 여기 들어간다. 그리고 코드 검사 집계가 전부 ok여도 스크린샷 판정이 fail이면 "통과했다"고 보고하지 않는다 — 두 가지는 별개로 표시된다.

한 번 실패한 뒤(preflight나 앞선 잡에서의 실패 포함) 자기 게이트가 실행하는 테스트 파일이 바뀌고 나서야 통과한 작업이 빌드의 어느 잡에든 있으면, 판정은 그대로 두되 "자기 테스트가 바뀐 뒤에야 통과했다 — 해당 파일의 diff를 확인하라"는 경고로 따로 보여준다(ADR-0023). 테스트를 느슨하게 고쳐서 통과시켰는지 사람이 확인하라는 뜻이다.

남는 것: spec/PROGRESS.md의 마지막 검증 절에 판정 기록.

막히면:

• 대부분이 unverified로 나온다 → 시간 예산이 실측보다 작을 가능성이 높다. 실제로 몇 초 걸리는지 재본 뒤 05-gate.md에 예산을 선언한다(추측으로 올리지 않는다).
• Codex 평가자가 거부당했다 → 이 프로젝트의 Codex 훅이 아직 신뢰되지 않은 상태다. 메시지에 나온 명령을 한 번 직접 실행해서 승인하면 된다. 쓰기를 감시할 게 없는 상태로 권한을 주지 않으려는 장치다.
• fail이 있다 → 여기서 코드를 고치지 않는다. /gatekit:build로 돌아가 고친다.

/gatekit:doctor#

언제 쓰나: 설치 직후, 훅이 안 먹히는 것 같을 때, 뭔가 이상할 때. 아무 때나 안전하게 실행할 수 있다.

무슨 일이 벌어지나: 8개 항목(플러그인 파일, 훅 등록, 프로젝트 상태, 스펙, 계약 신선도, 워커, 파이썬 버전, Codex 레이어)을 각각 판정하고, 항목마다 복사해서 바로 쓸 수 있는 해결 명령을 함께 보여준다. 아무것도 고치지 않는다 — 진단만 한다.

결과 읽는 법: 종료 코드 0은 "실패한 게 없다"이지 "다 괜찮다"가 아니다. unverified 항목이 있으면 그건 검사를 못 한 것이므로 "이상 없음"으로 읽으면 안 된다. 다만 unverified가 정상인 경우도 많다(아직 그 단계 전이라서). 어느 경우가 정상인지는 02-install.md에 정리돼 있다.

가장 위험한 실패: 2번 항목(훅 등록)의 fail. 파일은 전부 있는데 훅이 하나도 발화하지 않는 상태 — 하네스가 설치된 것처럼 보이면서 아무것도 막지 않는다.

/gatekit:setup#

언제 쓰나: 프로젝트에서 gatekit을 처음 쓸 때 1회. 나중에 Codex를 워커나 평가자로 쓰고 싶을 때 한 번 더.

무슨 일이 벌어지나: .gatekit/config.json이 없으면 기본값으로 만들고, 기본 워커가 실제로 동작하는지 확인한 뒤 결과를 보여준다. 이미 설정 파일이 있으면 건드리지 않는다.

/gatekit:setup codex로 실행하면 Codex를 켜기 전에 무엇이 바뀌는지 먼저 설명한다: 어떤 명령이 실행되는지, 샌드박스가 켜진 채로 도는지, 되돌릴 수 있는지. 답을 받기 전에는 아무것도 바꾸지 않는다.

남는 것: .gatekit/config.json.