지시로 안 되는 결은 코드가 한다 — 공장 라인(gatekit)을 돌려 검수기(final-review)를 뽑은 2주차
2026.10.13
gatekit 6단계로 final-review를 지었습니다 — 251배 사고가 걸립니다
소개
지난주 1주차에서 저는 "코드로 박겠다" 는 선언만 했습니다. Claude에게 중간점 쓰지 말라고 100번 넘게 말해도 사례글 초고에 15건이 들어왔고, LLM 지시가 아니라 결정론 코드로 잡아야 한다는 결론에 도달한 상태였습니다. 구현은 2주차 과제로 미뤄 두었습니다.
이번 주에 그걸 지었습니다. 공장 라인에 해당하는 것이 gatekit — Claude Code 안에서 "아이디어에서 완성까지"를 6단계로 끊어 돌리는 skill 묶음 — 이고, 그 라인으로 뽑은 첫 제품이 final-review — 발행 전 글 검수 skill — 입니다. 저서의 "1,000억 ÷ 40억 = 251배" 사고가 재현되는 샘플을 final-review가 직접 잡아냈습니다.
솔직히 말하면 저는 이 flow를 잘 모른 채로 뚝딱뚝딱 했습니다. Claude가 "/gatekit-interview 돌릴까요?" 하면 네, "이 작업 분해 괜찮으세요?" 하면 네. 그렇게 눌렀더니 결과물이 나왔습니다. 아래 flow 차트는 지금 사례글 쓰면서 Claude에게 "내가 뭘 돌린 거야?" 를 묻고 다시 받아 그린 것입니다. 그래서 결과물은 손에 있는데 앞으로 어디를 어떻게 깎아 나가야 할지는 모릅니다. 그걸 모른다는 것 자체가 이 사례글의 핵심 상태입니다.
이 글은 gatekit의 6단계 각각에서 final-review의 뭐가 어떻게 됐는지, 지금 뭐가 되고 뭐가 안 되는지 를 명령어와 산출물 중심으로 적습니다 — 사후에 복기한 것이지, 미리 알고 돌린 게 아닙니다.
전체 흐름
gatekit 실행 파이프라인 6단계 Claude Code skill 흐름: discover, interview, tasks, gate (사용자 승인과 해시 핀), build, verify. 각 단계의 명령어와 산출물. 1. /gatekit-discover 문제 발굴 → spec/00-discovery.md 2. /gatekit-interview PRD + 아키텍처 → 01-prd.md, 03-architecture.md 3. /gatekit-tasks 작업 분해 (10개, 5라운드) → 04-tasks.md 4. /gatekit-gate · 사용자 승인 05-gate.md → contract.json (SHA256 핀) 5. /gatekit-build 라운드 단위 구현 → src/, tests/ 6. /gatekit-verify 핀된 기준으로 검증 → .gatekit/runs/*.json 기준 바꾸면 해시 깨짐 만든 놈이 검사 못 함
방법은 gatekit, 제품은 final-review. 공장 라인(gatekit)과 그 라인으로 뽑은 첫 제품(final-review)이 다른 층위라는 점을 먼저 분리해둡니다. 아래는 각 단계에서 final-review가 어떻게 자랐는지입니다.
1단계 · /gatekit-discover — 생략
이 단계는 1주차에 이미 끝나 있었습니다. "뭘 만들지 모르겠다" 상황이 아니었고, 1주차 사례글이 그 자체로 발견 산출물 역할을 했습니다 — 중간점 15건이 걸러지지 않는 상황, 저서 251배 사고, 책 집필에서 월 50편 발행까지 반복되는 11가지 사고 패턴.
실제로 돌린 명령은 없고, Claude에게 "1주차 사례글이 00-discovery.md 역할을 한다"고 명시한 뒤 다음 단계로 넘어갔습니다.
2단계 · /gatekit-interview — PRD로 옮기면서 포맷 사고를 심음
/gatekit-interviewClaude가 묻기 시작했습니다. 어떤 글을 검수하는지, 입력 포맷은 뭔지, 블로그는 포함인지, 자동 치환은 어디까지 할지. 이 왕복이 spec/01-prd.md 로 떨어졌습니다. 핵심 결 11가지와 각 결의 수용 기준이 그 안에 있습니다.
이 단계에서 사고가 심어졌습니다. 숫자 포맷 결(①)에 대해 Claude가 "십억원 단위 소수점 한 자리로 통일"을 수용 기준으로 받아 적었고, 저도 confirm 없이 넘겼습니다. 제 메모리(feedback_currency_unit_format)에는 "십억 원" 포맷 금지가 적혀 있는데, PRD 쓰는 Claude 세션이 그 메모리를 쓰면서도 반대로 받아 적었습니다. 이 한 줄이 4단계에서 코드로 박히게 됩니다.
3단계 · /gatekit-tasks — 10개 작업, 5라운드
/gatekit-tasksPRD를 10개의 작업, 5개의 라운드 로 분해했습니다. 각 작업은 "결 하나(또는 묶음)를 입력 → 처리 → Finding 출력까지" 끝까지 도는 수직 슬라이스입니다. 수평 레이어(모델만 만들기, 로더만 만들기)는 안 만들었습니다.
Round 1: t1-scaffold-and-loader (뼈대와 로더)
Round 2: t2-deterministic-rules (중간점, 숫자포맷, 번역체, 맞춤법)
t3-numeric-reverify (숫자 재검증 — 251배 재현)
t4-ocr-gap (OCR 미독해 플래그)
t5-readability-metrics (가독성 지표)
Round 3: t6-citation-check-dart, t7-tone-prompt, t8-stress-test-wrapper
Round 4: t9-guard-and-report (통합 리포트)
Round 5: t10-e2e-skill-wiring (end-to-end)같은 라운드의 작업은 쓰기 범위가 겹치지 않습니다. 겹치면 다음 단계에서 거부됩니다. Round 2의 네 작업은 전부 다른 checks/*.py 와 tests/test_*.py 파일을 씁니다 — subagent에 병렬 위임이 가능한 조건입니다.
4단계 · /gatekit-gate — 완료 기준 승인과 해시 핀
/gatekit-gate작업 10개 각각에 pytest 명령어 를 완료 기준으로 꽂았습니다. 예:
{
"id": "t3-numeric-reverify-tests",
"argv": ["uv", "run", "--project", "src/final-review",
"pytest", "tests/test_numeric_reverify.py", "-v"],
"expect": {"exit": 0, "stdout_not_contains": ["skipped", "SKIP"]},
"timeout_s": 30.0
}제가 "OK 승인" 한 순간, gatekit이 전체 기준을 SHA256으로 해시 떠서 .gatekit/contract.json 에 핀을 박았습니다. 지금 그 해시는 066237c5...52f6ad 입니다. 기준 한 글자만 바뀌어도 이 해시가 깨지고, 다음 단계가 거부됩니다.
이게 "만든 놈이 검사하면 안 된다" 를 코드로 박는 지점입니다. 승인 전까지는 수정 자유, 승인 뒤에는 재승인 없이 수정 불가. 다음 단계 build에서 Claude가 기준을 두 번 완화하려 했는데, 이 핀 때문에 거부당했습니다.
5단계 · /gatekit-build — Round 1~2만 실제로 돌아감
/gatekit-buildRound 1-2를 subagent에 위임해 돌렸습니다. 결과물:
src/final-review/
├── SKILL.md (호출 지시서, 142줄)
├── review.py (오케스트레이터, 결정론 체커 5개 묶음)
├── models.py (Finding dataclass)
├── middle_dot.py (중간점 치환)
├── numeric_format.py (금액 포맷 통일)
├── numeric_reverify.py (배수·비율 재계산)
├── ocr_gap.py (OCR 깨진 영역 플래그)
├── translation_residue.py (번역체 사전 치환)
└── translation_dict.json (번역체 사전)
tests/
├── test_middle_dot.py
├── test_numeric_format.py
├── test_numeric_reverify.py
└── test_ocr_and_translation.py돌아가는 것 세 가지
⑦ 숫자 재검증. demo_numbers_input.md 에 저서 사고를 재현한 라인:
매출 1,000억원과 영업이익 40억원이 있을 때 매출은 영업이익의 251배다.돌린 명령:
python src/final-review/review.py demo_numbers_input.md --json결과 JSON 첫 지적:
{
"rule_id": "numeric-reverify",
"severity": "critical",
"line": 5,
"message": "재계산 불일치: 1,000억원 / 40억원 = 25.0배 (글에는 251배로 기재)"
}"원본 신뢰" 예외 없음이 코드로 박혔습니다.
② 중간점. 1주차 초고에서 뽑은 어긴 라인 15개를 넣은 demo_dirty_input.md 를 돌렸을 때:
전: 중간점 26건
후: 5건 — 전부 "중간점(·)" 처럼 기호 자체를 설명하는 참조. 치환되면 안 되는 것들만 살아남음.
③ OCR 미독해. ░░░░ 가 포함된 라인에 ocr-gap 지적 발생. 매끄럽게 메꾸는 대신 플래그 — "지어내지 않는다" 가 코드 레벨로 박힘.
아쉬운 것 두 가지
(a) 2단계 사고가 그대로 코드가 됐습니다. numeric_format.py 를 돌리니:
제가 지난주 메모리에 명시 금지한 포맷 "100.0십억원" 을 지적으로 생성합니다. PRD 한 줄이 코드가 되는 순간 지시의 가격이 올라갑니다. 2단계로 돌아가서 PRD를 고치고 재 build 해야 합니다.
(b) subagent 라운드가 실제로 안 돌았습니다. Round 2의 t2-t5 네 작업은 병렬 가능 조건을 만족하는데, 세션 교체 등 사정으로 메인 세션이 네 개를 순차 처리 했습니다. gatekit의 가장 큰 장점이 아직 제 손에서 안 돌아본 상태입니다.
(c) Round 3-5가 미완성. 전체 10개 중 Round 1-2의 5개만 구현. DART 공시 대조, 톤/추상도 LLM 프롬프트, editorial-stress-test 호출 래퍼, 치명도 순 통합 리포트, end-to-end wiring 전부 3주차로 넘어갔습니다.
6단계 · /gatekit-verify — 못 돌렸습니다
uv run --project src/final-review pytest tests/ -v
# → error: Failed to spawn: `pytest`
# Caused by: program not foundRound 1 build가 src/final-review/pyproject.toml 을 안 만들었습니다. 그래서 gate에 꽂혀 있는 pytest 명령어가 지금 돌지 않습니다. 완료 기준은 설계됐는데 집행이 안 됩니다. 3주차에 가장 먼저 고칠 지점.
흥미로운 점 — 이것도 4단계 gate가 핀을 박은 contract 덕분에 포착된 결함입니다. 핀이 없었다면 "그냥 통과했다" 고 넘겼을 겁니다.
메타 반전 · 사례글이 자기를 검사했더니
사례글 쓰다가 Claude 가 "이것도 final-review 돌릴까요?" 라고 물었습니다. 메타 그 자체죠. 돌려봤습니다.
python src/final-review/review.py 사례글-초안-2주차.md --json11건 지적 — 전부 false positive 또는 메타 참조.
numeric-reverify2건: "저서의 251배 사고" 라고 설명하는 문구를 저자의 주장으로 오해해 재계산. "1,000억 ÷ 40억 = 251배" 가 bold 안 설명인데 체커는 모름.ocr-gap1건: 글 안의░░░░인라인 코드 예시를 "실제 깨진 OCR"로 플래그.middle-dot7건: 섹션 제목(## 1단계 · /gatekit-discover)의 구분자와 flow 차트 SVG 안 라벨을 "본문 나열"로 지적.translation-residue1건: "레이어" → "층" (이건 진짜. 글이 실제로 "수평 레이어" 라는 번역체 사용 중)
이게 "만든 놈이 검사하면 안 된다"가 메타로 반전된 순간입니다. 검사기(final-review)가 자기 사용 설명서를 설명하는 글을 검사하는데, 설명 예시를 전부 "진짜 틀린 글"로 읽습니다. 거울 보고 "저 사람 중간점 많네" 라고 지적하는 꼴.
흥미로운 지점 — 1주차에 중간점 쪽에만 "참조는 보존" 가드(중간점(·) 같은 메타 참조)를 심었습니다. 그런데 숫자, OCR, 번역체 쪽에는 같은 가드를 복제해 심지 않았습니다. 지시가 코드가 되는 순간 지시의 가격이 올라간다 를 1주차에 선언만 했는데, 그 가격을 2주차 메타 반전 자리에서 체감하게 됩니다.
가드 세 겹을 세 체커에 복제
새 파일 src/final-review/text_guards.py 하나 만들고, 세 체커에 공통 가드를 심었습니다.
def strip_inline_code(line: str) -> str:
"""`...` 안의 내용을 같은 길이 '_' 로 치환.
공백으로 치우면 OCR의 '장시간 공백' 패턴이 치환자에 걸림 — 반드시 non-space."""
return _INLINE_CODE_RE.sub(lambda m: "_" * len(m.group(0)), line)
def is_heading_line(line: str) -> bool:
"""markdown 섹션 제목(# ...)이면 True. 본문 아님."""
return bool(re.match(r"#{1,6}\s", line.lstrip()))세 체커에 각각 끼웠습니다.
numeric_reverify.py: "배" claim 은 단위 명시된(원/달러) 수치만 매칭 대상. 글 안의 "1주차", "15건" 같은 count 가 "251배" 와 교차 매칭되는 걸 차단.middle_dot.py: 섹션 제목 skip + 인라인 SVG 블록 skip + 인라인 코드 마스킹.ocr_gap.py: 인라인 코드 안의 깨진 문자 예시는 "설명"이지 "실제 깨짐"이 아니라 skip.
재실행 결과: 11건 → 1건. 남은 1건은 "레이어" 번역체 — 진짜 지적. 글이 실제로 그 어휘를 쓰고 있어서 유지.
수정 전: 11건 (전부 false positive)
수정 후: 1건 (진짜 번역체 지적)재밌는 자기참조 — 가드를 심은 뒤에도 공백 치환이 OCR 의 "장시간 공백" 패턴에 걸려서 15건 신규 false positive 가 생겼습니다. 공백 대신 _ 로 바꾸고 나서야 정리됐습니다. 가드를 심는 과정 자체가 다시 가드를 요구하는 반복이 짧게 한 바퀴 더 돌았습니다.
배운 점
하나. 2단계 PRD가 가장 위험합니다
build가 수용 기준을 코드로 박는다는 건, PRD에 잘못 적힌 한 줄도 그대로 코드가 된다는 뜻입니다. "십억원 포맷으로 통일" 한 줄이 numeric_format.py 로 들어갔습니다. 지시가 코드가 되는 순간 지시의 가격이 올라갑니다. 다음부터는 /gatekit-interview 산출물을 메모리와 교차 대조하는 단계를 넣어야겠습니다.
둘. 4단계 contract 해시 핀이 생각보다 중요합니다
build 중에 Claude가 "이 기준이 좀 과한데 완화할까요?" 를 두 번 물었습니다. 완화하는 순간 해시가 깨지고 지금까지 통과한 테스트가 전부 unverified 로 떨어집니다. 그래서 완화를 거부했고, 수용 기준 쪽을 유지하면서 구현을 맞췄습니다. 승인된 기준을 바꾸려면 사용자가 다시 승인해야 한다 는 가드가 build 품질을 유지했습니다.
셋. completeness와 correctness는 다릅니다
Round 1-2는 "완료" 지만, 안에서 numeric_format이 제 선호와 반대로 동작합니다. 완료 기준(pytest exit 0)은 통과했는데 실사용 결과는 틀렸습니다. 테스트 통과 ≠ 사용자가 원하는 동작. 3주차에 Round 3 들어가기 전, Round 1-2 실사용 테스트를 돌려 PRD 쪽을 손봅니다.
넷. 가드는 복제해야 작동합니다
1주차에 중간점 쪽에만 "참조 보존" 가드를 심었습니다. 숫자/OCR/번역체에도 같은 가드가 필요하다는 걸 2주차 메타 반전 자리에서야 알았습니다. 지시가 코드가 되는 순간 가격이 올라가고, 그 가격은 같은 수용 기준을 체커 수만큼 복제해 심어야 하는 수고로 나타납니다. 공통 유틸(text_guards.py)로 뽑아 세 곳에 심었습니다. 다음 결(톤, 추상도, 논리)이 추가되면 같은 가드를 또 복제해야 할 겁니다.
결과와 앞으로
이번 주 산출물 (단계 번호로 매달면)
단계 | 산출물 |
|---|---|
1 discover | (생략 — 1주차 사례글이 역할 대신) |
2 interview | spec/01-prd.md, spec/03-architecture.md |
3 tasks | spec/04-tasks.md (10개 작업, 5라운드) |
4 gate | spec/05-gate.md, contract.json 해시 |
5 build | src/final-review/ (체커 5개), tests/ (테스트 4개) |
6 verify | 미완 (pyproject.toml 누락) |
3주차 할 것 — 이게 맞는 순서인지도 아직 모름
사례글 쓰면서 복기해 보니 "할 일" 로 보이는 네 가지가 있는데, 어느 것부터인지, 저 중에 뺄 게 있는지는 모르겠습니다. 일단 적어둡니다.
6단계 못 돌린 걸 먼저 —
pyproject.toml추가해서 /gatekit-verify 돌리기2단계로 돌아가서 — numeric_format 포맷 규칙 PRD 수정 → 재 build
5단계 Round 3를 — subagent 라운드로 실제로 병렬 위임해 보기
Round 5 끝나면 —
~/.claude/skills/final-review/로 복사해 전역 skill 등록
이것도 다음 세션에서 Claude에게 "어디부터 깎을까" 를 묻고 다시 정렬할 생각입니다.
결론 — 결과물은 있고, 다음 손길은 아직 모름
1주차에 "애쓰는 걸로는 안 된다, 코드가 박혀 있어야 한다" 고 적었습니다. 2주차에 그 코드가 어쨌든 지어졌습니다 — 저서 사고가 걸리는 것과 중간점 21건이 지워지는 것을 눈으로 봤습니다. 하지만 그걸 제가 알고 지은 게 아닙니다. Claude가 끌어가는 흐름에 네/네 하면서 따라갔더니 결과가 나왔습니다.
flow 차트는 사후에 그렸고, 각 단계가 무슨 역할이었는지도 사후에 이름이 붙었습니다. 이 사례글이 그 복기 작업입니다. 지금 저는 결과물 앞에 서서 다음 손길의 지점을 못 짚습니다. 2단계 PRD부터 다시 손대야 할지, 6단계 verify를 먼저 돌려야 할지, 아니면 Round 3 subagent 분업을 시도해 볼지 — 각각이 다른 지식을 요구하는 작업인데 그 지식의 지도를 저는 아직 안 갖고 있습니다.
이 상태를 숨기지 않고 적는 게 지피터스 24기 1주차 사례글의 "애쓰는 걸로는 안 된다" 와 결이 같다고 생각합니다. 모르는 걸 모른다고 적고, 다음 주에 Claude와 함께 지도를 그리는 것이 과제가 됩니다.
지시의 가격이 올라갔습니다. 다음 주에 어디부터 깎을지도 Claude와 같이 정합니다.




부엉부엉님, 안녕하세요! 1주차의 "코드로 잡겠다"는 선언이 2주차에 정말 gatekit과 final-review로 지어졌네요.
가장 재밌었던 건 두 군데예요. 하나는 "1,000억 ÷ 40억"이 25.0배로 재계산되어 251배 사고가 잡히는 장면이고, 다른 하나는 사례글 초안을 직접 돌려 11건이 전부 오탐으로 나온 메타 반전이에요. 거기서 text_guards.py로 가드를 모아 1건까지 줄이셨고, 공백 대신
_로 치환해야 OCR 공백 패턴에 안 걸린다는 시행착오까지 적어주셔서 그대로 따라 해볼 수 있겠어요.해시 핀 덕분에 기준 완화를 두 번 거부했고 pyproject.toml 누락도 잡혔다는 부분은, "만든 쪽이 검사하지 않게 한다"는 원칙이 실제로 작동한 사례로 읽혔어요. 3주차 순서를 모르겠다고 솔직히 적으신 것도 좋았습니다. 고롱고롱… 이런 복기 글 보면 기분 좋아져요 ✨