아프니까 개발자다

/plan-* 3종 — 한 PLAN 문서를 세 시선으로 통과시키기 (gstack 시리즈 3/6)

타이젠 개발자, 윤진 — Tue, 19 May 2026 23:00:57 +0900

시리즈 2편에서 /office-hours로 컨셉의 모서리를 깎았다. 이번 글은 그 정제된 컨셉을 PLAN으로 옮길 때 한 머리가 아닌 세 시선을 통과시키는 자리, /plan-ceo-review·/plan-eng-review·/plan-design-review 3종이 car-game의 PLAN v1을 v2로 만들어 낸 과정을 다룬다.

왜 이런 스킬이 필요했나

PLAN을 한 사람이 짜면 그 사람의 사각지대가 PLAN에 그대로 박힌다. car-game의 PLAN v1은 엔지니어 머리로 짠 plan이었다 — 모듈을 어떻게 나눌지, 어떤 자료구조를 쓸지에는 답이 있었지만, "이 plan대로 가면 1주일 안에 끝나나?", "사용자가 Lv1과 Lv10을 같은 게임으로 느끼나?" 같은 질문에는 답이 없었다.

문제는 한 사람이 자기 사각지대를 자기 머리로 메우려 해도 한계가 있다는 점이다. 시선 자체가 다른 사람을 데려와야 사각지대가 줄어든다. 그런데 매 PLAN마다 CEO와 디자이너를 모셔올 수는 없다. /plan-* 3종은 이 어려움을 푸는 게이트다.

무엇을 하는 스킬인가

/plan-* 3종은 한 PLAN 문서를 받아 세 가지 다른 역할로 동시에 검토한다. 각 역할은 PLAN의 다른 차원을 본다:

/plan-ceo-review — 범위·우선순위·일정. "이 약속이 너무 큰가? MVP는 어디서 자르나? 60% 진척에서도 publish 가능한가?"
/plan-eng-review — 아키텍처·확장성·기술 부채. "이 구조가 나중에 N번 더 추가될 때 회귀 위험이 어떻게 되나? 패턴은 정착되어 있나?"
/plan-design-review — 사용자 경험·진척감·일관성. "사용자가 진척을 느끼나? 처음과 끝의 톤이 다른가? 한 화면에 너무 많은 정보가 있지 않나?"

세 리뷰는 같은 PLAN 문서에 대해 완전히 다른 종류의 결함을 잡아낸다. 한 시선으로는 보이지 않는 게 다른 시선에는 명백히 보인다.

그림 설명: 가운데 노란 박스는 한 머리로 짠 PLAN v1이다. 세 시선이 PLAN을 둘러싸고 각자 다른 차원에서 결함을 가리킨다. 좌상의 CEO는 무엇을 자를까(범위·우선순위)를 묻고, 우상의 ENG는 어떻게 구조화할까(아키텍처)를 묻고, 하단의 DESIGN은 사용자가 무엇을 느낄까(경험)를 묻는다. 한 사람이 세 차원을 동시에 보는 것은 어렵지만, 세 시선을 따로 통과시키면 빠지는 부분이 적어진다.

car-game에서 이 스킬이 한 일

세 리뷰가 PLAN v1에서 잡은 결함과, 그것이 PLAN v2 + CHECKLIST v2에 어떻게 반영됐는지:

CEO 시선이 잡은 것

"Lv1~10 전부를 1주일 안에? 너무 큰 약속. MVP는 Lv1~3로 자르고, Lv4~10은 stretch goal로. 60% 진척에서도 publish 가능한 단위로 잘라라."

PLAN v1은 마일스톤이 한 덩어리(Lv1~10)였다. CEO 리뷰 후 마일스톤은 MVP(Lv1~3) + Stretch(Lv4~10) 두 단위로 쪼개졌고, MVP가 60% 진척 시점에서 publish 가능한 형태로 다시 설계됐다. 이는 CHECKLIST v2의 P1·P2 마일스톤 분리로 직접 반영됐다.

ENG 시선이 잡은 것

"spawner.js에 모든 장애물 타입을 한 함수로 박지 마라. priority chain 패턴으로 분리하라. 나중에 장애물 종류가 추가될 때마다 회귀 위험이 누적된다."

PLAN v1은 spawner를 단일 함수로 두었다. ENG 리뷰 후 spawner는 priority chain 패턴(pedestrian → parked → fixed → driving → oncoming, 각 단계마다 rate curve)으로 분리됐다. 이 결정 덕분에 이후 장애물 종류 11가지가 추가되는 동안 회귀가 거의 발생하지 않았다.

DESIGN 시선이 잡은 것

"Lv1과 Lv10의 도로색이 같으면 진척감이 안 느껴진다. 톤 변화 4단계(낮 → 오후 → 황혼 → 밤)를 도입하라."

PLAN v1은 도로색을 단일 #444로 두었다. DESIGN 리뷰 후 ROAD_TIERS 4단계 톤 시스템이 도입됐고, 레벨별 smoothstep 보간으로 점진적 변화를 주는 설계가 됐다. 이는 사용자가 "내가 진행하고 있다"는 감각을 시각으로 받게 만드는 핵심 기여다.

그림 설명: PLAN v1 → v2의 변화를 차원별로 정리한 표다. 같은 PLAN 문서의 세 차원(범위·아키텍처·UX)에서 각각 다른 시선이 다른 결함을 잡았다. 한 시선으로 다 잡으려 했다면 어느 한 차원은 비어 있는 채로 코드까지 흘러갔을 것이다. 표 아래 노란 박스는 세 리뷰의 결론이 합쳐져 도출된 PLAN v2 + CHECKLIST v2(U1~U29 항목)를 표시한다. CHECKLIST는 "이 세 시선이 잡은 것을 잊지 않는다"는 약속을 코드 레벨에서 추적하는 장치다.

핵심 메시지

PLAN을 한 머리로 짜지 말라. 세 시선이 각자 다른 차원을 본다. car-game에서 /plan-* 3종은 (1) MVP 마일스톤 분리(CEO), (2) spawner priority chain 패턴(ENG), (3) ROAD_TIERS 4단 톤 시스템(DESIGN) — 세 가지 결정적 변경을 PLAN v2에 박았다. 셋 중 하나라도 빠졌다면 1주일 안에 publish는 불가능했거나, 장애물 추가 시마다 회귀가 누적됐거나, 사용자가 진척감을 못 느꼈을 것이다.

다음 글은 이렇게 만든 PLAN을 들고 실제 구현 사이클로 들어간다. 첫 번째 게이트는 /review — 테스트가 못 보는 의미 부패를 청소하는 자리다.

이 글은 생성형 AI의 도움을 받아 작성되었습니다. 원본 자료를 기반으로 AI가 초안을 생성하고, 작성자가 검토·편집하였습니다.

/office-hours — 막연한 컨셉을 plan으로 갈 수 있게 깎는 자리 (gstack 시리즈 2/6)

타이젠 개발자, 윤진 — Tue, 19 May 2026 22:00:04 +0900

시리즈 1편에서 ralph-loop 위에 gstack 게이트를 얹는 흐름을 소개했다. 이번 글은 그 흐름의 가장 앞단, 기획 단계에 놓이는 /office-hours가 car-game 프로젝트에 어떤 기여를 했는지를 다룬다.

왜 이런 스킬이 필요했나

LLM에게 "장애물 피하는 자동차 게임 만들어줘" 한 줄을 던지면 결과는 두 가지 중 하나다.

그럴듯한데 내가 원하던 게 아닌 무언가
너무 일반적이라 어디서부터 손대야 할지 모를 무언가

문제는 입력이 막연하면 LLM이 빈 부분을 자기 마음대로 채운다는 점이다. 그 자기 마음대로 채워진 결정들이 코드 베이스 곳곳에 박힌 상태로 며칠 지나면 — 사용자가 만들고 싶었던 게임과 코드가 만들어 놓은 게임이 다른 게임이 된다. ralph-loop이 빠르게 코드를 늘릴수록 이 격차는 더 빨리 벌어진다.

/office-hours는 그 격차가 벌어지기 이전 단계에 놓이는 게이트다.

무엇을 하는 스킬인가

/office-hours는 막연한 컨셉을 받자마자 컨셉의 모서리를 묻는 질문을 던진다. 모든 컨셉은 다음 네 차원에서 잘리지 않으면 plan으로 옮길 수 없다:

핵심 동사: 사용자가 화면에서 무엇을 하는가? (피하기? 추월? 달리기? 모으기?)
진행 방식: 한 세션이 어떻게 끝나는가? (레벨제? 무한주행? 시간제? 점수제?)
실패·성공 조건: 무엇이 게임 오버이고 무엇이 클리어인가?
타깃 사용자: 누가 이 게임을 켜고 5분을 보낼 것인가?

각 차원의 질문에 사용자가 답하면, 컨셉의 한 모서리가 깎인다. 네 모서리가 다 깎이면 plan으로 가져갈 수 있는 형태가 된다.

그림 설명: 가운데 노란 원이 처음 들어온 막연한 컨셉이다. /office-hours는 네 방향(상·우·하·좌)에서 각자 다른 차원의 질문(파란 화살표)을 던진다. 각 질문이 들어올 때 사용자는 결정 하나를 내려야 하고, 결정 하나가 컨셉의 한 모서리를 깎는다. 네 결정이 모두 내려지면 컨셉은 모서리가 잘려 plan에 들어갈 수 있는 형태가 된다.

car-game에서 이 스킬이 한 일

처음 사용자가 가지고 온 컨셉은 "장애물 피하는 자동차 게임" 한 줄이었다. /office-hours가 30분 동안 네 차원의 질문을 던지며 컨셉을 깎았다:

핵심 동사: "피하기"로 결정. 차로 변경(좌·우)이 유일한 액션 수단.
진행 방식: 레벨제. Lv1~10. 각 레벨은 60초로 끝남. 무한주행 아님.
실패·성공 조건: 충돌 즉시 게임오버. 60초 생존 시 다음 레벨로.
타깃 사용자: 5분 단위 캐주얼 플레이. 하드코어 매니아용 아님.

30분 뒤 컨셉은 한 문단으로 정리됐다 — "10단계 레벨 기반의 종방향 스크롤 자동차 게임. 4차로 도로에서 좌우 차로 변경으로 장애물을 피한다. 각 레벨은 60초로 끝나며, 충돌하면 즉시 게임오버."

이 한 문단이 다음 글의 PLAN이 출발한 지점이다. 만약 /office-hours를 건너뛰고 막연한 한 줄로 PLAN을 짰다면, "차선이 몇 개인지", "충돌 시 라이프 시스템이 있는지", "레벨이 끝나는 조건이 뭔지"를 ralph-loop이 자기 마음대로 결정해버렸을 것이다.

그림 설명: 좌측의 노란 박스가 처음 입력된 한 줄짜리 막연한 컨셉이다. 가운데 파란 박스 안에서 /office-hours가 네 차원의 질문을 던지고 사용자가 답한다. 우측 초록 박스에 정제된 컨셉이 떨어진다 — 이제 같은 게임에 대해 4차로인지 6차로인지, 레벨이 60초인지 90초인지, 라이프 제도가 있는지 없는지가 모두 명시되어 있다. 이 정제된 컨셉이 다음 단계의 분홍 박스, 즉 /plan-* 3종의 입력으로 넘어간다.

핵심 메시지

/office-hours는 컨셉의 모서리를 깎는 자리다. plan으로 넘어가기 전, 핵심 동사·진행 방식·실패 조건·타깃 사용자 네 가지 질문에 사용자가 직접 답해야 한다. 답하지 않은 질문은 코드가 대신 답하는데, 그 답은 십중팔구 사용자가 원한 게 아니다.

car-game에서 /office-hours 30분이 만들어 낸 정제된 컨셉은 이후 6일치 ralph-loop의 출발점이 됐다. 이 30분이 없었다면 /plan-* 3종은 빈 입력 위에서 추측을 해야 했고, 그 추측은 PLAN v1에 박혀 코드까지 흘러갔을 것이다.

다음 글은 이 정제된 컨셉을 PLAN으로 옮길 때 한 머리가 아닌 세 시선으로 통과시키는 자리를 다룬다.

이 글은 생성형 AI의 도움을 받아 작성되었습니다. 원본 자료를 기반으로 AI가 초안을 생성하고, 작성자가 검토·편집하였습니다.

Ralph-loop만으로는 부족한 이유, 그리고 gstack의 자리 — gstack 시리즈 (1/6)

타이젠 개발자, 윤진 — Tue, 19 May 2026 21:00:33 +0900

car-game(HTML5 Canvas 자동차 게임) 한 작품을 만드는 동안, 백그라운드로 ralph-loop(자율 LLM 코딩 루프)을 돌리면서 동시에 gstack 스킬을 단계별로 직접 호출했다. 그 경험을 6편 시리즈로 정리한다. 이 글은 시리즈의 도입부 — 왜 ralph-loop만으로는 부족한가, gstack은 그 부족함의 어디를 메우는가.

ralph-loop이라는 진척 도구

자율 LLM 코딩 루프(이하 ralph-loop)는 매력적이다. 한 줄짜리 프롬프트와 N분의 시간만 있으면 코드가 알아서 늘어난다. car-game의 첫 5일을 ralph-loop만으로 굴렸다. 그러다 6일째, 게임을 켜보고 멈췄다 — Lv10 도로가 온통 녹색이었다. 단위 테스트 384개는 모두 통과한 상태였다.

ralph-loop이 나쁘다는 얘기가 아니다. ralph-loop은 "지금 상태에서 다음 한 발짝"을 두는 진척 도구다. 그 한 발짝을 빠르게, 많이 두는 데는 강하다. 문제는 진척 도구를 그대로 품질 게이트로 쓰려고 할 때 생긴다.

자율 루프가 자기 시야 안에서 못 잡는 것들

car-game 세션에서 ralph-loop 단독 운영이 만든 사고들:

사용자 손 변경의 원복 — 직접 손으로 고친 보행자 회전 로직을 다음 사이클이 "정상화"하면서 원래대로 되돌렸다. ralph는 자기 머릿속 정답으로 돌아가려는 관성이 있다.
자기 컨벤션도 못 지킴 — 자기가 정의하지 않은 ROAD_WIDTH 상수를 import해 Lv10 보스 스폰에서 크래시. 자율 에이전트가 자기가 만든 코드의 컨벤션도 지키지 못한다.
테스트 통과 ≠ 동작 정상 — 단위 테스트 384개가 모두 통과한 상태에서도 도로가 녹색으로 렌더링됐다. 테스트가 검증하는 영역과 사용자가 실제로 보는 영역이 어긋났다.

세 사고는 모두 "자율 루프가 자기 시야 안에서 스스로는 잡지 못하는" 종류의 결함이다. 시야 밖에 무엇이 있는지를 봐주는 별도 차원의 게이트가 필요했다.

gstack의 자리 — 흐름 위에 놓이는 6개의 게이트

gstack은 Garry-shaped 스킬 모음이다. 기획부터 운영까지의 흐름에서, 인간 판단이 들어가야 할 지점들을 명세 + 도구로 정의해 둔 것. 이번 시리즈는 그 중 car-game에서 직접 사용한 6개 게이트가 무엇이고, 왜 나왔으며, 프로젝트에 어떻게 기여했는지를 한 편씩 다룬다.

그림 설명: 가로 축은 프로젝트의 시간 흐름(기획 → 구현 → 운영)이다. 위쪽 파란 띠는 ralph-loop. 백그라운드에서 계속 코드를 늘린다. 아래쪽 5개 박스는 각 흐름의 지점에 놓인 gstack 게이트다 — 기획에는 노란색 게이트(/office-hours, /plan-* 3종)가, 구현에는 초록색 게이트(/review, /qa)가 놓이고, 운영 차원에서는 분홍색 /investigate가 필요할 때 어느 지점에든 끼어든다(점선). ralph-loop과 게이트가 만나는 지점에서 사용자가 검증·commit하기 때문에, ralph의 다음 사이클은 잘못된 위에서 출발할 수 없다.

6일째에 멈춘 사고들

ralph-loop을 끄지 않고 그 위에 gstack 게이트를 얹은 6일째부터 사고가 멈췄다. 같은 ralph-loop이 같은 속도로 코드를 늘렸지만, 사이클 사이마다 사용자가 게이트를 통과시키며 commit했다. 같은 도구 두 가지 운영 방식의 차이를 한 번 보여 본다:

그림 설명: 위 트랙은 5일차까지의 ralph-loop 단독 운영. 처음 두 사이클은 잘 굴러가지만(파란 점), 사용자 손 변경의 원복 → 크래시 누적 → 도로 녹색까지 사고가 늘어난다. 아래 트랙은 6일차부터의 운영. 같은 사이클 사이에 /qa(초록), /review(초록), /investigate(분홍 — 결정성 테스트 결함을 캐냄)가 끼어 들어 사용자가 검증·commit한다. ralph는 늘 깨끗한 상태에서 다음 발걸음을 시작하므로, 사고가 누적될 출발점이 사라진다.

핵심 메시지

ralph-loop은 끄지 않는다. 거리를 늘리는 도구로서 그대로 둔다. gstack 스킬은 그 거리에 의미를 박는 게이트다. 이 시리즈의 나머지 다섯 글은 그 게이트들이 car-game에 구체적으로 어떤 기여를 했는지를 하나씩 다룬다.

시리즈 안내

기획 → 구현 → 운영 흐름:

(이 글) Ralph-loop만으로는 부족한 이유, 그리고 gstack의 자리
/office-hours — 막연한 컨셉을 plan으로 갈 수 있게 깎는 자리
/plan-* 3종 (CEO/ENG/DESIGN) — 한 PLAN 문서를 세 시선으로 통과시키기
/review — 테스트가 못 보는 의미 부패를 청소하는 자리
/qa — 함수가 옳아도 화면에 안 나타나는 버그를 잡는 자리
/investigate — Trivial pass의 뿌리를 캐는 자리

이 글은 생성형 AI의 도움을 받아 작성되었습니다. 원본 자료를 기반으로 AI가 초안을 생성하고, 작성자가 검토·편집하였습니다.

한 285줄 스크립트가 self-recovering 자율 시스템이 되기까지 — ralph-loop.sh 의 8 commit 진화사 (Ralph Loop 시리즈 8편 통합)

타이젠 개발자, 윤진 — Mon, 18 May 2026 22:00:00 +0900

한 주말 취미 프로젝트에서 자동차 회피 게임을 AI 에이전트한테 자율적으로 시켜보려고 285줄짜리 bash 스크립트를 짰다. 그 스크립트는 처음부터 self-recovering 시스템이 아니었다 — 단순한 while true; do opencode run; done 한 줄에서 시작해서, 사고 한 번에 한 줄씩 늘어나며 어떻게 끝나든 자기 자원을 정리하고 / vLLM 죽음을 자동 복구하고 / 막힌 항목을 자동 우회하고 / 거짓 보고를 외부 검증으로 잡는 시스템이 됐다.

이 글은 시리즈 8편 통합편이다. 1~7편에서 각 디자인 결정의 왜와 어떻게 를 한 편씩 풀었다면, 이 글은 그 모든 결정이 한 스크립트 안에서 어떻게 합쳐져 자율성을 만드는가 를 본다. 8개의 commit 으로 진화한 ralph-loop.sh 의 timeline, 그 각 commit 이 어떤 사고에 대한 대응 이었는지, 그리고 38 iter 운영의 정량 결과까지.

전체 시리즈 인덱스

먼저 1~7편이 무엇을 다뤘는지 한눈에 정리한다.

1편 (컨텍스트 3축): PLAN.md (불변) + CHECKLIST.md (가변) + git (실측 가변) 의 분리. 매 iter 같은 PLAN 이 던져지지만 CHECKLIST 와 git 이 진척을 누적해 모델은 매번 새 세션이지만 작업은 누적 된다.
2편 (부팅과 셧다운): GPU acquire + vLLM 기동 + cleanup trap. released=false idempotent flag 가 어떻게 끝나든 정확히 한 번 release 보장.
3편 (vLLM 헬스 보장): ensure_vllm_alive() 의 9가지 진단 정보 캡처 + 자동 재기동. vllm-deaths.log 가 학습 자산이 됐다.
4편 (프롬프트 다층 메시지): 수행 순서 7단계는 효과 있음, 도구 가이드는 효과 0. prompt 가 닿는 layer 와 못 닿는 layer 의 구분.
5편 (opencode 호출 함정): yargs -f array 함정의 -- 구분자, 5분 timeout, 직후 헬스체크. 한 줄 호출이 17줄로 늘어난 이유.
6편 (외부 검증 후크): CHECKLIST 토글 + 직전 3분 commit 의 AND. 모델이 보고하는 채널 과 검증하는 채널 분리.
7편 (3-strike + 진척률 거짓말): dead-letter 패턴 + 진척률 32% 가 80% 로 보였던 사건. 사용자 통찰로 sed 한 줄 복원.

이 7개 패턴이 처음부터 다 있었던 게 아니다. 초기 scaffold + 7번의 사고 대응을 거치며 한 줄씩 추가됐다 — 총 8 commit. ralph-loop.sh 의 git log 가 그 8단계를 정확히 기록한다.

ralph-loop.sh 의 8 commit 진화 timeline

$ git log --oneline --reverse -- ralph-loop.sh

404f9d1 infra: Ralph Loop scaffold with PLAN, CHECKLIST, loop script
2348801 fix(ralph): pin model id to actual opencode provider config
20f2a12 fix(ralph): use -- separator to prevent -f array swallowing the prompt
64dadd5 feat(ralph): remove iteration cap (default unlimited)
eb70f0e feat(ralph): tool-use guidance + 3-strike skip for stuck items
8486e7d feat(ralph): integrate gpu-scheduler to keep vLLM loaded during loop
f190ae6 feat(ralph): per-iter vLLM healthcheck + crash diagnostics
3bd0362 feat(ralph): wrap opencode call with 300s timeout

각 commit 이 어떤 사고에 대한 대응이었는지 — 정확한 시간과 함께 짚는다.

그림 설명 — 8 commit 의 시간 분포가 집중적 이다. 처음 4 commit (09:33~09:35) 은 초기 scaffold + 즉시 발견된 함정들 (모델 ID, -- 구분자, 무제한 iter). 그 다음 4 commit (09:44~13:02) 이 운영 중 실제 사고에 대응한 진화. 색깔이 commit 의 카테고리 를 표현한다 — 보라(infra), 노랑(fix/feat), 빨강(긴급 대응), 녹색(중요 feature). 사고가 발생할 때마다 한 줄 추가된 git log 가 어떻게 시스템이 자율성을 키워갔는지 의 정확한 기록이다.

각 commit 의 사고 스토리

몇 commit 의 사고 → 대응 스토리를 짧게 본다.

commit 3 (20f2a12 fix: -- 구분자 추가) — 처음 ralph-loop.sh 를 실행하자마자 Error: File not found: 당신은 PLAN.md 의 ... 발생. 30초 만에 수정. yargs -f array 가 $prompt 를 file 경로로 흡수한 거였고 -- 한 단어로 해결. 사소해 보이지만 없으면 ralph-loop 자체가 작동 안 함. 가장 작은 commit 이지만 가장 결정적이었다.

commit 5 (eb70f0e feat: 도구 가이드 + 3-strike 스킵) — 처음 운영 중 한 항목 (src/main.js 부트스트랩) 에서 30분 정체. 모델이 도구 호출 schema 에러 반복. 검증 후크가 즉시 exit 시키면 자율성 0이라 — 시도 카운트 + 자동 마킹의 dead-letter 패턴 도입. 동시에 prompt 에 도구 사용 가이드 5단 추가 (효과는 거의 없었지만 안전장치로 남김). 이 commit 이 ralph-loop 를 반자동 에서 자율 로 바꾼 변곡점이었다.

commit 7 (f190ae6 feat: 매 iter 헬스 + 진단 캡처) — vLLM 컨테이너가 KV cache assertion 으로 자살하고 30분간 ralph-loop 가 정체. 시리즈 3편의 사건. 이 commit 이 self-recovering 의 핵심 — 매 iter 시작 + opencode 직후 헬스체크 + 진단 9가지 캡처 + 자동 재기동. 한 함수가 65줄. ralph-loop 의 가장 큰 진화였다.

commit 8 (3bd0362 feat: 5분 timeout) — vLLM 이 죽었지만 자동 복구 후 opencode 가 죽은 connection 에 hang. 헬스체크는 통과했는데 opencode 자체는 응답 끊긴 상태로 영영 대기. timeout 한 줄로 막음. 이건 직전 commit 7의 보완 — 자동 복구가 모든 hang 을 막진 못한다는 발견이었다.

각 commit 이 그 직전 사고의 대응 이라는 패턴이 명확하다. 처음부터 self-recovering 으로 짜진 게 아니라 — 사고 → 대응 → 사고 → 대응 의 8 cycle 끝에 self-recovering 이 됐다.

최종 형태 — 285줄이 만드는 self-recovering 시스템

8 commit 후 ralph-loop.sh 가 어떤 일을 하는지 한 번에 본다. 의미 단위로 묶은 285줄의 구조:

단계	줄 범위	역할	시리즈 매핑
전역 변수	1~30	경로·env·자원 ID·flag	—
ensure_vllm_alive()	32~97	매 iter 헬스 + 진단 + 재기동	3편
cleanup() + trap	99~108	idempotent 종료 처리	2편
부팅 시퀀스	110~130	GPU acquire + vLLM 기동 + 헬스체크	2편
메인 while 루프	132~280	iter 처리	—
↪ 다음 항목 추출	137~145	CHECKLIST grep	1편
↪ iter 시작 헬스	147~151	1번째 헬스체크 호출	3편
↪ git 컨텍스트 캡처	153~155	git log + status	1편
↪ prompt 조립	164~211	3축 컨텍스트 + 7단계 + 도구 가이드	1편, 4편
↪ 시도 카운트	214~224	.prev_item / .attempts 누적	7편
↪ opencode 호출	226~240	timeout + -- + tee + rc 분리	5편
↪ 직후 헬스체크	242~249	2번째 헬스체크 호출	3편, 5편
↪ 외부 검증	251~260	CHECKLIST 토글 + commit AND	6편
↪ 검증 분기	262~277	완료 vs 시도 카운트 vs 자동 스킵	6편, 7편

매 줄이 어느 시리즈의 어느 패턴 에 매핑된다. 285줄 중 단 한 줄도 — 우연히 거기 있는 줄은 없다. 모두 어떤 사고의 대응 또는 어떤 운영 원칙의 구현 이다.

정량 결과 — 38 iter 운영의 숫자들

ralph-loop 의 마지막 사이클을 정량으로 본다.

지표	값	해석
총 iter 수	38	재시작 포함
총 commit 수	72	인프라 + 게임 코드 합산
vitest 테스트 수	200 passed (14 files)	모든 단위 테스트 통과
vLLM 자살 횟수	2	모두 KV cache off-by-one assertion
vLLM 자동 복구 횟수	2 / 2	100% 자동 복구
schema 에러 (qwen3_xml 시점)	108회 (30 iter)	iter 평균 3.6회
schema 에러 (qwen3_coder 시점)	0회 (30 iter)	한 줄 변경의 효과
자동 스킵 → 잔여 복원 횟수	1 (sed 한 줄, 20 항목)	환경 변경 후 일괄
최종 CHECKLIST	완료 44 / 잔여 0 / 스킵 0	100% 진척
사용자 개입 횟수 (긴급)	0	cron 보고 + 결정만, 직접 코드 수정 0
총 운영 시간	~5시간	09:33 시작 ~ 14:55 완료

몇 가지 주목할 점이 있다.

vLLM 자살 100% 자동 복구 — 인프라 자체의 안정성은 못 고쳤지만 (vLLM 0.19 KV cache 버그는 우리가 패치 못함), 그 위에 복구 layer 를 만들어 운영이 안 멈추는 결과를 달성. 알려진 버그가 있는 인프라 위에서도 자율성을 살린 실용적 답이었다.

schema 에러 한 줄 변경의 효과 — qwen3_xml → qwen3_coder 한 줄이 평균 3.6회/iter 였던 schema 에러를 0으로. 인프라의 정공 이 prompt 강화 며칠보다 효과적이었다는 데이터.

사용자 개입 0회 (긴급) — 38 iter 운영 중 사용자가 직접 코드 수정 한 적 0번. 모두 cron 보고와 결정만으로 처리. 진정한 자율성의 정량 증거.

Ralph Loop 패턴의 일반화 — 다른 자율 시스템에 가져갈 것

이 시리즈에서 다룬 7가지 패턴은 ralph-loop 만의 것이 아니다. 외부 LLM 또는 도구를 호출하는 모든 장기 실행 자율 시스템 에 적용된다.

패턴	일반화	적용 도메인 예시
컨텍스트 3축	불변 정의 + 가변 진척 + 실측 상태	CRM 자동화, 운영 자동화, IaC 적용
idempotent cleanup	외부 자원 정확히 한 번 release	DB connection, lock, lease, port bind
매 iter 헬스 + 진단	의존성 자동 복구 + 9-인자 진단 캡처	마이크로서비스 호출, ETL 파이프라인
prompt 다층	의사결정 layer 지시 + 도구 layer 가이드 (효과 다름)	모든 LLM 응용
CLI 호출 안전망	-- 구분자 + timeout + rc 분리 + 직후 헬스	외부 서비스 호출, batch job
외부 검증 후크	응답 채널 ≠ 검증 채널, AND of 외부 사실	모든 자율 에이전트
3-strike dead-letter	막힘 자동 우회 + 명시적 마킹 + 사후 검토	큐 시스템, 워커 풀, retry 로직

핵심은 — AI 자율 에이전트 라는 새로운 영역에서도 운영의 원칙은 분산 시스템 운영의 고전 과 다르지 않다는 것. dead-letter, idempotent retry, 외부 검증, layer 분리 — 모두 메시지 큐와 마이크로서비스에서 수십 년간 쌓여온 패턴들이다. AI 에이전트 운영도 같은 원칙 위에 서 있다.

한 가지 안타까웠던 점 — 사용자 통찰 없이 못 알아챈 함정

시리즈 7편의 진척률 거짓말 함정 — 32% 가 80% 처럼 보였던 것 — 은 사용자가 직접 짚어줘야 알아챘다. "스킵도 잔여로 가야 하지 않나" 라는 한 마디. 운영 metric 을 명시적으로 쪼개서 보여주고 있었음에도 불구하고 — 인지적으로는 진척처럼 느껴지는 함정이 있었다.

이게 자율 시스템의 한 한계일 수도 — 시스템이 보여주는 metric 과 사용자가 인지하는 의미 사이의 거리. 시스템이 정직하게 데이터를 보여줘도 사용자가 잘못 해석하면 잘못된 결정으로 이어진다. 이 한계를 줄이려면 — metric 의 의미를 명시적 한 줄로 같이 보여주는 디자인이 필요하다. "스킵 = 진정 미완성, 사람 검토 또는 환경 변경 후 재시도 필요" 같은 한 줄.

이 시리즈를 읽는 분 중 자율 시스템을 운영하는 분이 있다면 — 내 시스템의 metric 이 정직하게 보이는가? 사용자가 그 metric 을 정확히 해석할 수 있는가? 한 번 점검해볼 가치가 있다.

결론 — 자율 시스템은 진화한다

이 시리즈의 큰 메시지 — self-recovering 자율 시스템은 처음부터 그렇게 짜이지 않는다. 진화한다.

ralph-loop.sh 의 첫 commit (404f9d1 infra: scaffold) 은 286줄이 아닌 ~150줄짜리 단순한 스크립트였다. 그 위에 사고 → 대응 → 사고 → 대응 의 8 cycle 이 누적되어 — 마지막 commit (3bd0362) 시점엔 어떻게 끝나든 자기 자원 정리 / vLLM 죽음 자동 복구 / 막힘 자동 우회 / 거짓 보고 검증 의 4 layer 안전망을 갖춘 285줄 시스템이 됐다.

각 진화는 그 사고가 일어나기 전엔 예측 못 한 것이었다. yargs -f array 함정, vLLM KV cache 자살, opencode hang, schema 에러의 진짜 원인 — 모두 첫 scaffold 짤 때는 모르는 일이었다. 예측 가능했다면 첫 commit 에 다 넣었을 것이다. 못 넣은 게 지식의 한계 였고 그 한계를 운영 중 사고로 발견 했고 commit 으로 영구 박았다.

그래서 이 시리즈가 들려주고 싶은 건 — 완벽한 첫 설계 라는 환상이 아니라 — 진화할 수 있는 구조 를 만드는 게 더 중요하다는 것. ralph-loop.sh 가 진화 가능했던 이유는 — 작고 (285줄), 단일 파일이고, git history 가 깔끔하고, 각 패턴이 서로 직교 했기 때문이다. 만약 처음에 1000줄짜리 거대한 자율 시스템 프레임워크를 짰다면 — 8 commit 진화 동안 곳곳에서 부서졌을 것이다.

주말 취미로 짠 285줄짜리 bash 스크립트가 — 진정한 자율 시스템 의 모양을 가르쳐줬다. AI 시대에도 운영의 원칙은 변하지 않는다 — 작게 시작하고, 사고에서 배우고, git log 가 그 학습을 영구 기록한다. 이게 그 시리즈의 한 줄 결론이다.

(시리즈 끝. 1~8편 모두 비공개 draft 로 작성됐습니다. 저자가 사후 리뷰 후 비공개 발행 예정.)

이 글은 생성형 AI의 도움을 받아 작성되었습니다. 원본 자료를 기반으로 AI가 초안을 생성하고, 작성자가 검토·편집하였습니다.

AI 자율 루프의 dead-letter 패턴 — 3-strike 자동 스킵과 진척률 80%가 사실은 32%였던 이야기 (Ralph Loop 시리즈 7편)

타이젠 개발자, 윤진 — Mon, 18 May 2026 21:00:50 +0900

자동 진행 루프를 짤 때 가장 어려운 결정은 막힌 항목을 어떻게 처리할까 다. 처음 ralph-loop 를 짤 때는 단순했다 — 검증 후크가 실패하면 즉시 exit 2. 사람이 들어와서 보고 다시 시작하라는 의도였다. 결과는 — 자율성 0. 한 시간 자리 비웠다 돌아오면 ralph-loop 가 첫 항목에서 막힌 채 멈춰있었다.

이 글은 그 이후 도입한 3-strike 자동 스킵 패턴과, 그 패턴이 만든 진척률 거짓말 함정 — 진척률 80% 가 사실은 32% 였던 — 을 다룬다. 자율성을 위해 한 결정이 어떻게 진척의 의미를 흐리는지, 그리고 사용자가 직접 짚어준 통찰로 어떻게 한 줄로 회복했는지. 시리즈 7편이고 1~6편은 컨텍스트 / 부팅·셧다운 / vLLM 헬스 / prompt 다층 / opencode 함정 / 외부 검증을 다뤘다.

출발점 — 즉시 exit 의 자율성 비용

초창기 ralph-loop.sh 의 검증 분기는 단순했다.

# 초기 버전 (사람 개입 강제)
if grep -nq "^- \[ \] ${escaped}\$" CHECKLIST.md; then
  echo "⚠️  검증 1 실패 (CHECKLIST 미토글)"
  exit 2
fi
if ! git log --oneline -1 --since="3 minute ago" | grep -q .; then
  echo "⚠️  검증 2 실패 (commit 누락)"
  exit 3
fi
echo "✅ iter 완료"

이 코드의 의도는 모든 실패는 명시적 사람 결정이 필요하다 였다. 그런데 운영해보니 — 모델이 한 항목 (예: src/spawner.js) 에서 도구 호출 schema 에러로 막히면 거기서 영영 종료. 다른 35개 항목은 시도조차 못 함. 사람이 와서 "막힌 항목 건너뛰고 다음 거 해" 라고 손으로 CHECKLIST 를 토글해주든지 항목을 지워줘야 했다.

이게 자율 시스템이 아니라 반자동 시스템 이다. 사람이 매 막힘마다 들어와야 하니 출장 중이거나 잘 때는 진척 0. ralph-loop 의 가치가 "내가 자는 동안 38 iter 돌아가는 것" 인데 그 가치를 못 살린다.

해결의 출발점은 — 막힌 항목은 자동으로 우회하되, 그 우회 사실을 명시적으로 표시 하는 것. dead-letter queue 의 메시지 큐 패턴과 같은 발상이다.

3-strike 패턴 — 시도 카운트와 자동 마킹

구현은 두 부분이다. 시도 카운트 누적 + 3회 도달 시 자동 마킹이다.

# 시도 카운트 (같은 항목을 몇 번째 처리하는가)
prev_item=$(cat "$LOG_DIR/.prev_item" 2>/dev/null || echo "")
attempts=$(cat "$LOG_DIR/.attempts" 2>/dev/null || echo "0")
if [ "$item" = "$prev_item" ]; then
  attempts=$((attempts + 1))
else
  attempts=1
fi
printf '%s' "$item" > "$LOG_DIR/.prev_item"
echo "$attempts" > "$LOG_DIR/.attempts"
echo "   시도 $attempts/3"

# (... opencode 호출 + 검증 ...)

# 검증 분기
if $checked && $committed; then
  echo "✅ iter 완료 — 다음 항목으로"
  echo "0" > "$LOG_DIR/.attempts"
  : > "$LOG_DIR/.prev_item"
else
  echo "⚠️  iter 미완 (시도=$attempts/3)"
  if [ "$attempts" -ge 3 ]; then
    # 3회 연속 실패 — 항목을 [!] 로 마킹하고 다음으로
    sed -i "s|^- \[ \] ${escaped}\$|- [!] ${escaped}|" CHECKLIST.md
    git add CHECKLIST.md
    git commit -m "skip: $(printf '%s' "$item" | head -c 60) (3회 실패)" || true
    echo "  항목 자동 스킵 → CHECKLIST 에 [!] 마킹 후 진행"
    echo "0" > "$LOG_DIR/.attempts"
    : > "$LOG_DIR/.prev_item"
  fi
fi

코드 설명 — .prev_item 과 .attempts 두 상태 파일이 같은 항목으로 몇 번째 시도하는가 를 추적한다. 새 iter 가 같은 항목으로 들어오면 attempts++, 다른 항목이면 1로 리셋. 검증 통과 시 둘 다 비움. 검증 실패가 누적돼 3회에 도달하면 — sed 로 CHECKLIST 의 - [ ] 를 - [!] 로 변경하고, 그 변경 자체를 "skip: ..." commit 으로 박는다. 이 commit 이 박힌 후 다음 iter 가 시작되면 grep ^- \[ \] 패턴이 그 항목을 건너뛰고 다음 미체크 항목으로 자연스럽게 진행한다.

그림 설명 — 같은 항목으로 시도가 누적되는 과정. iter N 의 시도 1, 시도 2, 시도 3 모두 검증 실패하면 — sed 로 항목을 [!] 로 마킹하고 그 변경 자체를 commit 으로 박는다. 그 commit 후 다음 iter (N+1) 가 시작되면 — grep 의 ^- \[ \] 패턴이 [!] 와 매치 안 되니 자연스럽게 다음 미체크 항목 으로 진행. 사람 개입 0회. .attempts 와 .prev_item 두 상태 파일이 시도 카운트의 지속성 을 책임진다.

왜 `[!]` 를 commit 으로 박나

스킵 마킹을 sed 로만 하고 끝낼 수도 있는데 — 굳이 commit 을 추가로 박는다.

sed -i "s|^- \[ \] ${escaped}\$|- [!] ${escaped}|" CHECKLIST.md
git add CHECKLIST.md
git commit -m "skip: $(printf '%s' "$item" | head -c 60) (3회 실패)" || true

왜 commit 까지? 두 가지 이유가 있다.

첫째, 검증 후크가 commit 존재 를 진척의 한 조건으로 본다. 만약 sed 만 하고 commit 안 하면 — CHECKLIST.md 가 dirty (uncommitted changes) 인 채로 다음 iter 가 시작된다. 다음 iter 의 git_status 캡처에 그 dirty 가 포함되고 모델이 그걸 "미해결 변경이 있다" 로 잘못 인지할 수 있다. commit 까지 하면 그 변경이 이미 영구적으로 박힌 상태 로 명시된다.

둘째, git history 가 dead-letter 의 audit log 가 된다. git log --oneline | grep '^skip:' 한 줄로 어느 항목들이 자동 스킵됐나 를 시간순으로 본다. 사후 분석에 가치 있다 — "파서 변경 전에 스킵된 항목들 vs 변경 후" 의 비교 가 즉시 가능. 우리도 이걸로 "qwen3_xml 파서 시점에 어느 항목들이 스킵됐는지" 를 정확히 추적했다.

|| true 가 끝에 붙어있는데 — commit 이 어떤 이유로든 실패해도 (이미 staged 가 비어있다거나) ralph-loop 가 죽지 않게 한다. set -e 활성화 환경에서 자율 운영의 안전장치다.

진척률의 거짓말 — 80% 가 사실은 32% 였다

3-strike 패턴이 자율성을 살렸지만 — 새로운 함정이 생겼다. 진척률 의 의미가 흐려진 것이다.

운영 중 사용자한테 진척 보고를 보내면 이런 형태였다.

완료(x): 9 / 잔여([ ]): 16 / 스킵(!): 19
→ 진척률: 9/(9+16) = 36%

이걸 보고 "36% 진척했네" 로 인지했다. 그런데 사용자가 핵심 질문을 던졌다 — "스킵은 어떤 의미야? 스킵도 잔여로 가야 하지 않나?"

맞는 말이다. 스킵은 의미적으로 미완성 이다. ralph-loop 가 자동 우회한 거지 작업을 끝낸 게 아니다. 그러면 진정한 진척률은:

완료(x): 9 / 진정한 미완성: 16 + 19 = 35
→ 진정한 진척률: 9/(9+35) = 9/44 = 20%

36% 가 아니라 20% 였다. 우리 인지가 16%p 만큼 부풀려진 상태로 운영하고 있었다. 즉 — 3-strike 자동 스킵이 진척처럼 느껴지게 만든다. 그런데 실제로는 "이 항목은 자동으로 못 했음" 의 표시일 뿐이다.

이 함정이 위험한 이유는 — 환경 변경의 효과 를 잘못 판단할 수 있어서다. 만약 진척률 36% → 50% 로 보이면 환경 변경이 잘 되고 있다고 착각하는데, 실제로는 완료가 늘어난 게 아니라 스킵이 늘어난 케이스일 수 있다. 즉 진척이 정체된 상태에서 dead-letter 만 쌓이고 있는데도 진척률은 올라가는 사고다.

그림 설명 — 3-bucket 분류로 진척률을 표현해야 정확하다. 잘못된 계산은 스킵을 분모에서 빼는 거고, 정확한 계산은 잔여로 카운트 한다. 함정 사례를 보면 완료가 그대로인데 잔여가 줄고 스킵이 늘어나도 잘못된 계산은 진척률이 오르는 것처럼 보인다. 이게 환경 변경 효과 측정 같은 운영 결정에서 잘못된 결론으로 직결될 수 있다.

처방 — sed 한 줄로 32% 가 84% 로

사용자 통찰 후 즉시 처방을 적용했다. 핵심 발상은 — 스킵된 항목들 중 다수가 qwen3_xml 파서 시점에 도구 호출 schema 에러로 막혔던 거지, 본질적으로 모델이 못하는 게 아니다. 파서를 qwen3_coder 로 변경한 후엔 같은 항목들이 통과 가능성이 매우 높다. 그러니 모든 [!] 마크를 잔여로 되돌리고 다시 시도하게 하면 된다.

# 변경 전 (직전 환경 변경 후 정체 상태)
완료(x): 9, 잔여([ ]): 8, 스킵(!): 20
정확한 진척률 = 9/37 = 24%

# 스킵 → 잔여 일괄 복원
sed -i 's/^- \[!\] /- [ ] /' CHECKLIST.md

# 시도 카운트 리셋 (같은 항목으로 즉시 3-strike 재발 방지)
rm -f .ralph-logs/.prev_item .ralph-logs/.attempts

# 변경 자체를 commit (audit log)
git add CHECKLIST.md
git commit -m "feat: revert all skipped items back to pending after parser fix"

# 변경 후 — 잔여 28 모두 시도 가능
완료(x): 9, 잔여([ ]): 28, 스킵(!): 0

이 sed 한 줄이 환경 변경의 효과를 다시 측정 가능 하게 만들었다. 그 다음 ralph-loop 사이클에서 잔여 28개 중 23개가 통과해 — 진척률이 32% (= 9/28) → 84% (= 32/38) 로 도약했다. 만약 이 통찰 없이 진척률 80% 를 자연스러운 진척 으로 봤다면 — qwen3_coder 파서의 진짜 효과를 영영 못 측정했을 것이다.

왜 사용자가 짚어줘야 알았나 — 운영 metric 의 인지적 함정

이 거짓말을 우리(나) 가 못 알아챈 이유를 돌아보자. 매 cron 보고에 "완료 9 / 잔여 8 / 스킵 20" 같은 형태로 3-bucket 을 명시했다. 데이터는 다 보여졌다. 그런데 인지적으로는 "잔여 8 = 거의 다 끝났음" 로 받아들였다. 스킵 20 은 "이미 처리된 분류" 처럼 무의식적으로 느껴졌다.

왜? UI/UX 의 한 패턴이다 — 사용자가 진행 중인 항목 과 완료/실패한 항목 을 다른 카테고리로 분리하면 진행 중 만 남은 일 로 인지한다. 완료와 실패가 같은 "이미 끝난 분류" 로 묶인다. 그런데 실패와 완료는 의미적으로 정반대다. 같은 분류로 묶이면 인지 함정에 빠진다.

그래서 운영 metric 의 명시는 — 단순히 3-bucket 카운트만 보여주는 게 아니라 진정한 미완성 = 잔여 + 스킵 을 명시적 한 줄로 추가해야 한다. ralph-loop 의 cron 보고를 다음과 같이 수정했다.

  Ralph Loop 상태
- 완료(x): 9
- 잔여([ ]): 8
- 스킵(!): 20  ← 진정 미완성, 사람 검토 또는 환경 변경 후 재시도 필요
- 진정한 진척률: 9/37 = 24%

이렇게 "스킵 = 진정 미완성" 한 줄을 옆에 붙이면 인지 함정을 막는다.

3-strike 의 적정값 — 왜 3인가

"왜 3 strike 인가" 도 짚자. 1 또는 2 또는 5 가 아닌 3 의 근거는 — 경험적 trade-off 다.

strike 수	장점	단점
1 (즉시 스킵)	막힘 시간 최소	일시적 환경 문제 (vLLM 일시 hang) 도 즉시 스킵 → 가짜 스킵 多
2	한 번 재시도 기회	일시적 vs 영구 실패 구분이 약함
3	일시적 실패는 재시도, 영구 실패는 빨리 우회 — 균형	—
5	더 많은 재시도 기회	같은 항목에서 ~10 ~ 15분 정체 가능
∞	—	막힘 = 무한 정체. dead-letter 의미 사라짐

3 이 영구 실패의 고집을 빨리 포기 하면서 일시적 실패에는 충분한 기회 를 주는 균형점이었다. 38 iter 운영 중 — 일시적 vLLM hang 으로 1~2 strike 후 통과한 케이스가 3건, 3 strike 도달해 자동 스킵 처리된 케이스가 19건 (변경 전), 영구 실패가 2 strike 안에 통과한 케이스 0건. 즉 3 strike 가 영구 실패 19건은 모두 스킵 했고 일시적 실패 3건은 자동 회복 시켰다. 적정값이었다.

일반화 — dead-letter 패턴은 어디나 있다

이 패턴은 ralph-loop 만의 것이 아니다. 모든 자동 처리 큐에 비슷한 게 있다.

RabbitMQ / SQS: dead-letter queue 자체가 N회 재시도 실패한 메시지를 옮기는 표준 패턴
K8s pod backoff: CrashLoopBackOff 가 N회 재시작 실패 후 backoff 늘리는 동일 발상
CI/CD 파이프라인: flaky test 가 N회 retry 후 failed 로 기록되는 것
cron 작업: failed exec count 누적 후 disable

공통 원칙은 — 막힌 작업 단위를 시스템이 자동 우회하되, 그 우회 사실을 명시적 표시로 남겨 사람이 사후 점검 가능하게 한다. ralph-loop 의 [!] 마크와 skip: commit 메시지가 그 표시다.

그리고 진척률의 거짓말 함정도 일반화된다. dead-letter 큐 깊이가 진척에 보이지 않으면 — 전체 큐 처리율 = 100% 처럼 보이지만 사실은 처리 못 한 메시지가 dead-letter 에 누적되고 있는 상태일 수 있다. 운영 metric 은 항상 dead-letter 깊이까지 함께 보여야 한다.

결론 — 자율성과 진정한 진척의 균형

이 글의 두 가지 결론은 이렇다.

첫째, 자동 우회 없이 자율은 없다. 막힘에 사람 개입 강제하면 ralph-loop 의 가치 자체가 무너진다. 3-strike dead-letter 는 자율성을 위한 필요악 이다.

둘째, 자동 우회의 결과는 명시적으로 추적해야 한다. [!] 마크와 skip commit 이 그 추적이고, 진척률 표현에서 스킵을 잔여로 카운트 해야 진정한 진척이 보인다. 그렇지 않으면 진척처럼 보이는 정체 라는 가장 위험한 운영 상태에 빠진다.

그리고 이 함정을 사용자가 직접 짚어줘야 알아챘다는 게 — 자율 시스템 운영의 또 다른 교훈이다. 시스템이 보여주는 metric 과 사용자가 인지하는 의미 는 종종 다르고, 그 차이가 위험한 결정으로 직결될 수 있다. metric 의 명시적 의미 표현 — "스킵 = 진정 미완성" 같은 한 줄 — 이 그 차이를 줄인다.

이 글은 생성형 AI의 도움을 받아 작성되었습니다. 원본 자료를 기반으로 AI가 초안을 생성하고, 작성자가 검토·편집하였습니다.

AI 가 "다 했다" 라고 보고할 때 의심하라 — 외부 검증 후크 두 줄의 의미 (Ralph Loop 시리즈 6편)

타이젠 개발자, 윤진 — Sun, 17 May 2026 23:00:07 +0900

자율 에이전트가 가장 위험할 때는 실패할 때 가 아니라 실패했는데 성공했다고 보고할 때 다. ralph-loop 초반에 가장 자주 본 실패 패턴이 이거였다 — 모델이 "작업 완료, CHECKLIST 토글, 커밋 했음" 이라고 응답을 끝냈는데 정작 git log 에는 commit 이 없거나, CHECKLIST.md 의 라인이 그대로 - [ ] 인 경우. 응답 텍스트만 보면 진척이 잘 되는 것 같은데 실제로는 작업이 안 되어 있다.

이 글은 그 거짓 보고를 잡기 위해 ralph-loop.sh 가 매 iter 끝에 수행하는 두 줄짜리 외부 검증 후크 — (1) CHECKLIST 라인이 진짜 토글됐는가 (2) 직전 3분 안에 git commit 이 진짜 생성됐는가 — 를 분해한다. 단순한 grep 두 번이지만 그 안에 AI 응답을 신뢰하지 않는 운영 철학 이 박혀있다. 시리즈 6편이고, 1~5편은 컨텍스트 3축 / 부팅·셧다운 / vLLM 헬스 보장 / prompt 다층 메시지 / opencode 호출 함정을 다뤘다.

출발점 — 모델이 거짓말을 한다는 게 아니라

오해를 먼저 풀자. 모델이 의도적으로 거짓말 하는 게 아니다. ralph-loop 38 iter 동안 관찰한 거짓 보고의 원인은 다음 중 하나였다.

shell escape 사고 — 모델이 git commit -m "feat: 한국어 메시지 with \"중첩 따옴표\"" 같은 형식으로 commit 하다가 셸이 따옴표를 해석 실패해 commit 자체가 깨짐. 모델은 응답에 "커밋 완료" 적었지만 실제론 commit 안 됨
도구 호출 실패의 부분 인지 — Edit 도구 호출이 SchemaError 로 실패했지만 모델이 그걸 부분적으로 인지하고 나머지는 됐다고 가정 하고 응답 마무리
응답 토큰 limit — 모델이 작업 끝까지 갔지만 응답 텍스트가 limit 에 걸려 "커밋했음" 까지 출력하기 전에 잘림. CHECKLIST 토글까진 했는데 commit 만 누락
vLLM streaming 끊김 — 시리즈 3편의 KV cache 자살. 응답 도중 끊겨서 모델이 "작업 끝낼 의도였는데" 못 끝냄

모두 모델 책임 이 아니라 그 사이 어딘가의 layer 책임이다. 그래도 결과는 같다 — 모델 응답 텍스트와 실제 시스템 상태가 어긋난다. 자율 시스템이 모델 응답만 신뢰 하면 그 어긋남이 누적되어 잘못된 진척률 보고로 이어진다.

해결의 출발점은 — 모델이 보고하는 채널과 실제 결과를 검증하는 채널을 분리 하는 것. 모델은 응답 텍스트로 보고하고, 우리는 모델이 건드린 외부 사실 에서 검증한다.

두 외부 사실 — CHECKLIST 토글 + git commit 존재

ralph-loop 의 작업 단위에서 모델이 건드려야 하는 외부 사실 은 정확히 두 가지다.

CHECKLIST.md 의 해당 라인이 - [ ] → - [x] 로 바뀌었는가
그 변경이 git commit 으로 박혔는가

이 둘이 모두 만족되면 작업 진척이 영구적으로 시스템에 박힌 상태다. 한 가지만 만족되면 — CHECKLIST 만 토글되고 commit 이 없으면 다음 iter 에 git status 에 dirty 로 보일 거고, commit 만 있고 CHECKLIST 토글 안 됐으면 같은 항목을 다음 iter 에 또 시도하게 된다. 둘 다 안 되면 진척 0.

그래서 검증 후크는 두 사실을 외부에서 확인한다.

# 검증 1 — CHECKLIST 라인이 진짜 [x] 로 토글됐는가
escaped=$(printf '%s' "$item" | sed 's/[][\.*^$/]/\\&/g')
checked=true
if grep -nq "^- \[ \] ${escaped}\$" CHECKLIST.md; then
  checked=false
fi

# 검증 2 — 직전 3분 안에 git commit 이 진짜 생성됐는가
committed=true
if ! git log --oneline -1 --since="3 minute ago" | grep -q .; then
  committed=false
fi

# 두 검증의 AND 가 진척의 정의
if $checked && $committed; then
  echo "✅ iter $iter 완료 — 다음 항목으로"
else
  echo "⚠️  iter $iter 미완 (checked=$checked, committed=$committed)"
fi

코드 설명 — 두 검증이 모두 true 일 때만 iter 완료 로 판정한다. 한 가지라도 false 면 미완. 검증 1 은 CHECKLIST.md 에 그 항목이 여전히 미체크 상태로 남아있는가 를 grep 으로 본다. 남아있으면 토글 안 된 것 → checked=false. 검증 2 는 직전 3분 안에 어떤 커밋이라도 있는가 를 git log 의 --since 옵션으로 본다. 없으면 committed=false. $checked && $committed 의 AND 가 진척의 조작적 정의 가 된다.

그림 설명 — 모델 응답이 "작업 완료" 라고 보고해도 ralph-loop 는 그걸 직접 신뢰하지 않는다. 두 외부 채널 — CHECKLIST.md 의 grep 결과와 git log 의 since 결과 — 으로 실제 사실 을 확인한다. 두 채널이 모두 true 일 때만 진척으로 인정. 한 가지라도 false 면 시도 카운트가 늘어 다음 iter 에서 재시도 한다 (시리즈 7편의 dead-letter 패턴). 모델 응답 채널과 검증 채널이 물리적으로 분리 되어 있다는 게 핵심이다.

왜 검증 1 의 grep 패턴이 까다로운가

검증 1 의 한 줄을 자세히 본다.

escaped=$(printf '%s' "$item" | sed 's/[][\.*^$/]/\\&/g')
checked=true
if grep -nq "^- \[ \] ${escaped}\$" CHECKLIST.md; then
  checked=false
fi

왜 $item 을 그대로 grep 패턴에 넣지 않고 sed 로 escape 한 $escaped 를 쓰는가?

CHECKLIST 의 항목 이름에는 정규식 특수문자가 자주 포함된다.

src/main.js 부트스트랩 (DOMContentLoaded → Game 인스턴스 생성) — 괄호 (), 화살표 →
tests/collision.test.js — 6 케이스 (겹침/접점/분리/한쪽 포함 등) — 슬래시 /, 괄호
src/levels.js — LEVELS 배열 1~10 (PLAN.md 매트릭스 그대로) — 점 ., 물결 ~, 괄호

이런 항목 이름을 그대로 grep 에 넣으면 — 점은 임의 한 글자 로, 괄호는 그룹 으로, 슬래시는 delimiter 로 해석되어 매치가 잘못 된다. 예를 들어 src/main.js 의 점이 임의 문자로 해석되면 srcXmainXjs 도 매치된다. 가능성은 낮지만 — 비슷한 이름의 다른 항목이 우연히 매치되면 완료된 다른 항목을 미완으로 오판 할 수 있다.

해결은 sed 로 정규식 특수문자 5종 ([]\.*^$/) 을 모두 escape 하는 것. 's/[][\.*^$/]/\\&/g' 가 그 변환을 한 줄로 한다.

# item: src/main.js 부트스트랩 (DOMContentLoaded → Game 인스턴스 생성)
# escaped: src\/main\.js 부트스트랩 \(DOMContentLoaded → Game 인스턴스 생성\)

이렇게 escape 한 후 "^- \[ \] ${escaped}\$" 패턴으로 grep 한다. ^ 와 \$ 가 줄 시작·끝을 명시해 정확히 그 항목 줄만 매치한다. \[ 와 \] 도 바깥쪽에서 한 번 더 escape 한다 (대괄호 자체가 grep 에서 character class 라).

이 한 줄 escape 가 없으면 — 한국어 항목 이름 + 특수문자 조합에서 가끔 완료된 항목을 미완으로 또는 미완 항목을 완료로 오판하는 사고가 발생한다. 38 iter 동안 한 번도 그런 사고가 없었던 건 escape 덕이다.

왜 검증 2 의 시간 윈도우가 3분인가

검증 2 의 --since="3 minute ago" 가 또 디테일이다.

if ! git log --oneline -1 --since="3 minute ago" | grep -q .; then
  committed=false
fi

왜 3분인가? 이 숫자가 두 가지 트레이드오프 사이의 균형이다.

너무 짧으면 (예: 30초) — opencode 가 작업 시작부터 commit 까지 30초 안에 끝내야 한다. 정상 iter 도 30초 ~ 2분 사이라 30초 윈도우는 자주 false negative (실제 commit 했는데 윈도우 밖이라 미완으로 오판) 를 일으킨다.

너무 길면 (예: 30분) — 직전 iter 의 commit 을 이번 iter 의 commit 으로 오판할 수 있다. iter A 에서 commit 했고 iter B 가 시작됐을 때 30분 윈도우면 iter A 의 commit 이 검색에 잡혀 false positive (실제 commit 안 했는데 검증 통과로 오판) 를 일으킨다.

3분은 — opencode 의 정상 작업 시간 (≤2분) + 안전 마진 (1분) 이고 — iter 간 간격은 보통 2초 sleep 만 있으니 직전 iter 의 commit 이 3분 안에 끊임없이 새로 들어오진 않는 시간이다. 38 iter 운영 중 false positive / negative 모두 0이었다.

이 윈도우 시간은 작업 도메인에 따라 조정 해야 한다. 더 무거운 작업 (예: ML 모델 학습, 큰 파일 다운로드) 에 ralph-loop 패턴을 쓴다면 윈도우를 30분 또는 1시간으로 늘려야 할 수 있다. 단 그러면 false positive 위험이 생기니 — 직전 iter 의 commit hash 를 변수에 저장하고 그것과 다른 commit 만 카운트 하는 더 정밀한 방법으로 가야 한다.

검증 결과의 두 가지 분기 — 다음 항목 진행 vs 시도 카운트 누적

검증 후크 직후 두 분기다.

if $checked && $committed; then
  echo "✅ iter $iter 완료 — 다음 항목으로"
  echo "0" > "$LOG_DIR/.attempts"
  : > "$LOG_DIR/.prev_item"
else
  echo "⚠️  iter $iter 미완 (checked=$checked, committed=$committed, opencode_rc=$opencode_rc, 시도=$attempts/3)"
  if [ "$attempts" -ge 3 ]; then
    # 3-strike 자동 스킵 (시리즈 7편)
    sed -i "s|^- \[ \] ${escaped}\$|- [!] ${escaped}|" CHECKLIST.md
    git add CHECKLIST.md
    git commit -m "skip: $(printf '%s' "$item" | head -c 60) (3회 실패)" || true
    echo "  항목 자동 스킵"
    echo "0" > "$LOG_DIR/.attempts"
    : > "$LOG_DIR/.prev_item"
  fi
fi

분기 1 (성공) — 두 검증 모두 true 면 시도 카운트를 0 으로 리셋하고 prev_item 도 비운다. 다음 iter 의 첫 미체크 항목 (다른 항목) 에 대해 시도 1로 시작한다.

분기 2 (미완) — 한 가지라도 false 면 미완 메시지 출력. opencode_rc 도 함께 출력해 어떻게 미완인지 진단 정보 제공. 시도 카운트 자체는 다음 iter 시작 시점에 누적되는데 (시리즈 7편), 만약 이미 3회 누적이면 즉시 자동 스킵 처리한다.

이 분기에서 핵심은 — 검증 실패 시 곧장 ralph-loop 를 죽이지 않는다. 초창기 버전에선 검증 실패 = 즉시 exit 2 였는데, 그러면 사람이 매번 끼어들어야 한다. 자율성 0. 시도 카운트 + dead-letter 로 자동 우회 하는 패턴이 자율성을 살린다 (시리즈 7편).

왜 두 검증이 둘 다 필요한가 — 한 가지만으론 못 막는 시나리오

두 검증을 하나만 두면 안 되는 이유는 다음과 같다.

시나리오	검증 1 만 (CHECKLIST 만)	검증 2 만 (commit 만)	둘 다
모델이 CHECKLIST 토글 + commit 둘 다 함	✅	✅	✅
CHECKLIST 토글했는데 commit 누락 (escape 사고)	✅ (false positive! 진짜 미완인데 통과)	❌ 잡음	❌ 잡음
commit 했는데 CHECKLIST 토글 안 함 (작업 도중 종료)	❌ 잡음	✅ (false positive! commit 만 봐서 통과)	❌ 잡음
둘 다 안 함	❌ 잡음	❌ 잡음	❌ 잡음

두 가지 false positive 시나리오가 한 검증만 있으면 잡지 못한다. 둘 다 있어야 — 완전한 진척이라는 의미를 정확히 표현 한다.

특히 두 번째 행 (CHECKLIST 토글 + commit 누락) 이 자주 본 케이스다. 모델이 CHECKLIST 를 먼저 Edit 으로 토글하고 그 다음 git commit 시도했는데 — commit 의 shell escape 사고로 commit 자체가 깨짐. 그 결과 모델 응답에는 commit 했다고 적혀있고 CHECKLIST 도 토글됐는데 git log 에 없는 상태. 검증 1 만으로는 못 잡는다.

이 패턴의 일반화 — 외부 사실의 AND

이 검증 후크 패턴은 ralph-loop 의 작업 단위 정의에 의존한다. 우리 작업 단위는 CHECKLIST 한 항목 = 한 commit 이고, 그래서 검증할 외부 사실이 정확히 두 가지다. 다른 도메인이라면 다르다.

DB 마이그레이션 자동화: 검증 = (1) 스키마 버전 테이블이 새 버전으로 업데이트됐는가 + (2) 마이그레이션 스크립트가 실행 로그에 박혔는가 + (3) 새 컬럼/테이블이 실제로 존재하는가 (3개 사실)
인시던트 자동 대응: 검증 = (1) 알람 상태가 resolved 로 바뀌었는가 + (2) post-mortem 문서가 생성됐는가 + (3) 관련 메트릭이 정상 범위로 돌아왔는가
코드 리뷰 자동화: 검증 = (1) PR 의 review status 가 approved/changes_requested 인가 + (2) 인라인 comment 가 N개 이상 달렸는가

핵심은 — "작업 완료" 의 의미를 모델 응답 텍스트가 아니라 외부 시스템의 실제 상태로 정의 하는 것. 그 외부 사실들의 AND 가 진척의 조작적 정의가 된다.

모델 응답을 전혀 안 보는 건 아니다

오해를 또 하나 풀어둔다. ralph-loop 가 모델 응답을 무시하는 건 아니다. 응답을 .ralph-logs/iter-N.log 파일에 모두 저장하고, 사용자가 사후에 읽을 수 있다. 디버깅, 패턴 분석, 모델 성능 평가에 다 쓴다.

응답을 진척 판정의 기준으로 쓰지 않는다 가 정확한 표현이다. 응답은 모델이 무엇을 시도했는지의 기록 이고, 외부 검증은 그 시도가 시스템에 영구적으로 박혔는지의 사실 이다. 두 정보가 다르면 — 응답은 보존하지만 진척으로는 안 잡는다.

이 분리가 운영 시 모델 행동 분석 과 진척 판정 이라는 두 일을 동시에 가능하게 한다. 응답 로그를 grep 해서 "prompt 강화 후 모델이 도구 호출 재시도를 더 자주 하나" 같은 질문에 답할 수 있고, 진척 통계는 외부 사실에 박힌 진짜 결과만 카운트한다.

결론 — "신뢰하지 마라, 검증하라"

이 글의 한 문장 결론 — 자율 시스템에서 모델 응답은 시도의 기록 이지 결과의 보고 가 아니다. 결과는 외부 시스템의 사실에서 검증해야 한다.

이건 모델을 의심하는 게 아니라 — 모델이 시도한 일이 어딘가에서 실패할 가능성을 인정 하는 거다. shell escape 사고, 도구 호출 schema 에러, 응답 토큰 limit, vLLM 자살 — 모두 모델 책임 밖의 layer 에서 일어나는 일인데 결과는 모델이 거짓 보고한 것처럼 보인다. 외부 검증이 그 모든 layer 의 실패를 결과 기준으로 일관되게 잡는다.

또 — 외부 검증이 진척 통계의 진실 이 된다는 점도 중요하다. 시리즈 7편에서 다룰 진척률의 거짓말 함정 — 스킵을 진척으로 카운트하면 80% 가 보이지만 실제론 32% 인 사고 — 가 외부 검증 없이 모델 응답만 신뢰하면 더 자주 발생한다. 외부 검증은 진척의 정의 자체를 외부 사실에 묶어서 그 함정을 피한다.

두 줄 grep 으로 가능한 신뢰 시스템이라는 게 — 처음엔 단순해 보이지만 — 그 단순함 안에 AI 응답을 신뢰하지 않는다는 운영 원칙 이 깔끔하게 박혀있다. 자율 시스템 디자인의 핵심이다.

이 글은 생성형 AI의 도움을 받아 작성되었습니다. 원본 자료를 기반으로 AI가 초안을 생성하고, 작성자가 검토·편집하였습니다.

opencode 한 줄 호출에 숨은 3가지 함정 — `--` 구분자, 5분 timeout, 직후 헬스체크 (Ralph Loop 시리즈 5편)

타이젠 개발자, 윤진 — Sun, 17 May 2026 22:00:59 +0900

자율 코딩 루프의 핵심은 결국 외부 CLI 한 줄 호출 이다. opencode run --model X -f file1 -f file2 -- "<prompt>" 라는 한 줄. 그런데 이 한 줄에 세 가지 함정 이 숨어있어 ralph-loop 를 짜면서 모두 한 번씩 부딪혔다. 함정마다 한 번씩 사고를 겪고 한 줄씩 추가해서 — 이제는 안전한 호출이 됐다.

이 글은 그 한 줄의 진화를 따라간다. (1) yargs 의 -f array 가 prompt 를 삼키는 함정, (2) vLLM 응답 hang 시 무한 대기를 끊는 timeout, (3) opencode 호출 직후 vLLM 죽음 감지하는 헬스체크. 시리즈 5편이고, 1~4편은 컨텍스트 3축, 부팅·셧다운, vLLM 헬스 보장, prompt 다층 메시지를 다뤘다.

최종 형태 — 그 한 줄

먼저 결과물부터 보자. ralph-loop.sh 안에서 opencode 를 부르는 부분이다.

# prompt 크기 측정 (vLLM 죽음 트리거 분석용)
prompt_size=$(printf '%s' "$prompt" | wc -c)
echo "   prompt: ${prompt_size} chars | CHECKLIST: $(wc -c < CHECKLIST.md) chars"

# `--` 구분자로 -f array 파서가 prompt 를 삼키는 것 방지
# timeout 300 — vLLM 죽음 등으로 응답 hang 시 5분 후 강제 종료 (124 반환)
opencode_rc=0
timeout 300 opencode run \
      --model "$MODEL" \
      -f PLAN.md \
      -f CHECKLIST.md \
      -- "$prompt" 2>&1 | tee "$log" || opencode_rc=$?
if [ "$opencode_rc" -eq 124 ]; then
  echo "⏱  opencode 5분 timeout — vLLM 응답 hang 의심, 다음 iter 로 진행"
fi

# opencode 직후 vLLM 죽음 감지 — 죽었다면 직전 prompt 크기와 함께 진단 캡처
if ! curl -sS --max-time 3 "$VLLM_BASE_URL/models" > /dev/null 2>&1; then
  echo "  opencode 호출 직후 vLLM 죽음 감지"
  ensure_vllm_alive "$iter (post-opencode)" "$item" "$prompt_size" || {
    echo "❌ 재기동 불가 — 루프 중단"
    exit 4
  }
fi

이 17줄이 함정 셋의 답이다. 한 줄씩 처음부터 어떻게 진화했는지 보자.

함정 1 — yargs `-f` array 가 prompt 를 삼킨다

처음 시도한 호출은 단순했다.

opencode run \
      --model "$MODEL" \
      -f PLAN.md \
      -f CHECKLIST.md \
      "$prompt"

실행하면 즉시 에러가 났다.

Error: File not found: 당신은 PLAN.md 의 설계를 따라 car-game 을 구현하는 자율 에이전트다.

## 컨텍스트
- **PLAN.md (불변)**: 첨부됨. 절대 수정 금지.
...

모델한테 던지려던 prompt 가 "File not found: ..." 의 파일 경로로 해석된 것이다. 처음엔 이게 왜 그런지 몰랐다 — opencode 의 --help 출력에 따르면 -f 가 file 첨부 옵션이고 마지막은 message positional argument 라 명시되어 있었다. 직관대로면 동작해야 하는데.

원인은 opencode 가 내부적으로 yargs 라는 Node.js 인자 파서를 쓰는데, yargs 의 -f 같은 array 옵션 이 연이은 positional argument 까지 모두 흡수 하는 동작이 default 라는 거였다. opencode run --help 로 확인:

  -f, --file  file(s) to attach to message  [array]

이 [array] 가 핵심. yargs 는 이 옵션 뒤에 오는 모든 인자 — 다른 옵션 (--xxx) 또는 명시적 끝 표시 (--) 를 만나기 전까지 — 를 array 에 넣는다. 우리 호출에서:

opencode run --model X -f PLAN.md -f CHECKLIST.md "$prompt"
                          └────────────┴──────────────┘ ← -f 배열에 다 들어감

즉 "$prompt" 가 마지막 -f 의 세 번째 file 인자 로 해석돼 그 prompt 텍스트를 파일로 읽으려다 실패 한 것이다.

해결은 yargs 의 표준 명시적 끝 표시 --. POSIX 셸 호출 컨벤션에서 -- 뒤는 옵션이 아닌 positional 이라는 표시다.

opencode run \
      --model "$MODEL" \
      -f PLAN.md \
      -f CHECKLIST.md \
      -- "$prompt"   ← 이 한 줄이 핵심

-- 가 yargs 에게 "여기까지가 옵션, 다음은 positional" 을 명시한다. 그러면 -f array 는 PLAN.md 와 CHECKLIST.md 에서 멈추고 "$prompt" 가 정확히 message positional 로 들어간다.

그림 설명 — 같은 명령에 -- 한 단어가 들어가고 안 들어가고의 차이가 prompt 가 message 로 가느냐 file 경로로 해석되느냐 다. yargs 의 array 옵션은 다음 옵션 (--xxx) 또는 -- 를 만날 때까지 인자를 계속 흡수하는데, 그 사이에 positional argument 가 끼어있으면 그것까지 array 에 넣는다. -- 한 줄로 흡수가 멈춘다. 이게 yargs 만의 동작이 아니라 POSIX 인자 파싱 컨벤션 이라 — Python argparse 도, Go cobra 도, Rust clap 도 같은 동작을 한다.

함정 2 — vLLM 응답 hang 시 무한 대기

두 번째 함정은 한 시간 동안 ralph-loop 가 진척 0인 채로 멈춰있던 사고에서 알게 됐다. 그 시점 vLLM 컨테이너는 죽어있었고 (시리즈 3편의 KV cache assertion 자살), 그 사이 opencode 가 죽은 endpoint 에 호출을 던지고 있었다. opencode 는 http://localhost:8000/v1/chat/completions 에 POST 했는데 OS 레벨에서 connection 이 거부되거나 timeout 응답이 매우 느렸다.

관찰된 패턴은 — opencode 가 응답 시작은 받았지만 (TCP 핸드셰이크 + 첫 chunk 정도) 모델 응답이 끊겨서 무한 대기 상태가 됐다. opencode 자체에 timeout 설정이 없으면 "streaming response 가 끝날 때까지 대기" 가 default 다. 응답이 영영 안 오면 영영 대기.

해결은 외부에서 강제 timeout 을 거는 것 — bash 의 timeout 명령을 사용하는 방법이다.

timeout 300 opencode run \
      --model "$MODEL" \
      -f PLAN.md \
      -f CHECKLIST.md \
      -- "$prompt" 2>&1 | tee "$log" || opencode_rc=$?

if [ "$opencode_rc" -eq 124 ]; then
  echo "⏱  opencode 5분 timeout — vLLM 응답 hang 의심"
fi

timeout 300 은 5분 안에 끝나지 않으면 SIGTERM 을 던진다. opencode 가 SIGTERM 받으면 즉시 종료하고 timeout 명령은 종료 코드 124 를 반환한다. ralph-loop 의 다음 검증 후크 (시리즈 6편) 가 "opencode 가 비정상 종료했고 CHECKLIST 토글도 안 됐다" 로 잡아 시도 카운트를 누적하고, 3-strike 후 자동 스킵 (시리즈 7편) 한다.

왜 5분(300초) 인가? 정상 iter 는 30초~2분 사이에 끝났다. 가장 무거운 작업 (테스트 작성 + 도구 호출 다수) 도 3분 안. 5분이면 정상 작업의 안전 마진 + 외부 자원이 살아있다면 회복할 마지막 시간 이다. 더 짧으면 정상 작업이 잘리고, 더 길면 죽은 vLLM 에 너무 오래 매달린다.

함정 3 — opencode 직후 vLLM 죽음 감지

세 번째 함정은 미묘하다. timeout 으로 hang 은 막았는데, opencode 가 정상 종료 했지만 그 호출 도중 vLLM 이 죽은 케이스가 있었다. 우리가 던진 prompt 가 vLLM 의 KV cache assertion 을 트리거했고, vLLM 이 죽기 직전 일부 응답을 client 에 흘려보냈다. opencode 는 짧은 응답이라도 받았으니 정상 종료했고, 우리 검증 후크는 그 응답이 부족해서 미체크/미커밋 상태로 시도 카운트만 늘렸다.

문제는 — 그 시점에 vLLM 이 죽은 줄 모르고 다음 iter 가 시작되면 — 그 iter 의 시작 헬스체크 (ensure_vllm_alive) 가 죽음을 감지하긴 하지만, 어느 prompt 가 죽음을 일으켰는지 의 인과 정보가 사라진다. 죽음의 prompt 크기를 진단 로그에 남길 수 없게 된다.

해결은 — opencode 호출 직후 즉시 vLLM 헬스를 한 번 더 체크하고, 죽었다면 그 시점에 진단을 캡처하는 것이다.

# opencode 직후 vLLM 죽음 감지 — 죽었다면 직전 prompt 크기와 함께 진단 캡처
if ! curl -sS --max-time 3 "$VLLM_BASE_URL/models" > /dev/null 2>&1; then
  echo "  opencode 호출 직후 vLLM 죽음 감지"
  ensure_vllm_alive "$iter (post-opencode)" "$item" "$prompt_size" || {
    echo "❌ 재기동 불가 — 루프 중단"
    exit 4
  }
fi

핵심은 ensure_vllm_alive 의 세 번째 인자로 $prompt_size 를 넘기는 것. 이게 진단 로그의 "직전 prompt 크기" 항목으로 박혀, 사후 분석 시 "prompt 가 N chars 였을 때 vLLM 이 죽음" 의 인과를 추적 가능하게 한다.

iter 시작 시점의 헬스체크와 opencode 직후 헬스체크는 같은 함수를 호출하지만 context 인자가 다르다. iter 시작 호출은 "$iter" 만 넘기고, opencode 직후 호출은 "$iter (post-opencode)" 와 prompt_size 를 함께 넘긴다. vllm-deaths.log 만 봐도 어느 단계에서 죽었는지 즉시 구분된다.

그림 설명 — 헬스체크 1 (iter 시작 시점) 만 있으면 외부 요인으로 vLLM 이 이미 죽어있는 케이스 만 감지한다. opencode 호출 도중 자살한 케이스는 다음 iter 의 헬스체크 1 에서야 감지되는데, 그 시점에는 어느 호출이 트리거였는지 알 길이 없다. 헬스체크 2 (opencode 직후) 가 그 인과 단절을 막는다. 같은 함수를 두 번 호출하는데 — 위치가 다르면 잡는 정보가 다르다.

왜 외부 timeout + 직후 헬스가 모두 필요한가

이 두 안전망이 같이 있어야 한다. 한 가지만 있을 때 막지 못하는 시나리오가 각각 있다.

시나리오	timeout 만 있을 때	직후 헬스 만 있을 때	둘 다 있을 때
vLLM 죽고 opencode hang	✅ 5분 후 timeout	❌ opencode 가 안 끝나서 헬스 호출 못 감	✅ timeout 후 헬스로 죽음 캡처
vLLM 죽고 opencode 정상 종료 (짧은 응답)	❌ timeout 안 발동, 인과 정보 사라짐	✅ 즉시 죽음 감지 + prompt 캡처	✅ 직후 헬스가 잡음
vLLM 살아있고 opencode 작업 정상	✅ 정상 종료	✅ 헬스 OK 즉시 return	✅ 둘 다 통과
vLLM 살아있는데 opencode 자체 hang (드물지만)	✅ 5분 후 timeout	❌ opencode 가 안 끝남	✅ timeout 발동 후 헬스도 OK

어느 한 가지 안전망만으론 모든 케이스를 덮지 못한다. 두 안전망이 직교 한다 — timeout 은 시간 차원 (얼마나 오래 기다렸나), 직후 헬스는 상태 차원 (지금 의존성이 살아있나) 을 본다. 시리즈 7편의 시도 카운트가 반복 차원 의 안전망이라면, 이 둘은 그 앞단의 두 차원이다.

왜 prompt_size 를 호출 직전에 미리 측정하나

코드에 한 가지 디테일이 더 있다 — opencode 호출 직전 에 prompt_size 를 변수에 박는다.

# prompt 크기 측정 (vLLM 죽음 트리거 분석용)
prompt_size=$(printf '%s' "$prompt" | wc -c)
echo "   prompt: ${prompt_size} chars | CHECKLIST: $(wc -c < CHECKLIST.md) chars"

opencode_rc=0
timeout 300 opencode run ...

왜? opencode 호출 도중 vLLM 이 죽으면 prompt 변수 값을 그 시점에 읽을 수 없을 수도 있어서 다. bash 의 변수는 같은 셸 프로세스 안에서는 안전하지만 — 만약 ralph-loop 가 SIGKILL 같은 비정상 종료를 당하고 다시 시작되면 그 사이 prompt 값이 사라진다. 미리 echo 로 출력하면 stdout 또는 log 파일에 박혀 영구적이다.

또 한 가지 — echo 로 stdout 에 미리 출력하면 cron 보고나 로그 추적 시 이 iter 의 prompt 크기가 즉시 보인다. 운영 중 어느 iter 에서 prompt 가 갑자기 커졌나 같은 질문을 빠르게 답할 수 있다.

echo 와 stdout 통합 — `2>&1 | tee`

마지막 작은 디테일. opencode run ... 2>&1 | tee "$log" 의 의미는 이렇다.

2>&1 — stderr 를 stdout 으로 합친다. opencode 가 에러를 stderr 로 보내도 모두 한 stream 으로 모임
| tee "$log" — 그 stream 을 화면에도 출력하고 동시에 $log 파일에 저장
|| opencode_rc=$? — opencode 가 0이 아닌 코드로 종료해도 즉시 죽지 않고 exit code 를 변수에 저장

이 조합이 두 가지를 보장한다 — (1) 사용자가 화면에서 실시간으로 진행 보면서 동시에 로그에도 영구 저장, (2) set -e 가 활성화돼있어도 opencode 의 비정상 종료가 ralph-loop 를 죽이지 않게 한다 (검증 후크가 그 결과를 처리하도록).

특히 set -e 와 || opencode_rc=$? 의 조합이 중요. set -e 는 어느 명령이든 0이 아닌 코드로 종료하면 즉시 죽는데, opencode 가 도구 호출 schema 에러 등으로 비정상 종료하는 건 예상된 실패 다. || ... 가 없으면 ralph-loop 자체가 그 자리에서 죽고 cleanup → exit. 그러면 자동 스킵이나 시도 카운트 같은 dead-letter 처리가 작동 못 한다. || opencode_rc=$? 한 줄이 예상된 실패를 ralph-loop 안에서 처리 하는 길을 만든다.

결론 — 한 줄 호출의 17줄짜리 답

opencode 한 줄 호출이 17줄로 늘어난 게 과도해 보일 수 있다. 그런데 각 줄이 한 가지 실패 시나리오에 대한 답이다.

-- ← yargs -f array 함정
timeout 300 ← vLLM 응답 hang 무한 대기
2>&1 | tee ← 화면 + 로그 동시
|| opencode_rc=$? ← set -e 와 예상된 실패 분리
if rc -eq 124 ← timeout 발동 시 사용자 알림
opencode 직후 헬스 + ensure_vllm_alive ← 자살 감지 + 인과 캡처
prompt_size 미리 echo ← 운영 추적성 + 진단 인자 보존

각 줄이 한 사고에서 한 줄씩 추가됐다 — 처음부터 이렇게 짠 게 아니다. ralph-loop.sh 의 git log 를 따라가면 각 줄이 추가된 commit 과 그 commit 메시지가 어떤 사고에 대한 대응이었나 를 보여준다 (시리즈 9편 통합편 주제).

외부 CLI 한 줄을 자율 시스템 안에서 안전하게 부르려면 — 그 CLI 의 인자 파서 동작 / 응답 시간 / 의존성 살아있나 / exit code 의미 / 출력 stream / 예상된 실패와 진짜 실패의 구분 — 이 모두를 명시적으로 처리해야 한다. 간단한 한 줄 이라는 환상은 운영 중 사고 한 번이면 깨진다.

이 글은 생성형 AI의 도움을 받아 작성되었습니다. 원본 자료를 기반으로 AI가 초안을 생성하고, 작성자가 검토·편집하였습니다.

프롬프트만으로는 못 고친다 — 도구 가이드를 5단으로 줘도 schema 에러는 그대로였다 (Ralph Loop 시리즈 4편)

타이젠 개발자, 윤진 — Sun, 17 May 2026 21:00:01 +0900

자율 코딩 루프를 짜면서 가장 답답했던 시기는 모델이 도구 호출 시 필수 필드를 빠뜨리는 schema 에러 가 매 iter 평균 3.7회 발생하던 때였다. filePath 누락 43회, description 누락 26회, content 누락 23회. 가장 기본적인 식별자조차 빠뜨리는 모델 을 두고 처음엔 prompt 가이드로 해결할 수 있다고 믿었다. 그래서 prompt 안에 도구 사용 필수 사항을 5단으로 명시했다 — Bash 도구의 두 필드, Edit 도구의 세 필드, Write 도구의 두 필드, commit 메시지 형식, 실패 시 즉시 재시도 명령. 결과는 — 효과가 사실상 0이었다.

이 글은 ralph-loop.sh 의 prompt 템플릿이 어떻게 수행 순서 + 도구 사용 가이드 + 제약 조건 의 세 영역으로 짜여있는지 분해한다. 그리고 도구 가이드라는 한 영역이 왜 효과가 없었는지 — 프롬프트 엔지니어링의 한계 를 직접 부딪힌 경험을 본다. 시리즈 4편이고 1~3편은 컨텍스트 3축, 부팅·셧다운, vLLM 헬스 보장을 다뤘다.

출발점 — 한 prompt 에 무엇을 담아야 하는가

매 iter 마다 새 opencode 세션이라 — 모델은 PLAN 첨부 + CHECKLIST 첨부 + git 인라인 + 그리고 prompt 자체 에서 모든 컨텍스트를 새로 받는다. prompt 가 한 줄짜리 "다음 항목 1개 구현해" 라면 모델이 알아서 한다고 가정하는 거다. 하지만 그 가정은 부서졌다.

모델이 매번 다른 행동을 했다 — 어떤 iter 는 PLAN 을 다 읽고 시작했고, 어떤 iter 는 그냥 작업부터 시도했다. 어떤 iter 는 commit 메시지를 영문으로 한 줄로 깔끔하게 적었고, 어떤 iter 는 다줄 한국어 메시지에 큰따옴표 escape 사고로 commit 자체가 깨졌다. 어떤 iter 는 도구 호출을 정확히 했고, 어떤 iter 는 필드 누락 에러를 5번 연속 던지고 포기했다.

변동성을 줄이려면 prompt 가 수행 순서를 명시 해야 했다. 단순한 "1개 구현해" 가 아니라 — git log 부터 보고, 디렉토리 구조 확인하고, 한 항목만 구현하고, 테스트 작성하고, vitest 돌리고, CHECKLIST 토글하고, commit 한다 — 의 7단계 흐름이다.

prompt 의 3영역 구조

최종 정착한 prompt 템플릿은 200줄 정도. 그 구조를 추상화하면 세 영역이다.

그림 설명 — prompt 가 위에서 아래로 ① 컨텍스트 ② 수행 순서 ③ 도구 가이드+제약 의 세 영역으로 흐른다. 영역 ①은 불변/가변/실측 3축의 형태를 모델에게 명시하는 부분 (1편 주제). 영역 ② 는 변동성 줄이기 를 위한 7단계 절차. 영역 ③ 은 도구 호출 시 필드 누락 방지 + 제약 조건. 세 영역이 같은 prompt 안에 있지만 효과는 천양지차였다 — ② 는 효과 있음, ③ 은 효과 거의 0. 색깔이 그 효과 차이를 표현한다 (녹색 계열은 효과적, 빨강 계열은 거의 무용).

영역 ② 수행 순서 — 효과가 있었던 부분

수행 순서를 명시한 것은 효과가 있었다. 7단계로 명시한 prompt 가 적용된 후 모델 행동의 변동성이 눈에 띄게 줄었다.

## 수행 순서
1. 먼저 `git log --oneline -5` 와 `git diff HEAD~1` 로 직전 iter 의 변경을 파악한다.
2. `ls -la src/ tests/ 2>/dev/null` 등으로 PLAN.md 의 목표 디렉토리 구조 대비
   현재 상태를 확인한다.
3. 위 작업 항목을 **하나만** 구현한다 (다른 미체크 항목은 건드리지 않는다).
4. 코드 변경 시 관련 단위 테스트를 같은 iter 에 작성/갱신한다 (TDD).
5. 테스트가 있으면 `npx vitest run` 으로 통과 확인 (실패 시 고친다).
6. 작업 완료 후 CHECKLIST.md 의 line $line_num 을 `- [ ]` → `- [x]` 로 변경한다.
7. 작업 중 PLAN.md 에 없던 새 요구사항을 발견하면 CHECKLIST.md 끝에
   `- [ ] <새 항목>` 으로 자유롭게 추가한다.
8. `git add -A && git commit -m 'feat: <한 줄 요약>'` 로 커밋한다.

왜 이게 효과가 있었나? 추측건대 — 수행 순서는 모델의 의사결정 영역이다. "git log 부터 봐라" 는 명령은 모델이 응답 생성 시점에 자기 행동 계획을 짜는 단계에 영향을 준다. 모델이 응답을 "네, 시작합니다. 먼저 git log 를 봅니다." 로 시작하는 패턴이 38 iter 중 80% 이상 관찰됐다. 즉 prompt 의 영역 ②는 모델의 chain-of-thought 에 직접 박혀 작동한다.

영역 ③ 도구 가이드 — 효과가 0이었던 부분

같은 prompt 의 다음 영역인 도구 가이드는 그렇지 않았다.

## 도구 사용 필수 사항 (매우 중요)
opencode 의 도구 호출 시 모든 필수 필드를 빠짐없이 채워라. SchemaError 가
발생하면 누락 필드를 추가해 **즉시 재시도**한다 — 절대 포기하지 마라.

- **Bash 도구**: `{ "command": "...", "description": "한 줄 설명" }` 두 필드 모두 필수.
- **Edit 도구**: `{ "filePath": "...", "oldString": "...", "newString": "..." }` 세 필드 모두 필수.
- **Write 도구**: `{ "filePath": "...", "content": "..." }` 두 필드 모두 필수.
- **git commit 메시지**: `git commit -m '메시지'` 처럼 **작은따옴표 단일 인수**를 사용하라.
  큰따옴표 안에 줄바꿈/특수문자가 들어가면 셸 escape 사고가 잦다.

도구 호출이 한 번 실패해도 멈추지 마라. 누락 필드를 채워 다시 호출하라.

이 가이드를 prompt 에 박은 후 30 iter 의 schema 에러를 다시 카운트했다. 결과:

에러 종류	가이드 적용 전 (10 iter 평균)	가이드 적용 후 (10 iter 평균)
`filePath` 누락	1.4회/iter	1.4회/iter
`description` 누락	0.9회/iter	0.8회/iter
`content` 누락	0.8회/iter	0.8회/iter
`oldString` 누락 / 매치 실패	0.4회/iter	0.4회/iter

차이가 통계적 노이즈 수준 이다. 가이드를 5단으로 명시했는데도 누락 빈도가 거의 같았다. 모델이 응답 텍스트로는 "Edit 도구는 filePath/oldString/newString 세 필드 모두 필수" 를 인지한 듯한 메시지를 출력하기도 했지만 — 정작 다음 호출에서 또 필드를 빠뜨렸다.

왜 효과가 없었나? 이 부분이 결국 시리즈 8편(별도 글) 의 주제다. 짧게 결론만 — "필드 누락" 자체가 모델의 직접적 실수가 아니었다. 진짜 원인은 vLLM 의 qwen3xml tool parser 가 streaming chunk 를 파싱하다가 모델 출력의 XML 형식 위반에 부딪혀 ValueError 를 던지는 거였고, 그 결과 부분 파싱된 tool_call JSON 이 클라이언트에 도달했다. opencode 가 보기엔 "필드 누락" 이지만 모델이 보기엔 "내가 필드 다 적었는데 vLLM 이 끊어 보낸 것" 이었다. 그래서 prompt 로 모델 행동을 바꿔도 — 모델 출력은 그대로인데 그 다음 layer 인 vLLM 파서에서 깨지니 — 효과가 없었다.

핵심 발견 — prompt 가 미치는 layer 와 미치지 못하는 layer

이 경험에서 정리된 일반화는 — prompt 는 모델의 의사결정 layer 만 통제할 수 있고, 그 너머 layer 는 못 닿는다.

그림 설명 — prompt 의 영향력이 어느 layer 까지 닿는지 시각화한 것이다. Layer 1 (모델의 의사결정·계획·chain-of-thought) 까지는 prompt 의 명시적 지시가 효과를 발휘한다. 하지만 Layer 2 (모델이 생성하는 토큰 시퀀스의 형식 — XML 태그 위치, streaming chunk 분할 시점), Layer 3 (vLLM 의 tool parser 가 그 형식을 어떻게 파싱하는지), Layer 4 (클라이언트가 받은 결과를 어떻게 해석하는지) 는 prompt 가 닿지 못하는 영역이다. 우리는 그 단순한 사실을 30 iter 의 schema 에러를 겪고서야 깨달았다.

실패한 prompt 가 가르쳐준 것 — "도구 가이드를 줘봐야"

도구 가이드 영역을 prompt 에 박은 게 헛수고였나? 완전히 그렇진 않다. 두 가지 가치가 있었다.

첫째, 가이드가 효과 없다는 사실을 데이터로 확정 했다. 만약 가이드를 안 주고 schema 에러가 평균 3.7회였다면 — 그 원인이 prompt 가 부족해서 인지 모델 능력이 부족해서 인지 알 길이 없다. 가이드를 주고도 같은 빈도면 — 분명히 prompt 너머의 layer 에 원인이 있다는 증거가 된다. 잘못된 가설을 빨리 기각한 셈이다.

둘째, 막힌 후의 재시도 명령 은 일부 효과 있었다. "도구 호출 한 번 실패해도 멈추지 마라. 누락 필드 채워 다시 호출하라" 라는 부분. 이게 없을 때는 모델이 1회 SchemaError 후 응답을 끝내는 패턴이 흔했는데, 명시한 후엔 같은 호출을 2~3번 재시도하는 패턴이 자주 나타났다. 재시도 자체가 schema 에러를 줄이진 못했지만 — 작업의 깊이 는 늘어났다 (한 호출 실패로 끝나지 않고 다른 접근으로 시도). 이 부분은 Layer 1 (의사결정) 에 영향을 준 셈이다.

진짜 답 — vLLM 의 한 줄 변경

schema 에러를 진짜로 고친 건 prompt 가 아니라 vLLM 의 --tool-call-parser 옵션 변경이었다. qwen3_xml → qwen3_coder 한 줄이었다.

# Before — schema 에러 평균 3.7회/iter
VLLM_EXTRA_ARGS=... --tool-call-parser qwen3_xml ...

# After — schema 에러 0회/iter
VLLM_EXTRA_ARGS=... --tool-call-parser qwen3_coder ...

이 변경 후의 다음 30 iter 에서 schema 에러가 완전히 사라졌다. prompt 의 도구 가이드는 아무것도 안 바꿨다. 즉 같은 모델, 같은 prompt, 같은 클라이언트 — vLLM 측 한 줄만 바꿨는데 결과가 정반대가 됐다.

이건 프롬프트 엔지니어링이 무용하다 는 게 아니라 — 프롬프트로 풀 문제와 인프라로 풀 문제를 구분하는 안목 이 결정적이라는 거다. 우리가 30 iter 동안 prompt 만 만지작거린 시간은 사실상 낭비였다. vLLM 의 tool parser 옵션을 일찍 의심했다면 시간을 훨씬 아꼈을 것이다.

그러면 prompt 의 도구 가이드를 빼야 하나

고민했다. qwen3_coder 로 바꾼 후 schema 에러가 0이 됐으니 prompt 의 도구 가이드 영역은 더 이상 의미 없는 거 아닐까?

그래도 빼지 않았다. 두 가지 이유로:

안전망 — 향후 다른 모델 (Qwen 3.7, 4.0 등) 또는 다른 vLLM 버전에서 또 다른 형식의 schema 에러가 날 수 있다. 그때 prompt 의 가이드가 최소한의 안전장치 가 된다. 효과가 작아도 0은 아니다.
"실패 시 즉시 재시도" 의 가치 — Layer 1 에 영향을 주는 부분이라 schema 에러 외 다른 종류의 도구 호출 실패에서도 도움이 된다. 예를 들어 oldString 매치 실패 같은 케이스 (Edit 의 oldString 이 파일에 없는 경우) — 이건 prompt 의 재시도 명령으로 모델이 다시 파일을 읽고 정확한 oldString 을 추출하는 패턴이 자주 작동한다.

즉 prompt 의 도구 가이드는 주된 효과는 없지만 부수적 가치는 있는 영역이라 그대로 두는 게 합리적이다. 시리즈 8편에서 다룰 내용이지만 — 이 명목상의 가이드 + 실제 효과는 인프라 변경 패턴은 자율 시스템 디버깅에서 자주 만나는 구조다.

결론 — prompt 엔지니어링의 경계 인식

이 글의 한 문장 결론 — prompt 가 어디까지 닿는지 알아야 어디서 멈추고 인프라를 만져야 하는지 안다. prompt 는 모델의 의사결정·계획에 영향을 미치지만, 모델이 생성하는 토큰의 형식적 구조나 그 다음 layer 의 파싱·해석에는 닿지 못한다.

그래서 자율 시스템 운영에서는 layer 별 진단 이 결정적이다. 보고된 증상이 "schema 에러" 라고 prompt 부터 만지작거리는 게 아니라 — 어느 layer 에서 진짜 문제가 발생하는지 한 단계씩 추적해야 한다. 우리 경우는 클라이언트(opencode) 가 보고한 "필드 누락" 이 사실은 vLLM 파서의 streaming chunk 처리 실패였고, 그건 prompt 와 무관하게 인프라 한 줄 변경으로 해결됐다.

그럼에도 prompt 의 영역 ② (수행 순서) 는 효과가 있었다 — 모델 의사결정 layer 에 직접 박혀 작동했다. prompt 가 무용하다 가 아니라 — 어느 layer 에서 효과가 있고 어느 layer 에서 한계가 있는지 를 명확히 아는 게 중요하다.

이 글은 생성형 AI의 도움을 받아 작성되었습니다. 원본 자료를 기반으로 AI가 초안을 생성하고, 작성자가 검토·편집하였습니다.

vLLM 이 매 iter 도중 자살할 수 있다 — 헬스 보장과 진단 자산을 한 함수에 (Ralph Loop 시리즈 3편)

타이젠 개발자, 윤진 — Sat, 16 May 2026 23:00:37 +0900

장기 실행 자율 스크립트의 가장 짜증나는 실패 모드는 의존성 서비스가 도중에 죽고 우리는 한참 후에 알아차리는 케이스다. Ralph Loop 를 돌리던 어느 날, 30분간 진척이 0이 되어 의아해하다가 발견했다 — vLLM 이 KV cache 의 off-by-one assertion 으로 자살하고 docker compose 의 restart: "no" 정책 때문에 자동 재기동이 안 되어 컨테이너가 죽은 채로 방치된 상황이었다. 그동안 opencode 는 죽은 endpoint 에 호출을 던지고 5분 timeout 으로 종료하기를 반복하고 있었다.

이 글은 그 이후 추가한 ensure_vllm_alive() 함수 — 매 iter 시작 시 + opencode 직후에 vLLM 헬스를 확인하고, 죽었으면 진단을 캡처한 뒤 자동 재기동하는 한 함수 — 를 다룬다. 단순한 헬스체크가 아니라 장애 발생 시점의 운영 상태를 한 번에 누적 해서 사후 분석 자산으로 만드는 패턴이 핵심이다. 시리즈 3편이고, 1편은 컨텍스트 3축, 2편은 부팅·셧다운 lifecycle 을 다뤘다.

왜 시작 헬스체크 한 번으로 안 되는가

2편에서 ralph-loop 가 부팅 시 GPU acquire → vLLM 기동 → 헬스체크 의 3단계를 거친다고 했다. 그 헬스체크가 통과하면 곧바로 메인 루프에 들어가 opencode 를 호출한다. 처음엔 이걸로 충분하다고 생각했다 — 한 번 띄운 vLLM 이 한 사이클 동안은 살아있을 거라고 가정한 것.

그런데 vLLM v019 의 v1 엔진에는 긴 컨텍스트 + 특정 토큰 패턴 조합에서 KV cache 매니저가 off-by-one assertion 을 던지고 EngineCore 가 죽는 알려진 버그가 있었다. 우리 prompt 가 매 iter 마다 PLAN.md (5.8KB) + CHECKLIST.md (점점 커짐) + git log + 시스템 프롬프트 + 도구 설명 으로 늘어나면서 어느 임계점에서 이 버그를 트리거했다. 두 번 죽음을 관찰했다 — 한 번은 09:48 (24 < 25), 한 번은 10:46 (25 < 26). 매번 정확히 +1 차이의 off-by-one 패턴.

EngineCore 가 죽으면 APIServer 가 따라 종료하면서 컨테이너가 정상 종료(Exit 0)된다. 그런데 우리 docker-compose.yml 의 restart: "no" 가 자동 재기동을 막는다. 컨테이너는 죽고, GPU 스케줄러의 lock 은 여전히 살아있다. 즉 lock 은 점유 중이라고 보고하지만 실제 컨테이너는 죽어있는 desync 상태 가 생긴다.

opencode 입장에서 endpoint 에 요청을 보내면 connection 자체는 OS 레벨에서 거부되거나 timeout 이 떨어진다. opencode 는 그걸 일반 응답 실패로 처리하고 stdout 에 짧은 에러를 출력한 뒤 종료한다. ralph-loop 의 검증 후크가 미체크/미커밋을 잡아 시도 카운트를 증가시키지만, 같은 항목으로 3-strike 가 발동해 자동 스킵 되어버린다. 결과적으로 vLLM 이 죽어있는 채로 ralph-loop 는 계속 돌면서 모든 항목을 허위 스킵 처리하는 사고가 발생한다.

해결은 단순했다 — 매 iter 시작 시 vLLM 헬스를 다시 확인하고, 죽었으면 즉시 재기동. 그리고 이왕 헬스체크 함수를 만드는 김에 죽음의 진단 정보까지 함께 캡처 하는 게 더 큰 가치였다.

핵심 함수 — `ensure_vllm_alive()` 의 3단 구조

이 함수는 ralph-loop.sh 안에서 가장 긴 함수다. 65줄 정도. 구조는 단순하다 — 헬스체크 (3줄) + 진단 캡처 (30줄) + 자동 재기동 (15줄) + 재확인 (5줄).

DEATH_LOG="$LOG_DIR/vllm-deaths.log"

ensure_vllm_alive() {
  local context_iter="$1"
  local context_item="$2"
  local context_prompt_size="$3"

  # 1단 — 헬스체크 (살아있으면 즉시 return)
  if curl -sS --max-time 3 "$VLLM_BASE_URL/models" > /dev/null 2>&1; then
    return 0
  fi

  echo "  vLLM 응답 없음 — 진단 로그 캡처 + 재기동 시도"

  # 2단 — 진단 캡처 (한 번에 9가지 운영 정보)
  {
    echo "===== vLLM down detected at $(date '+%Y-%m-%d %H:%M:%S') ====="
    echo "context: iter=$context_iter, item=$context_item"
    echo "직전 prompt 크기: ${context_prompt_size:-(N/A)} chars"
    echo ""
    echo "--- CHECKLIST 상태 ---"
    echo "  크기: $(wc -c < CHECKLIST.md) chars / $(wc -l < CHECKLIST.md) lines"
    echo "  완료(x): $(grep -cE '^[ ]*- \[x\]' CHECKLIST.md), 잔여([ ]): $(grep -cE '^[ ]*- \[ \]' CHECKLIST.md), 스킵(!): $(grep -cE '^[ ]*- \[!\]' CHECKLIST.md)"
    echo ""
    echo "--- PLAN.md ---"
    echo "  크기: $(wc -c < PLAN.md) chars / $(wc -l < PLAN.md) lines"
    echo ""
    echo "--- 직전 5 커밋 ---"
    git log --oneline -5 | sed 's/^/  /'
    echo ""
    echo "--- docker container 상태 ---"
    docker ps -a --filter name=vllm-spark-head --format '  {{.Status}} / {{.RunningFor}}'
    echo ""
    echo "--- vLLM container 마지막 60줄 ---"
    docker logs --tail 60 vllm-spark-head 2>&1 | sed 's/^/  /'
    echo ""
    echo "--- nvidia-smi ---"
    nvidia-smi --query-gpu=name,memory.used,memory.free,memory.total --format=csv,noheader | sed 's/^/  /'
    echo ""
    echo "--- GPU 스케줄러 status ---"
    "$GPU_SCHED" status 2>&1 | sed 's/^/  /'
    echo "===== END ====="
    echo ""
  } >> "$DEATH_LOG"

  echo "  진단 로그 기록: $DEATH_LOG"

  # 3단 — 자동 재기동 (1차 → 30초 wait → 2차)
  echo "  vLLM 재기동 시도 (1차)"
  if ! "$START_VLLM" 2>&1 | tail -10; then
    echo "❌ 재기동 1차 실패 — 30초 후 재시도"
    sleep 30
    echo "  vLLM 재기동 시도 (2차)"
    if ! "$START_VLLM" 2>&1 | tail -10; then
      return 1
    fi
  fi

  # 4단 — 재확인
  if ! curl -sS --max-time 5 "$VLLM_BASE_URL/models" > /dev/null 2>&1; then
    return 1
  fi

  echo "✅ vLLM 복구 완료, iter $context_iter 재개"
  return 0
}

코드 설명 — 함수는 살아있으면 1단에서 즉시 return 0 으로 끝난다 (정상 케이스, 매 iter 시작 시 거의 항상 이 경로). 죽어있을 때만 2~4단이 실행된다. 2단의 진단 캡처는 한 번의 함수 호출로 9가지 운영 정보 를 한 파일에 누적 append 한다 — 호출 시점·iter 번호·작업 항목·prompt 크기·CHECKLIST 메트릭·PLAN 크기·직전 5 커밋·docker 컨테이너 상태·vLLM 컨테이너 마지막 60줄 로그·nvidia-smi 메모리·GPU 스케줄러 상태. 3단의 재기동은 1차 실패 후 30초 wait + 2차 재시도까지 시도하고 그래도 실패하면 return 1 (호출자가 루프 중단 결정). 4단의 재확인은 재기동 명령이 성공해도 endpoint 가 진짜 응답하는지 한 번 더 확인한다.

왜 9가지나 캡처하는가 — 한 번 죽으면 다시 못 보는 정보

처음엔 진단 캡처가 너무 과한가 싶었다. docker logs 만 있으면 충분하지 않을까? 하지만 한 번 사고를 겪고 나니 이유가 분명해졌다.

vLLM 이 죽는 시점의 운영 컨텍스트는 시간 함수 다. 우리가 30분 후에 사후 분석을 시작하면:

docker logs 는 ring buffer 라 옛날 로그가 잘려나간다 (특히 INFO 가 매초 출력되는 vLLM)
nvidia-smi 는 지금 의 GPU 메모리 상태만 보여줌. 30분 전 다른 작업이 동시 점유 중이었는지 알 길 없음
CHECKLIST.md 는 그 사이 다른 항목까지 처리되어 죽음 시점의 크기·진척과 다름
git log 는 그 사이 커밋이 더 추가되어 직전 5 커밋이 다름
GPU 스케줄러 status 는 다른 작업이 acquire/release 한 결과로 다른 lock 상태

즉 죽음 시점에 캡처 안 하면 영영 못 보는 정보들이 9가지 나 있다. 사후 분석은 이 9가지 조각을 맞춰서 왜 그 시점에 그 죽음이 발생했는가 를 추론한다. 우리 케이스에서 prompt 크기와 CHECKLIST 크기를 봤더니 iter 가 진행될수록 누적된 prompt 가 vLLM 의 KV cache 임계를 트리거했다 는 가설이 자연스럽게 떠올랐다.

그림 설명 — 9가지 운영 정보 각각이 시간이 지나면 어떻게 변하거나 사라지는지 정리한 표다. ①~⑨ 모두 죽음 시점에 캡처해야 사후에 추론할 수 있다. ⑦ docker logs 는 vLLM 이 매초 INFO 를 출력해 ring buffer 가 빨리 차서 옛날 로그가 잘려나간다. ⑧ nvidia-smi 와 ⑨ GPU 스케줄러 status 는 다른 GPU 작업의 활동에 따라 변동한다. ② prompt 크기와 ③ CHECKLIST 카운트는 다음 iter 에서 다른 값으로 덮인다. 한 번에 한 곳에 누적 하지 않으면 영영 잃는 정보다.

실제 진단 로그 — 9가지가 한 번에 보이는 모양

위 함수가 실제로 만든 진단 로그의 한 항목이다 (일부 발췌).

===== vLLM down detected at 2026-05-04 11:46:38 =====
context: iter=30, item=src/game.js 상태 머신 골격...
직전 prompt 크기: 12347 chars

--- CHECKLIST 상태 ---
  크기: 3722 chars / 71 lines
  완료(x): 6, 잔여([ ]): 22, 스킵(!): 14

--- PLAN.md ---
  크기: 5826 chars / 152 lines

--- 직전 5 커밋 ---
  06a5f1d skip: tests/collision.test.js (3회 실패)
  76e39d7 skip: src/collision.js — aabb() (3회 실패)
  5397ac3 feat: requestAnimationFrame 메인 루프 통합
  68d4603 skip: 차 좌우 이동 + 도로 경계 클램프 (3회 실패)
  99b68ef skip: src/input.js — 좌우 화살표/A/D 키 핸들러 (3회 실패)

--- docker container 상태 ---
  Exited (0) 43 minutes ago / 6 days ago

--- vLLM container 마지막 60줄 ---
  ...
  (EngineCore pid=123) ERROR 05-04 01:46:37 [core.py:1110] AssertionError: num_required_blocks 25 < len(req_blocks) 26
  (APIServer pid=1) ERROR 05-04 01:46:37 [async_llm.py:707] AsyncLLM output_handler failed.
  (APIServer pid=1) ERROR 05-04 01:46:37 [async_llm.py:707] vllm.v1.engine.exceptions.EngineDeadError: EngineCore encountered an issue.
  (APIServer pid=1) INFO:     Shutting down
  (APIServer pid=1) INFO:     Application shutdown complete.
  ...

--- nvidia-smi ---
  NVIDIA GB10, 88 GiB, 8 GiB, 96 GiB

--- GPU 스케줄러 status ---
  실행 중인 작업:
  qwen3-asr-daemon  p=68  8GB  실행중
  vllm-chat (lock 살아있음 — 컨테이너는 죽었는데도)

===== END =====

로그 설명 — 한 번에 죽음의 모든 면을 본다. iter 30 에서 작업 항목은 src/game.js 상태 머신 이었고 직전 prompt 가 12347 chars 였다. CHECKLIST 는 그 시점 71 lines 였다. docker container 는 43분 전 Exit 0 으로 정상 종료. vLLM container 의 마지막 60줄에 정확한 죽음 원인 — AssertionError: num_required_blocks 25 < len(req_blocks) 26 — 이 박혀있다. nvidia-smi 는 88GB / 96GB 사용 중 (vllm-chat 점유 80GB 가 빠지지 않은 상태). GPU 스케줄러 status 에는 vllm-chat lock 이 살아있는데 docker container 는 죽어있는 desync 가 그대로 보인다.

이 한 항목만으로 vLLM v019 의 KV cache assertion 버그가 prompt 길이가 임계점에 도달했을 때 트리거됨, docker compose restart no 라 자동 복구 안 됨, GPU 스케줄러 lock 과 컨테이너 desync 발생 의 세 줄 결론이 나온다. 30분 후에 사후 분석한 게 아니라 죽음 시점에 한 번에 잡았기 때문에 가능했다.

매 iter 두 번 호출 — 시작 시 + opencode 직후

이 함수는 메인 루프 안에서 두 번 호출된다.

while [ ... ]; do
  iter=$((iter + 1))

  # 다음 항목 추출
  next=$(grep -n '^- \[ \]' CHECKLIST.md | head -1 || true)
  ...

  # 1번째 호출 — iter 시작 시
  if ! ensure_vllm_alive "$iter" "$item" ""; then
    echo "❌ vLLM 복구 불가 — 루프 중단"
    exit 4
  fi

  # opencode 호출
  prompt_size=$(printf '%s' "$prompt" | wc -c)
  timeout 300 opencode run --model "$MODEL" -f PLAN.md -f CHECKLIST.md -- "$prompt"

  # 2번째 호출 — opencode 직후
  if ! curl -sS --max-time 3 "$VLLM_BASE_URL/models" > /dev/null 2>&1; then
    echo "  opencode 호출 직후 vLLM 죽음 감지"
    ensure_vllm_alive "$iter (post-opencode)" "$item" "$prompt_size" || exit 4
  fi

  # 검증 후크 (다음 글에서)
  ...
done

코드 설명 — 두 번 호출하는 이유는 언제 죽었는지 의 정밀도를 높이기 위해서다. 1번째 호출 (iter 시작) 은 직전 iter 와 이번 iter 사이에 외부 요인 (다른 GPU 작업, 시스템 재시작 등) 으로 vLLM 이 죽었나 잡는다. 2번째 호출 (opencode 직후) 은 우리 prompt 가 직접 트리거했나 잡는다 — 이때 직전 prompt 크기를 함께 캡처해서 prompt 길이와 죽음의 상관관계 분석에 쓴다. 둘 다 같은 함수를 호출하지만 context 인자가 다르다 — 1번째는 빈 문자열, 2번째는 "$iter (post-opencode)" 와 prompt_size 값. 그래서 vllm-deaths.log 만 봐도 어느 단계에서 죽었는지 즉시 구분된다.

start_vllm.sh 의 idempotent 성질에 의존

재기동 명령으로 호출하는 start_vllm.sh 는 GPU 스케줄러 프로젝트에 따로 있는 스크립트인데, 이게 이미 살아있으면 즉시 skip 하는 idempotent 한 동작을 한다. 그 덕에 재기동 호출이 부작용 없이 안전 하다.

# start_vllm.sh 의 핵심 로직 (발췌)
# 이미 healthy 면 skip
if curl -sf "$HEALTH_URL" >/dev/null 2>&1; then
    echo "[start_vllm] vLLM 이미 실행 중"
    exit 0
fi

# 컨테이너 기동
cd "$VLLM_DIR"
docker compose --profile head up -d 2>&1 | tail -5

# 헬스체크 폴링 (vLLM 콜드 스타트 ~3분)
for i in $(seq 1 90); do
    if curl -sf "$HEALTH_URL" >/dev/null 2>&1; then
        break
    fi
    sleep 4
done

코드 설명 — 살아있으면 0줄 변경으로 즉시 종료, 죽어있으면 컨테이너 재기동 후 6분(90×4초) 까지 헬스체크 폴링. 이 idempotent 성질 덕에 ralph-loop 의 ensure_vllm_alive 가 부담 없이 호출할 수 있다 — 살아있다면 ms 안에 끝나고, 죽어있다면 재기동까지 6분 안에 끝낸다. 호출자는 항상 같은 인터페이스로 부른다.

왜 1차 실패 후 30초 wait 인가

2단의 자동 재기동에 1차 → 30초 wait → 2차 의 backoff 가 들어있다.

if ! "$START_VLLM" 2>&1 | tail -10; then
  echo "❌ 재기동 1차 실패 — 30초 후 재시도"
  sleep 30
  echo "  vLLM 재기동 시도 (2차)"
  if ! "$START_VLLM" 2>&1 | tail -10; then
    return 1
  fi
fi

이 30초가 도움이 됐던 케이스가 한 번 있었다 — vLLM 이 죽고 거의 동시에 다른 GPU 작업 (vlm-analysis 같은 background 작업) 이 들어와 잠깐 GPU 메모리를 80GB 잡고 있었다. 1차 재기동은 메모리 부족으로 실패. 30초 wait 동안 그 background 작업이 끝났고, 2차에서 80GB 잡고 정상 기동. 이 시나리오에서 30초가 없었다면 즉시 2차 실패하고 함수가 return 1 → 루프 중단으로 갔을 것이다.

30초가 모든 일시 자원 충돌을 해결하진 않지만 대부분의 background 작업이 1분 안에 끝나는 우리 환경에서 적절한 trade-off 였다. 더 보수적이라면 60초·90초로 늘릴 수 있는데, 그러면 정상 재기동도 30초 늦어진다.

실제 효과 — 38 iter 동안 vLLM 자살 2회를 모두 자동 복구

이 함수를 도입한 후 ralph-loop 를 다시 돌렸더니 vLLM 이 두 번 죽었지만 둘 다 자동 복구했다. vllm-deaths.log 는 두 항목으로 누적됐고, ralph-loop 는 멈추지 않고 끝까지 갔다. 사용자(나) 가 알아챈 건 cron 진척 보고에서 death events: 2 표시를 본 시점이지, 그 사이 ralph-loop 가 멈춘 적 없다.

장애가 0 에 가까워지는 게 아니라 — 알려진 vLLM v019 버그를 우리가 패치할 수 없으니 — 장애가 발생해도 운영이 안 멈추는 게 진짜 목표였다. 이 함수가 그 목표를 달성했다.

결론 — 진단을 작업의 일부로 만들기

운영 시스템에서 흔한 패턴은 "장애 발생 → 알람 → 사람이 들어가 디버깅" 이다. 그런데 자율 시스템에서는 사람이 들어갈 시간이 없을 수 있다 — ralph-loop 같은 장기 실행 루프는 사람이 잘 때, 출근했을 때, 다른 일 하고 있을 때 돌고 있다.

그래서 장애 발생 시점에 진단을 자동으로 캡처해서 한 곳에 누적 하는 게 — 알람보다 훨씬 — 가치 있다. 사람이 깨어나서 보면 그 사이 일어난 모든 장애의 9가지 정보가 vllm-deaths.log 에 시간순으로 정리되어 있다. 한 번 보면 패턴 추론이 가능하다 — "prompt 크기가 12000 chars 넘으면 자주 죽네" 같은 가설을 만들 수 있다.

이게 단순한 헬스체크 함수가 아닌 이유다. 헬스체크 + 자동 복구만이라면 한 줄 curl + restart 로 끝났을 것이다. 그 사이에 9줄짜리 진단 캡처 블록을 끼워 넣은 게 — 이 함수의 진짜 가치다. 장애를 데이터로 바꾸는 운영 철학.

이 글은 생성형 AI의 도움을 받아 작성되었습니다. 원본 자료를 기반으로 AI가 초안을 생성하고, 작성자가 검토·편집하였습니다.

자율 스크립트의 부팅과 셧다운 — 외부 자원을 잡았다면 정확히 한 번만 놓아라 (Ralph Loop 시리즈 2편)

타이젠 개발자, 윤진 — Sat, 16 May 2026 22:00:52 +0900

자율 코딩 루프 같은 장기 실행 스크립트의 시작과 끝은 의외로 까다롭다. 시작에서 외부 자원 — GPU lock, vLLM 컨테이너, 임시 파일 — 을 잡는 건 어렵지 않은데, 스크립트가 어떻게 끝나든 정확히 한 번 정리(cleanup)되도록 보장 하는 게 진짜 일이다. 정상 종료, Ctrl-C, kill -TERM, 스크립트 자체 exit 4, 또는 bash 의 set -e 가 발동시킨 갑작스런 종료까지 — 이 다섯 가지 종료 경로가 모두 같은 cleanup 함수로 합류하면서 동시에 중복 호출은 차단 되어야 한다.

이 글은 ralph-loop.sh 의 startup·shutdown 시퀀스를 본다. 한 30줄 정도의 코드인데 그 안에 자율 스크립트가 외부 자원을 다룰 때 빠지기 쉬운 실수 4가지의 답이 들어있다. 시리즈 2편이고, 1편은 컨텍스트 3축 분리 를 다뤘다.

왜 이게 어려운가 — 외부 자원의 "정확히 한 번"

Ralph Loop 가 시작되면 GPU 스케줄러에 vllm-chat 작업을 acquire 한다. 이건 다른 GPU 작업 (vault-search, voice-pipeline 등) 이 우리가 쓰는 동안 vLLM 을 죽이지 못하게 막는 lock 이다. 그리고 vLLM Docker 컨테이너를 기동한다 (이미 떠 있으면 skip).

이제 작업이 끝나서 스크립트가 종료될 때 — 평범하게 끝나든, 사용자가 Ctrl-C 누르든, 다른 셸에서 kill 으로 죽이든 — GPU lock 은 반드시 release 되어야 한다. release 안 하고 죽으면 lock 이 stale 상태로 남아 다음 실행이 "이미 점유 중" 응답을 받고 acquire 에 실패한다. 그러면 사람이 직접 lock 파일 지워줘야 한다.

여기서 한 단계 더 — release 가 정확히 한 번만 호출되어야 한다. 두 번 호출되면 그것 자체가 에러는 아니지만, 두 번째 호출 시점에 lock 이 이미 다른 작업에 의해 새로 잡혔다면 그 새 작업의 lock 을 우리가 지워버리는 사고가 발생한다. "한 번 이상" 도, "한 번 이하" 도 안 되고 정확히 한 번.

그림 설명 — 다섯 가지 종료 경로 (정상 / Ctrl-C / kill / exit 1·4 / set -e 갑작스런 종료) 가 모두 trap 두 개로 분기된다. INT/TERM trap 은 SIGINT/SIGTERM 받을 때 발동하고 cleanup 호출 후 exit 130 으로 종료하는데, 이 종료 자체가 다시 EXIT trap 을 발동시킨다. 즉 Ctrl-C 한 번에 cleanup 이 두 번 호출되는 경로가 자연스럽게 생긴다. 두 번째 호출에서 GPU release 를 또 하면 사고. 그래서 cleanup 안에 released flag 가 들어있고, 이미 release 한 상태라면 두 번째 호출은 즉시 return 한다. 다섯 가지 어떤 경로로 끝나든 GPU release 는 정확히 한 번만 발동한다.

핵심 코드 — 30줄 안에 모두 들어있다

ralph-loop.sh 의 startup·shutdown 부분이다. 총 30줄 정도.

#!/usr/bin/env bash
set -euo pipefail   # ← 한 줄이 갑작스런 종료를 만든다

REPO_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
cd "$REPO_DIR"

GPU_SCHED="$HOME/projects/gpu-scheduler/gpu-scheduler.sh"
START_VLLM="$HOME/projects/gpu-scheduler/start_vllm.sh"
JOB_NAME="vllm-chat"

iter=0
released=false   # ← idempotent flag

# cleanup 함수 — 무엇이 호출하든 정확히 한 번만 release
cleanup() {
  if [ "$released" = false ]; then
    echo ""
    echo "  ralph-loop 종료 (iter=$iter) — vLLM lock 해제"
    "$GPU_SCHED" release "$JOB_NAME" 2>/dev/null || true
    released=true
  fi
}
trap 'cleanup; exit 130' INT TERM   # ← Ctrl-C, kill -TERM
trap 'cleanup' EXIT                  # ← 모든 종료 (정상·exit·set -e)

# 부팅 — GPU acquire (먼저 자원 잡고)
echo "  GPU acquire ($JOB_NAME)"
if ! "$GPU_SCHED" acquire "$JOB_NAME"; then
  echo "❌ GPU acquire 실패 — freeze 모드 또는 더 높은 우선순위 작업 보유"
  exit 1
fi

# 부팅 — vLLM 컨테이너 기동 (이미 살아있으면 skip)
echo "  vLLM 기동 점검"
if ! "$START_VLLM"; then
  echo "❌ vLLM 기동 실패"
  exit 1
fi

# 부팅 — 최종 헬스체크
echo "  vLLM endpoint 점검"
if ! curl -sS --max-time 5 "$VLLM_BASE_URL/models" > /dev/null; then
  echo "❌ vLLM endpoint 응답 없음"
  exit 1
fi
echo "✅ vLLM 응답 OK"

# 메인 루프 — 다음 글들에서 다룸
while [ ... ]; do
  ...
done

코드 설명 — 위에서 아래로 읽으면 자연스러운 시퀀스다. 첫째, set -euo pipefail 로 갑작스런 종료 정책을 활성화한다 (어느 명령이든 실패하면 즉시 종료한다). 둘째, released=false 와 cleanup() 함수를 먼저 정의하고 trap 으로 두 종류의 신호에 묶는다. trap 등록은 acquire 보다 먼저 되어야 한다 — 만약 acquire 후 trap 등록 사이에 신호가 도착하면 cleanup 안 호출되고 lock 이 stale 로 남는다. 셋째, GPU acquire → vLLM 기동 → 헬스체크 의 3단계 부팅. 어느 한 단계라도 실패하면 즉시 exit 1 인데, 이 종료조차 EXIT trap 을 발동시켜 cleanup → release 가 자동으로 따라온다. 넷째, 메인 루프는 다음 글에서.

왜 trap 이 두 개인가 — INT/TERM 과 EXIT 의 분리

이 부분이 처음엔 헷갈렸다. EXIT trap 하나만 등록하면 모든 종료 경로를 잡을 수 있는데 왜 굳이 INT TERM 을 따로 두는가?

차이는 exit code 다. EXIT trap 은 종료 직전에 발동하지만 종료 코드 자체를 바꾸지 않는다. 만약 사용자가 Ctrl-C (SIGINT) 를 누르면 bash 의 기본 동작은 종료 코드 130 인데, EXIT trap 만 있으면 cleanup 후 130 으로 정상 종료한다 — 여기까진 OK 다.

그러나 cleanup 안에서 다른 명령이 실패해서 set -e 가 발동하면 종료 코드가 cleanup 의 마지막 명령 종료 코드로 덮인다. 또 어떤 운영 환경에서는 trap 등록 시 명시적으로 exit code 를 박아두는 게 안전하다. 그래서 INT/TERM 에는 cleanup; exit 130 으로 코드를 명시했다. 130 = 128 + 2(SIGINT) 의 표준 관례라 모니터링 도구가 사용자 중단으로 자동 분류해준다.

즉 EXIT trap 은 모든 종료에서 발동하는 안전망이고, INT/TERM trap 은 사용자가 의도해서 죽인 경우의 명시적 처리다. 둘 다 같은 cleanup 을 부르지만 의미가 다르고, exit code 도 다르다.

idempotent flag — 한 줄의 안전장치

cleanup 안의 if [ "$released" = false ] 가 핵심이다. Ctrl-C 시나리오를 따라가 보자.

사용자가 Ctrl-C 누름 → SIGINT 발동
INT trap 발동 → cleanup 호출 → released=false 상태 → release 실행 → released=true
INT trap 의 exit 130 실행
이 exit 가 또 다시 EXIT trap 발동 → cleanup 두 번째 호출
두 번째 호출에서 released=true 상태 → 즉시 return → release 안 일어남

flag 한 줄이 없으면 release 가 두 번 호출된다. 첫 번째와 두 번째 사이에 다른 작업이 lock 을 잡았을 가능성이 있으면 그 작업의 lock 을 우리가 지워버린다. 운영 중인 프로덕션이라면 "왜 갑자기 vault-search 가 GPU 를 잃었지" 같은 미스터리한 사건이 된다. flag 한 줄이 그걸 막는다.

또 하나 — "$GPU_SCHED" release "$JOB_NAME" 2>/dev/null || true 끝의 || true 가 있다. release 자체가 어떤 이유로든 실패해도 cleanup 은 끝까지 진행되어야 하기 때문이다. 만약 set -e 가 활성화돼있고 release 명령이 0이 아닌 종료 코드를 반환하면 cleanup 한복판에서 죽으면서 EXIT trap 이 또 발동하는 무한 루프 위험이 있다. || true 가 그걸 차단한다.

왜 acquire 가 먼저, trap 이 그보다 먼저

이 순서도 중요한 디테일이다. 코드를 보면:

trap 'cleanup; exit 130' INT TERM   # 1. trap 등록 먼저
trap 'cleanup' EXIT

if ! "$GPU_SCHED" acquire "$JOB_NAME"; then   # 2. 그 다음 acquire
  exit 1
fi

왜? acquire 가 먼저 되고 trap 등록이 나중에 되면 — 그 사이의 마이크로초 동안 사용자가 Ctrl-C 를 누르면 — trap 이 등록 안 된 상태라 cleanup 이 안 일어난다. lock 만 잡고 죽는다. 가능성이 매우 낮지만 0은 아니다. trap 을 먼저 박고 그 다음 자원을 잡는 게 일반 원칙 이다.

반대로 release 는 cleanup 안에서 하니 순서를 신경 쓸 필요 없다 — trap 발동 시점에는 acquire 가 됐든 안 됐든 release 명령은 안전하다 (release 가 이미 풀린 lock 을 풀려 하면 그냥 "점유하고 있지 않음" 응답을 받고 끝).

실패 모드 — 이 디자인이 정말 작동하나

Ralph Loop 를 38 iter 돌리면서 의도적·비의도적으로 다양한 종료를 일으켰다. 결과:

정상 종료 (CHECKLIST 완료): while 루프 break → bash 정상 exit → EXIT trap 발동 → cleanup → release 1회. ✅
Ctrl-C: SIGINT → INT trap → cleanup → release 1회 → exit 130 → EXIT trap → cleanup 두 번째 호출 → flag 차단. ✅
외부 kill -TERM: SIGTERM → TERM trap → 위와 동일. ✅
vLLM 복구 불가 (exit 4): 스크립트 자체 exit → EXIT trap → cleanup → release 1회. ✅
set -e 갑작스런 종료: 어느 명령 실패 → bash 즉시 종료 → EXIT trap → cleanup → release 1회. ✅

한 번 작동 안 한 케이스가 있었다 — kill -9 (SIGKILL) 이다. SIGKILL 은 process 가 가로챌 수 없는 신호라 trap 이 안 발동한다. 그래서 lock 이 stale 로 남고, 다음 실행에서 acquire 가 "이미 점유 중" 응답을 받았다. 운영 중에 두 번 이 일이 있었는데 손으로 release 호출해서 풀었다.

# SIGKILL 후 stale lock 처리
~/projects/gpu-scheduler/gpu-scheduler.sh release vllm-chat
# → "vllm-chat: GPU를 점유하고 있지 않음" 또는 정상 release

SIGKILL 은 본질적으로 막을 수 없는 신호라 — 우리 스크립트가 할 수 있는 건 그 가능성을 인지하고 운영 절차를 마련하는 것뿐이다. 시리즈 9편(통합편) 에서 ralph-loop 실행 전후의 운영 체크리스트를 다룰 예정.

다른 자율 스크립트에 그대로 가져갈 수 있는 패턴

이 cleanup·trap 패턴은 ralph-loop 만의 것이 아니라 외부 자원을 잡는 모든 장기 실행 bash 스크립트 에 적용된다. 일반화하면:

#!/usr/bin/env bash
set -euo pipefail

# 1. 자원 release 가 필요한 모든 자원에 대해 idempotent flag 정의
released=false

# 2. cleanup 함수 — flag 검사 + release + flag 토글
cleanup() {
  if [ "$released" = false ]; then
    # release 명령들 (각각 || true 로 실패해도 다음 step 진행)
    your_resource_release || true
    released=true
  fi
}

# 3. trap 등록 — INT/TERM 은 명시적 exit code, EXIT 는 모든 종료
trap 'cleanup; exit 130' INT TERM
trap 'cleanup' EXIT

# 4. 그 후 자원 acquire
your_resource_acquire || exit 1

# 5. 메인 작업
while [ ... ]; do
  ...
done

이 5단계는 GPU lock 뿐 아니라 — DB connection pool, tmpfile, network port bind, process group, 심지어 외부 API 의 lease (예: Hashicorp Vault token) 등 — 어떤 외부 자원에든 적용된다. 자원의 종류만 바뀔 뿐 패턴은 동일하다.

결론 — 30줄 안의 운영 안정성

전체 30줄짜리 부팅·셧다운 코드인데 그 안에 들어간 결정들이다:

set -euo pipefail 로 갑작스런 종료 정책을 활성화한다.
released=false idempotent flag 로 release 가 정확히 한 번만 호출되도록 보장한다.
cleanup 함수 안에 || true 를 붙여 release 명령이 실패해도 cleanup 이 끝까지 진행되게 한다.
INT/TERM trap 과 EXIT trap 을 분리해 의미 차이와 exit code 를 명시한다.
trap 등록을 acquire 보다 먼저 둔다.
SIGKILL 은 막을 수 없음을 인정하고 운영 절차로 보완한다.

이 결정들은 별것 아닌 디테일처럼 보이지만 자율 에이전트 운영에서 결정적이다. 한 번 실행된 ralph-loop 가 자기 자원을 깨끗하게 정리하지 못하면 다음 실행이 시작도 못 한다. 그러면 사람이 매번 끼어들어야 하고, 그 순간 자율 이라는 말이 무너진다. 자율 시스템의 자율성은 시작과 끝의 깔끔함에서 시작된다.

이 글은 생성형 AI의 도움을 받아 작성되었습니다. 원본 자료를 기반으로 AI가 초안을 생성하고, 작성자가 검토·편집하였습니다.