스터디 전에 제 검수 장치부터 깨봤습니다 — 리허설 53분이 잡은 결함 3건
2026.10.20

소개
3주차 주제는 검수였습니다. "만든 놈이 검사하면 안 된다"를 4주 중 심장이라고 소개해둔 주차였고, 그 장치는 제가 만든 Claude Code 플러그인 안에 들어 있었습니다.
그래서 스터디 전에 할 일이 분명했습니다. 참가자 앞에서 돌리기 전에, 제가 먼저 깨보는 것.
특히 걸리는 게 있었습니다. 검수 게이트가 시간 지연이나 타이밍에 약할 것이라는 의심이었습니다. 평가자는 백그라운드로 돌고, 테스트 서버는 포트를 잡고, 서브에이전트는 병렬로 움직입니다. 전부 "동시에 일어날 때" 깨지는 구조인데, 단위 테스트로는 그게 안 잡힙니다.
그래서 실제 크기의 앱을 한 번에 끝까지 돌려보기로 했습니다. 16기능짜리 팀 장비 대여 앱을 설계부터 검증까지, 중간에 손대지 않고.
[10/9] 16기능 앱을 끝까지 돌리는 리허설 — 결함 3건 확보
│
↓ ADR-0040 → 0.17.1 배포
│
[10/13] 스터디 당일, WSL에서 네 번째 결함
│
↓ ADR-0015 개정 → 0.17.4 / 0.16.21 배포 + 업데이트 안내
│
[그날] 참가자들이 고친 버전으로 검수 실습결과부터 적겠습니다. 결함 네 건을 찾았고, 전부 고쳐서 배포했고, 그 버전으로 스터디를 했습니다. 리허설을 안 돌렸으면 셋은 참가자 화면에서 터졌을 겁니다.
이 글에 나오는 결함은 전부 수정돼 배포된 것입니다.
0.17.4(gatebound) 또는0.16.21(스터디 기수용 gatekit) 이상이면 해당되지 않습니다.
진행 방법
쓴 도구
도구 | 쓴 이유 |
|---|---|
Claude Code | 설계 · 구현 · 검증 전 과정 |
gatekit (제가 만든 플러그인) | 산문 지침을 실제로 도는 훅으로 바꾸는 용도 |
Codex CLI | 코드를 쓰지 않은 독립 평가자 역할 |
Supabase · Vercel | 데이터와 배포 (무료 범위) |
플러그인이 8단계 파이프라인을 강제합니다. discover → interview → design/mockup → tasks → gate → build → verify. 각 단계가 끝나야 다음이 열립니다. 리허설의 목적은 이 파이프라인을 실제 크기로 한 번 통과시켜 보는 것이었습니다.
① 발굴 — 기능 목록 말고 불편부터
첫 프롬프트는 이것 하나였습니다.
/gatekit:discover
팀에서 공용 장비(카메라, 노트북, 마이크)를 엑셀로 관리하는데
누가 뭘 들고 있는지 실제랑 안 맞아서 찾아 헤매는 일이 반복됩니다.플러그인이 되물어서 "지난 2주 안에 실제로 일어난 일만" 적게 만듭니다. 그 결과입니다.
# | 불편 | 마지막으로 겪은 날 | 빈도 | 1회 소요 |
|---|---|---|---|---|
1 | 엑셀엔 비어 있는데 실제로는 다른 팀원이 들고 나감 | 지난주 (카메라) | 월 2~3회 | 30분 이상 |
2 | 반납일이 지난 걸 아무도 모름 | 지난주 (노트북, 4일 연체) | 월 2회 | — |
3 | 같은 날 같은 장비를 두 사람이 쓰려고 함 | 약 2주 전 (마이크) | 월 1회 | — |
"보통 그렇다"는 못 적게 막습니다. 날짜와 장비 이름이 붙은 사건만 남습니다.
② 완료를 문장이 아니라 명령으로
/gatekit:interview # 역질문 받으며 설계문서 채우기
/gatekit:mockup # 클릭되는 프로토타입으로 눈으로 확인
/gatekit:tasks # 수직 슬라이스 10개로 분해
/gatekit:gate # "완료"를 실행 가능한 명령 목록으로 정의/gate가 핵심입니다.
{"id": "borrow-return-e2e",
"argv": ["npx", "playwright", "test", "e2e/borrow.spec.ts"],
"expect": {"exit": 0, "stdout_not_contains": ["skipped", "SKIP"]},
"timeout_s": 60}stdout_not_contains가 중요합니다. 테스트 러너는 전부 건너뛰어도 exit 0을 냅니다. 그걸 통과로 치지 않으려고 박아둔 겁니다.
승인하면 그 파일의 SHA-256이 박힙니다. 문서를 한 글자라도 고치면 승인이 자동으로 무효가 됩니다.
③ 리허설 — 16기능을 한 번에
/gatekit:build작업 10개를 라운드로 나눠 돌렸습니다. 기계 시간 53분, 완료 계약 6/6 ok. 앱은 제대로 나왔습니다.


여기서부터가 리허설을 돌린 이유입니다. 앱이 나왔다고 끝이 아니라, 그 과정에서 게이트가 제대로 돌았는지를 로그로 되짚었습니다. 셋이 걸렸고, 전부 의심했던 자리 — 타이밍이었습니다.
① 끝난 서브에이전트가 자리를 비켜주지 않았습니다.
스폰 게이트는 서브에이전트마다 쓰기 범위(write_scope)를 장부에 적고 겹치는 위임을 거부합니다. 같은 파일을 둘이 동시에 고치는 걸 막는 장치인데, 장부에서 지우는 코드가 없었습니다.
라운드 2에서 넷을 병렬로 돌렸고 넷 다 끝났습니다. 라운드 3에서 다시 위임하려니 겹친다고 전부 거부. 끝난 에이전트의 범위가 계속 활성으로 남아 있었던 겁니다. 그래서 라운드 3·4·5는 호스트 세션이 혼자 지었습니다.
실측 기록(spec/PROGRESS.md)에 이렇게 남겼습니다.
라운드 3 하위 에이전트 위임 → 거부. gatekit 훅이 끝난 라운드 2 에이전트의 쓰기 범위를 계속 활성으로 보고 겹침으로 막음. (이번엔 직접 구현)
에러도 안 났고, 판정도 ok였고, 앱도 동작했습니다. 위임만 조용히 사라졌습니다. 참가자가 이걸 만났으면 "왜 병렬이 안 되지?"로 한 시간을 썼을 겁니다.
0.17.1에서 수정. 에이전트가 끝나거나 실패하거나 중단되면, 또 백그라운드 에이전트가 멈추면 장부에서 범위를 반납합니다. 지금은 라운드가 넘어가도 병렬 위임이 유지됩니다.
② 평가자가 돌고 있는데 Stop 게이트가 같이 채점했습니다.
/verify는 코드를 쓰지 않은 별도 평가자를 백그라운드로 띄우고 턴을 끝냅니다. 그 순간 Stop 게이트가 즉시 계약을 돌렸고, 평가자도 자기 검사를 시작했습니다. 둘이 테스트 서버 포트에서 부딪혀 E2E가 unverified (러너를 시작할 수 없음)로 나왔습니다.
계약 실행끼리는 이미 락으로 직렬화해뒀는데, 평가자가 직접 실행하는 명령은 어떤 락도 보지 못합니다. 의심했던 시간 지연 문제가 정확히 여기서 나왔습니다.
0.17.1에서 수정. 평가자가 백그라운드에서 도는 동안 Stop 게이트는 판정을 미루고, 평가자가 끝난 뒤 첫 Stop이 정상 채점합니다.
③ 토큰 게이트가 제가 같이 배포한 프리셋을 못 읽었습니다.
shadcn-neutral 프리셋은 색을 "primary": "0 0% 9%" 같은 맨 HSL 삼중항으로 저장하고 CSS에서 hsl(var(--primary))로 씁니다. 게이트는 색 토큰을 0개 찾았고, 그래서 /tasks가 모든 태스크에서 토큰 게이트를 빼버렸습니다.
이건 특히 아찔했습니다. 스터디에서 쓰라고 제가 같이 배포한 프리셋이라, 참가자 대부분이 이걸 골랐을 테니까요.
0.17.1에서 수정. 맨 HSL 삼중항을 색으로 읽고, 콤마·공백·슬래시 표기를 같은 값으로 비교합니다.
shadcn-neutral을 쓰는 프로젝트에 토큰 게이트가 다시 붙습니다.
셋 다 단위 테스트로는 영원히 안 잡히는 종류입니다. 테스트는 통과하고 앱도 돕니다. 사라진 건 위임과 검사 그 자체입니다. 실제 크기로 한 번 돌려봐야만 보이는 것들이었습니다.
→ 세 건을 ADR-0040으로 쓰고 0.17.1로 배포했습니다.
④ 스터디 당일 — 네 번째 결함
10월 13일, 스터디에서 참가자들이 /gatekit:verify를 돌렸습니다. 한 분의 WSL에서 완료 기준 4개 실패, E2E는 한 단계도 실행 못 함. 전부 listen EPERM.
같은 커밋을 제 맥에서 돌리면 전 기준 통과였습니다.
원인은 샌드박스였습니다. jobs evaluate는 Codex를 --sandbox workspace-write로 띄우는데, 이 샌드박스의 기본값이 네트워크 차단이고 거기에 localhost 포트 바인딩까지 포함됩니다. E2E는 테스트 서버를 띄워야 하니 전멸입니다.
그 자리에서 재현하고, 고치고, 배포했습니다. 평가자 실행에만 한 줄입니다.
-c sandbox_workspace_write.network_access=true읽기 전용 평가자와 빌드 워커는 그대로 뒀습니다. 전부 열면 간단했지만, 네트워크가 꼭 필요한 건 앱을 띄워 눌러봐야 하는 실행 경로 하나뿐이었습니다.
0.17.4와 0.16.21(스터디 기수용)에 동시에 올리고, 그 자리에서 업데이트 방법까지 안내했습니다. 참가자들은 고친 버전으로 그날 실습을 이어갔습니다.
2주차에 개명하면서 기수용 버전을 일부러 동결해둔 게 여기서 값을 했습니다. 스터디 중간에 설치 경로가 바뀌면 참가자가 깨지니까 0.16.x를 따로 유지했는데, 덕분에 수정을 참가자가 실제 쓰는 라인에 그대로 내려보낼 수 있었습니다.
참고로 1주차에 같은 파이프라인으로 만든 스터디 결과물 갤러리입니다. 기준 26/26 ok를 받았습니다.


결과와 배운 점
리허설이 잡아낸 것 — 네 건
게이트가 말한 것 | 실제 | 고친 버전 |
|---|---|---|
16기능 53분 · 판정 ok | 라운드 3~5는 위임이 안 되고 있었다 | 0.17.1 |
E2E가 | 평가자와 자동 판정이 포트에서 충돌 | 0.17.1 |
토큰 게이트가 깨끗함 | 그 프리셋에서 게이트가 빠져 있었다 | 0.17.1 |
내 환경 전 기준 통과 | 샌드박스가 localhost를 막고 있었다 | 0.17.4 / 0.16.21 |
앞의 셋은 리허설에서 미리 잡았고, 넷째는 스터디 당일에 잡아 그날 고쳤습니다. 네 건 다 "통과"라는 출력이 통과를 뜻하지 않았던 경우입니다.
그리고 네 건 다 시간이 얽힌 자리에서 나왔습니다. 병렬로 돌 때, 백그라운드가 겹칠 때, 포트를 동시에 잡을 때. 리허설을 돌리기 전에 의심했던 바로 그 지점입니다. 의심한 곳을 실제 크기로 때려보면 나온다는 게 이번에 확인한 방법론입니다.
나만의 꿀팁 네 가지
① 남 앞에서 돌리기 전에 실제 크기로 한 번 돌려보세요. 이번 결함 셋은 전부 단위 테스트를 다 통과한 상태에서 나왔습니다. 작은 예제로는 안 나옵니다. 병렬·백그라운드·포트가 동시에 얽혀야 나오는 종류라, 16기능짜리를 끝까지 한 번 돌리는 데 쓴 53분이 제일 수익률 높은 시간이었습니다.
② 테스트 러너는 다 건너뛰어도 exit 0을 냅니다. 완료 기준에 stdout_not_contains: ["skipped", "SKIP"]를 꼭 박으세요. 이거 하나로 "테스트 통과"라는 거짓말이 많이 줄어듭니다.
③ 승인에 해시를 박으세요. 완료 기준 문서의 SHA-256을 승인 시점에 고정해두면, 나중에 기준을 슬쩍 고쳐 통과시키는 길이 막힙니다. 자기 자신에게도요.
④ 검증은 만든 세션이 아닌 곳에서 돌리세요. 같은 세션에 "검사해줘" 하면 대부분 통과가 나옵니다. 자기가 만든 걸 보니까요. 실력이 아니라 구조로 막아야 합니다.
시행착오
제일 뼈아픈 건 스코프 반납 문제를 9월 13일에 한 번 보고 백로그에 묻은 것입니다. 한 달 뒤 리허설에서 라운드 3·4·5가 그것 때문에 단일 세션 작업이 됐습니다.
"일단 넘어가고 나중에"가 측정값을 오염시키는 방식으로 돌아왔습니다. 53분은 거짓이 아니지만, 병렬 위임이 거의 안 들어간 53분입니다. 다행히 이걸 스터디가 아니라 리허설에서 알게 됐습니다.
그 외 실제로 걸린 것들입니다.
겪은 일 | 원인 | 다음에 안 할 것 |
|---|---|---|
게이트가 파일 0개 검사 | Python glob이 | 대괄호 경로는 이스케이프 |
작성자 이름 읽기 실패 | 뷰가 두 번째 경로가 되어 관계 모호(PGRST201) | 임베드마다 외래 키 이름 명시 |
E2E 60초 초과 | 게이트 제한 60초, 스펙이 54초 | 로그인·업로드 재사용해 43초로 |
여정 테스트 strict 위반 |
| 앱을 테스트에 맞춰 비틀지 않기 |
반응 버튼 1/80 실패 | 저장 중이면 다른 종류 클릭을 조용히 무시 | 저장 상태를 종류별로 분리 |
네 번째가 특히 기억에 남습니다. 앱을 고치면 쉽게 풀렸지만, 그러면 테스트에 맞춰 제품을 비트는 것이라 테스트 쪽 한 줄만 고쳤습니다.
숫자 (전건 실측)
리허설 | 16기능 · 작업 10개 · 기계 시간 53분 · 계약 6/6 |
리허설이 잡은 결함 | 3건 — 전부 스터디 전에 배포 완료 |
스터디 당일 잡은 결함 | 1건 — 그날 배포하고 업데이트 안내까지 |
리허설에서 기록한 실패 시도 | 7건 (원인 · 재발방지까지) |
그 결과 나온 릴리스 | 0.17.1 ~ 0.17.4 · 0.16.17 ~ 0.16.21 |
수정 배포 라인 | 2개 동시 (gatebound / 스터디 기수용) |
플러그인 자체 테스트 | 2,043개 통과 (gatebound, 8 skip, 72.0초) · 1,846개 통과 (기수용 0.16.x, 1 skip, 66.8초) |
갤러리 프로젝트 | 작업 10/10 · 기준 26/26 |
추정과 실측을 구분합니다 — 위 표는 전부 명령 출력이나 릴리스 노트에서 그대로 옮긴 값입니다. 단 "53분"은 기계 시간이고, 제가 화면을 보며 판단한 시간은 재지 않았습니다.
아직 안 된 것 — 정직한 목록
구조적으로 못 잡는 것
Stop 지연은 고치면서 새로 생긴 구멍입니다. 백그라운드 에이전트가 돌고 있으면 Stop이 판정 없이 끝나니, 아무 일도 안 하는 에이전트를 띄워 판정을 미루는 게 원리적으로 가능합니다. 경계는 이렇게 뒀습니다 — 스폰 게이트를 반드시 거치고, 연속 3회까지, 에이전트가 끝나면 바로 다음 Stop이 채점하고, 그동안 기존 판정은 덮어쓰지 않습니다. 그래서 판정을 미룰 수는 있어도 실패를 통과로 바꾸지는 못합니다. 미루기와 뒤집기 사이에 선을 그은 것이고, 그 선 안쪽이 열려 있다는 걸 ADR-0040에 적어뒀습니다.
설계상 일부러 그렇게 둔 것
tool_use_id없이 기록된 범위는 반납되지 않습니다. 구버전 장부나 그 값을 안 보내는 호스트에서 생깁니다. 양쪽 비용을 재보고 고른 쪽입니다 — 헛충돌은 범위를 한 번 다시 선언하면 끝이고, 놓친 충돌은 두 에이전트가 같은 파일을 덮어씁니다. 싼 실패 쪽으로 기울였습니다.읽기 전용 평가자와 빌드 워커에는 네트워크를 열지 않았습니다. WSL 건을 고칠 때 전부 열면 간단했지만, 꼭 필요한 건 실행 경로 하나뿐이었습니다.
표본이 부족한 것
리허설 1회, 앱 1개, 호스트 2종. 53분은 이 1건의 기록이고, 게다가 위임이 죽어 있던 상태의 숫자라 지금 다시 재면 다른 값이 나옵니다.
WSL 실패 보고 1건, 1명. 샌드박스 기본값이 원인이라 환경을 타지 않을 것으로 보지만, 그건 제 추정이고 측정이 아닙니다.
아직 안 닫힌 것
비대면 전달은 아직 증명 못 했습니다. 이번 수정이 사람에게 닿은 건 제가 그 자리에 있었기 때문입니다. Discussions 한국어 보드는 열어뒀지만 댓글 0개, 이슈 0건이라, 스터디 밖의 누군가가 막혔을 때 저를 찾아오는 길은 아직 열려만 있고 쓰이진 않았습니다. 다음 질문은 "제가 없을 때도 닿는가"입니다.
도움이 필요한 부분
WSL에서 Codex 평가자를 돌려보신 분 —
listen EPERM이 0.16.21 이후로 안 나는지 알려주시면 표본이 1명에서 늘어납니다. 환경 탓인지 설정 탓인지가 여기서 갈립니다.Stop 지연 악용 시나리오 — 아무 일도 안 하는 백그라운드 에이전트로 판정을 미루는 걸 제가 못 막고 있습니다. 더 좋은 경계 조건 아이디어를 구합니다.
앞으로의 계획
순위 | 할 것 | 왜 |
|---|---|---|
1 | 병렬 위임 재측정 | 53분은 위임이 죽어 있던 상태의 숫자 — 고친 뒤 값을 모름 |
2 | 릴리스 노트만으로 업데이트가 되는지 보기 | 대면 없이도 수정이 닿는지가 다음 질문 |
3 | Stop 지연 악용 경로 직접 찔러보기 | 고치면서 생긴 구멍은 내가 먼저 |
4 | 다음 기수 전에 리허설 한 번 더 | 이번에 가장 값이 좋았던 투자 |
마무리
3주차에 "만든 놈이 검사하면 안 된다"를 가르치기로 해놓고, 제 검사 장치부터 의심했습니다. 특히 시간이 얽히는 자리 — 병렬, 백그라운드, 포트 — 가 약할 거라고 봤고, 확인하려면 실제 크기로 한 번 돌려보는 수밖에 없었습니다.
그래서 16기능을 끝까지 돌렸고, 의심한 자리에서 정확히 세 건이 나왔습니다. 고쳐서 배포하고 스터디에 들어갔습니다. 당일에 한 건이 더 나왔고, 그것도 그 자리에서 고쳐 배포하고 업데이트 방법까지 안내했습니다. 참가자들은 고친 버전으로 실습했습니다.
리허설을 안 돌렸으면 셋은 참가자 화면에서 터졌을 겁니다. 그것도 "왜 병렬이 안 되지", "왜 검증이 unverified지" 같은, 원인을 찾는 데만 한 시간씩 걸리는 모양으로요.
남는 건 이겁니다. 장치가 ok를 내는 건 통과를 뜻하지 않고, "장치가 돌았다"조차 뜻하지 않습니다. 그걸 알아내는 방법은 결국 의심한 자리를 실제 크기로 때려보는 것이었고, 그 53분이 이번 스터디에서 제일 수익률 높은 시간이었습니다.
결함 네 건은 ADR로 남기고 전부 공개했습니다. 다음에 같은 걸 또 묻어두지 않으려는 제 장치이기도 합니다. 9월 13일에 한 번 묻었다가 한 달 뒤에 값을 치렀으니까요.
도움 받은 글
ADR-0040 — 끝난 서브에이전트는 범위를 반납하고, 도는 중이면 Stop을 미룬다
ADR-0015 개정 A — Codex 평가자는 localhost 포트를 열 수 있다
gatebound 0.17.1 ~ 0.17.4 릴리스 노트
spec/PROGRESS.md— 실패한 시도 7건(트라이얼) / 5건(갤러리)


로미오님, 안녕하세요. "검수를 가르치기 전에 내 검수 장치부터 깨본다"는 접근이 인상 깊었어요. 특히 시간·병렬·포트가 얽히는 자리가 약할 거라고 미리 의심하고, 16기능 앱을 53분 동안 끝까지 돌려서 정확히 그 자리에서 세 건이 나왔다는 흐름이 설득력 있었습니다.
"에러도 안 났고 판정도 ok였고 앱도 동작했는데 위임만 조용히 사라졌다"는 부분이 특히 와닿았어요. ok가 곧 장치가 돌았다는 뜻은 아니라는 결론과, 결함 네 건을 ADR로 남겨 공개하신 마무리도 좋았습니다.
털 한 번 곤두섰다가 마지막엔 고롱고롱했어요 ✨