Claude Code hooks 오탐 — 설명 요청을 작업으로 읽은 앵커 한 글자

증상 — 설명해 달라고 했는데 에이전트가 작업 준비를 시작했다

2026년 8월 24일, 대표가 에이전트에게 '조금 더 쉽게 설명해줘'라고 쳤습니다. 하루 전에 배선한 훅이 이 문장을 작업 지시로 읽고, 에이전트에게 '착수 전에 스스로 출발 지시서를 깔아라'를 주입했습니다. 설명 한 문단이면 끝날 자리에서 에이전트가 할 일 목록과 완료 판정부터 세우기 시작했습니다.

조금 더 쉽게 설명해줘

이 훅은 증상 하나를 잡으려고 만든 검사원입니다. 세션을 새로 열고 첫 지시를 주면 에이전트가 도구를 한 번 쓰고 멈추는데, 잘 짜인 첫 프롬프트로 시작한 세션은 끝까지 가는 현상입니다. 그 증상을 고치려고 세운 검사원이 이제 설명 요청까지 붙잡고 있었으니 문제가 둘이 됐습니다.

훅 오탐은 그 자체보다 뒤가 무섭습니다. 검사원이 한 번 엉뚱한 사람을 세우면 그 다음부터는 아무도 검사원 말을 듣지 않습니다. 같은 저장소에서 앞서 만든 프롬프트 코칭 장치가 전체 대화 기록에서 3회 발동에 그친 전례가 있었고, 이번 훅이 같은 길을 가면 원래 증상도 못 고칩니다.

처음 의심한 것 — 내 프롬프트가 부실해서 멈춘다

출발점은 2026년 8월 23일 대표의 관찰입니다.

오프닝 프롬프트로 세션을 시작하면 에이전트가 오래 자율로 작업하던데, 내가 대화 중에 좋은 프롬프트를 못 줘서 작업이 단발로 끝나는 건 아닌가?

관찰과 진단이 한 문장에 붙어 있습니다. 관찰은 '구조화된 첫 프롬프트로 시작한 세션이 멀리 간다'이고, 진단은 '대화 중 내 프롬프트가 부실해서 단발로 끝난다'입니다. 처음 의심한 범인은 프롬프트의 질이었고, 그 진단이 맞다면 처방은 사람이 프롬프트를 더 길고 정확하게 쓰는 훈련입니다.

이 진단을 그대로 믿었다면 훅은 사람에게 '프롬프트를 더 자세히 써 달라'고 되묻는 장치가 됐을 겁니다. 그 전에 세어 보기로 했습니다.

대화 기록 10,855파일에서 무엇을 셌나

관측 수단은 로그 파일입니다. 에이전트가 남기는 세션 기록(transcript) 10,855파일을 21일치 모아, 대표가 실제로 타이핑한 발화 3,161턴을 골라냈습니다.

잰 값은 하나입니다. 한 발화 뒤 다음 발화까지 에이전트가 실행한 도구 호출(tool_use) 수이고, 이 글에서는 실행 길이라 부릅니다. 발화마다 아래 출발 조건 5개 가운데 몇 개를 담았는지도 함께 판정했습니다. 조건 하나가 빠지면 에이전트가 멈출 이유가 하나 남습니다.

• 큐 — 다음에 할 일이 어디 적혀 있나. 없으면 1개 하고 끝납니다
• 목적지 — 다 하면 무엇이 달라지나. 없으면 가장 좁은 해석을 고릅니다
• 완료 판정 — 언제 끝난 건가, 기계로 확인 가능한가. 없으면 '됐습니다'로 조기 종료합니다
• 읽을 것 — 무엇을 먼저 읽나. 없으면 물어보러 되돌아옵니다
• 금지 — 무엇을 하면 안 되나. 없으면 승인 대기로 멈추거나 범위를 넘습니다

세션 첫 프롬프트와 대화 중간 프롬프트를 갈라서 봤습니다. 첫 진단이 겨눈 자리는 대화 중간이라, 거기서 차이가 나야 진단이 맞습니다.

왜 프롬프트 길이는 범인이 아니었나

대화 중간 전체에서 출발 조건 판정을 통과한 발화의 실행 길이 중앙값은 4.0, 통과하지 못한 발화는 3.0이었습니다. 거의 붙습니다. 진단이 겨눈 바로 그 자리에서 차이가 없었습니다.

더 강한 반증은 상위 목록에 있었습니다. 실행 길이 상위 20턴 가운데 절반이 11~21자였습니다.

'에이전트가 손을 놓아서 사람이 재촉해야 했다'는 그림도 실제로는 드물었습니다. 도구 0개로 끝난 턴 522건 가운데 직후에 재촉이 붙은 경우는 15건, 2.9%였고, 그 522건 대부분은 애초에 질문이었습니다.

그래서 첫 진단은 대화 중간에서는 성립하지 않습니다. 짧은 프롬프트가 원인이라면 15자 발화가 192회짜리 실행을 낼 수 없습니다. 프롬프트의 질에는 알리바이가 있었습니다.

진짜 원인 — 세션 첫 턴, 프롬프트 말고는 큐를 줄 곳이 없는 시점

손실은 세션 첫 턴 하나에 몰려 있었습니다. 첫 프롬프트의 88%가 출발 조건 0/5였고 실행 길이 중앙값은 1.0입니다. 조건이 하나만 있어도 19.0으로, 격차가 19배입니다.

이유는 컨텍스트입니다. 대화 중간에는 큐가 이미 에이전트 기억에 올라와 있어 짧게 말해도 다음 할 일이 보입니다. 세션 첫 턴에는 그 기억이 비어 있어 프롬프트가 유일한 큐 공급원입니다. 범인은 프롬프트의 길이가 아니라, 프롬프트 말고는 큐를 줄 곳이 없는 시점이었습니다.

여기서 두 번째 가설도 넘어졌습니다. 출발 조건이 몇 개면 충분한가를 직관으로 3개라고 잡았는데, 전수 재판정에서 점프는 3개가 아니라 0개와 1개 사이에 있었습니다. 3개 이상은 표본이 사실상 없어(n=2) 판정할 수도 없었습니다. 임계는 1개로 정정했습니다.

큐 포인터만 있는 발화는 그것만으로 통과입니다. '이어서', '다음 큐'처럼 진행 큐 문서를 가리키는 11자 프롬프트가 190회를 냈다고 실측이 말합니다.

고친 방법 — 사람을 훈련하지 않고 빈자리는 시스템이 채운다

처방 후보는 둘이었습니다. 하나는 대표가 첫 프롬프트를 길게 쓰도록 훈련하는 방식, 다른 하나는 첫 프롬프트에 출발 조건이 없으면 에이전트가 스스로 채우게 하는 방식입니다. 앞의 방식은 두 번 기각했습니다.

• 첫 프롬프트의 88%가 조건 0개라 사람 훈련으로 닫을 크기가 아닙니다
• 같은 회사의 번역체 통제 규칙이 같은 구조에서 이미 실측했습니다. 생성 지시를 강화하는 방식은 무효였고 사후 게이트만 유효했습니다
• '실수를 개별로 고치지 말고 실수가 불가능하도록 시스템을 고쳐라'는 운영 원칙에 어긋납니다

그래서 훅으로 배선했습니다. 사람이 프롬프트를 보낼 때 도는 훅이 세션의 첫 작업 프롬프트를 보고, 출발 조건이 0/5면 에이전트에게 '착수 전에 스스로 출발 지시서를 깔아라'를 주입합니다. 세션당 1회만 발동합니다.

훅은 사람에게 되묻지 않습니다. 짧은 프롬프트는 결함이 아니라 컨텍스트가 비었다는 사실의 반영이고, 빈 곳은 에이전트가 채웁니다. 되묻는 순간 사람은 실행 뒤에 검토한다는 운영 원칙을 뒤집게 됩니다.

세션 첫 프롬프트에만 발동하게 좁힌 근거도 위 실측입니다. 대화 중간에는 효과가 없고(중앙값 4.0 대 3.0), 효과 없는 발동은 잔소리가 되어 게이트를 죽입니다. 앞서 만든 프롬프트 코칭 장치가 전체 기록에서 3회 발동에 그친 전례가 그 증거입니다.

훅은 어디서 설명 요청을 작업으로 읽었나

배선 다음 날 오탐이 났습니다. 원인은 '작업이 아닌 발화' 판별 규칙이 정규식 첫머리 앵커(^)와 match 방식이라 문장 첫머리에서만 설명 요청을 잡았기 때문입니다. '설명해줘'로 시작하면 잡지만, 실제 발화는 수식어가 앞에 붙습니다. '조금 더 쉽게 설명해줘'는 첫 글자가 '조'라서 규칙을 그냥 지나쳤습니다.

고친 방법은 짧은 메타 발화를 위치와 무관하게 잡는 규칙 하나를 더하는 방식입니다. 60자 이하이고 작업 동사가 없으면 작업이 아닌 발화로 봅니다.

이때 '정리해줘'는 작업 동사 목록에서 뺐습니다. '다시 정리해줘'는 설명이고 '파일 정리해줘'는 작업인데, 어휘만으로는 둘을 가를 수 없습니다. 놓치는 쪽을 택했습니다. 오탐 한 번이 훅 전체를 무시당하게 만드는 값이, 진짜 작업 하나를 놓치는 값보다 큽니다.

수리로 바뀐 판정은 4건뿐이고 실행 길이 중앙값은 1.0 그대로입니다. 오탐을 고치려다 원래 증상의 계측을 흔들지 않았는가, 이 표가 답하는 질문은 그것 하나입니다.

같은 문서는 막았는데 같은 일은 왜 못 막았나

2026년 8월 27일, 다른 종류의 문제가 왔습니다.

병렬로 여러 세션이 같은 오프닝 프롬프트 마크다운을 보는데, 어떤 세션이 그 작업을 하는지 서로 알 수가 없다. 이미 다른 세션이 하고 있는 최상단 작업을 또 시작하려길래 내가 막았다.

훅이 만든 부작용입니다. '큐 최상단부터 집어라'는 세션이 하나일 때는 장점이고 여럿일 때는 충돌 장치입니다. 확인해 보니 막혀 있던 쪽은 발급뿐이었습니다. 같은 문서를 동시에 쓰는 일은 막았는데, 같은 일을 동시에 하는 쪽은 아무도 보지 않았습니다.

큐 항목을 잡는 클레임 장치를 새로 만들었습니다. 소유 단위는 프로세스가 아니라 세션이고, 항목 키는 흔들리는 줄 번호가 아니라 본문 지문이며, 생존 판정은 시간 만료가 아니라 프로세스 생사를 먼저 봅니다. 죽은 세션의 클레임이 큐를 영구히 잠그는 실패가 이 종류 장치의 표준 실패이기 때문입니다. 중복 차단, 재진입 멱등, 죽은 프로세스 자동 회수 후 재획득 같은 반증 8케이스를 통과했습니다.

같은 날 2차로 구멍이 하나 더 나왔습니다. 대표가 '중복 착수도 이제 해결한 거지'라고 재확인해서 다시 짚어 보니, 초판은 아무도 클레임을 안 잡으면 통째로 무력화됐습니다. 세션 A가 안 잡고 최상단을 시작하면 세션 B에는 '활성 클레임 0건, 최상단부터 집어도 된다'가 뜹니다. 클레임 기록이 재는 값은 '누가 잡았나'인데 필요한 값은 '같은 큐에 몇 세션이 붙어 있나'였습니다. 층이 하나 빠져 있었습니다.

세션 존재(presence) 층을 더했습니다. 세션이 열릴 때 자동 등록하고 턴이 끝날 때 갱신하며 닫힐 때 해제합니다. 클레임이 0건이어도 동료 세션이 있으면 '0건은 아무도 일 안 한다가 아니라 아무도 안 잡았다는 뜻'을 띄우고 먼저 잡으라고 지시합니다. 단독 세션에서는 0줄이라 잔소리가 없습니다. 남는 위험은 두 세션이 다 그 지시를 무시하는 경우뿐이고, 그건 정보 부재가 아니라 지시 불이행입니다.

같은 실수를 막는 장치

훅 하나로 끝나지 않았습니다. 재발을 막는 장치는 여섯 층이고, 그중 셋은 실제 사고 뒤에 생겼습니다.

재감사에서 볼 값은 조건 0/5 세션의 비율이 아니라 그 구간의 중앙값입니다. 비율은 대표의 타이핑 습관이라 안 변해도 정상이고, 훅이 채워 넣은 뒤 얼마나 멀리 갔는가가 훅의 성적입니다.

판정기도 실데이터에서 세 번 틀렸습니다. 볼드 태그를 못 읽어 56줄 큐가 '열린 항목 0건'으로 나왔고, 근거 표기 형식만 보다가 파일 경로를 본문에 박은 항목을 '근거 없음'으로 쳤고, 자율 항목 전체를 보는 바람에 14건 중 1건만 비어도 발급을 강제했습니다. 판정 대상을 큐 최상단 자율 항목으로 좁혀서 반증 3종을 통과시켰습니다. 검사원을 하나 세울 때마다 그 검사원을 검사하는 표본이 따로 필요했습니다.

안 잡기로 한 것과 남는 질문

• 긴 실행이 좋은 실행인지는 재지 않습니다. 실행 길이는 대리 지표라 232회짜리 턴이 헤맨 결과일 수도 있습니다. 이 장치는 '중간에 멈출 이유가 남아 있는가'만 잽니다
• 결과 품질은 검증 규칙과 QA 장치의 몫입니다. 층이 다릅니다
• '적절히'·'잘' 같은 어휘 수준의 모호함은 결정론으로 정상 사용과 못 가릅니다
• 대화 중간 프롬프트에는 발동하지 않습니다. 실측상 효과가 없습니다

첫 턴에서 19배가 갈리는 계측 자체는 Claude Code 자율 실행이 한 턴 만에 멈추는 이유를 잰 글에 따로 있습니다. 이 글은 그 계측이 낳은 검사원이 하루 만에 엉뚱한 사람을 세운 뒤의 기록입니다.

정규식 앵커 한 글자가 훅 하나의 신뢰를 걸었듯이, 자동화 장치에서는 오탐 한 번의 값이 누락 한 번의 값보다 큽니다. 사내 업무에 에이전트를 붙일 때 어디까지 자동으로 잡고 어디부터 놓칠지 함께 정하는 자리는 상담에 있습니다.