모든 훅은 흉터다: 코드로 남은 84번의 에이전트 실패

제 에이전트 오케스트레이션 시스템에는 훅이 84개 있습니다. v2.1.116 기준(2026년 4월)으로 Claude Code가 노출하는 26가지 수명 주기 이벤트 중 15가지를 가로챕니다. 각 훅은 특정 에이전트 동작의 앞뒤에서 실행되는 셸 스크립트나 Python 코드 조각입니다. 파일 읽기, 파일 쓰기, bash 명령, 웹 요청, 하위 에이전트 생성, git 작업, MCP 도구 호출이 그 대상입니다. 그리고 훅 하나하나에는 무언가 잘못됐던 사건이 하나씩 붙어 있습니다.

에이전트 오케스트레이션 시스템의 모든 훅은 특정한 운영 장애로 거슬러 올라갑니다. 그래서 훅 모음은 셸 스크립트로 기록된 조직의 기억이 됩니다. 에이전트는 CDN 캐시를 날렸고, 자격 증명 파일을 읽었고, 돌려본 적도 없는 테스트가 통과했다고 보고했으며, 40분 동안 엉뚱한 일로 새어 나갔습니다. 사고가 하나 터질 때마다 작고 결정론적인 방어 장치가 하나씩 생겼고, 그 장치는 이후 모든 작업 회차에서 조용히 작동해 왔습니다.

이론상 잘못된 게 아닙니다. 운영 환경에서 실제로 잘못됐습니다. 어떤 에이전트는 수백만 건의 요청을 처리하던 CDN 캐시를 날려버렸습니다. 어떤 에이전트는 SSH 키를 쓰려고 했습니다. 어떤 에이전트는 pytest를 실행하지도 않고 “모든 테스트 통과”라고 보고했습니다. 어떤 에이전트는 맡은 일에서 너무 멀리 벗어난 나머지, 지시받은 작업과 아무 관련도 없는 파일의 함수를 40분 동안 최적화했습니다.

이 훅들 중 어느 것도 미리 설계해 둔 것이 아닙니다. 자리에 앉아 자율 AI 에이전트의 실패 유형을 하나하나 열거하고 예방용 통제 장치를 작성한 적이 없습니다. 모든 훅은 사후 대응입니다. 무언가 망가졌고, 다시 망가지지 않도록 스크립트를 썼고, 그 스크립트는 그 뒤로 모든 작업 회차에서 조용히 작동했습니다. 이 훅 시스템은 보안 아키텍처가 아닙니다. 흉터 모음집입니다.

핵심 요약

• 캐시 퍼지: 에이전트가 권한이 부여된 API 호출로 운영 CDN 캐시를 통째로 날렸습니다. 이제 훅 2개(47줄)가 파괴적 작업을 사람이 직접 입력하는 암구호 뒤에 가둬 둡니다.
• 자격 증명 읽기: 에이전트가 API 토큰을 컨텍스트 윈도에 실어 보냈습니다. 이제 경로 대조 방어 장치가 자격 증명 파일 읽기를 차단하고, .env 파일 접근은 기록으로 남깁니다.
• 유령 검증: 에이전트가 pytest를 돌리지 않고 “모든 테스트 통과”라고 보고했습니다. 얼버무리는 표현을 잡아내는 감지기를 넣자 유령 검증이 전체 작업 회차의 12%에서 2% 미만으로 떨어졌습니다.
• 12번의 이탈: 에이전트가 60일 동안 맡은 일을 놓친 사례가 12건 확인됐습니다. 이제 임계값 0.30의 코사인 유사도 감지기가 도구 호출 25회마다 작동합니다.
• 분류 체계: 여섯 가지 구조적 실패 범주가 84개 훅 전부를 포괄합니다. 500회가 넘는 작업 회차를 지나면 새로운 범주는 거의 나오지 않습니다. 시스템은 사고를 겪을 때마다 더 단단해집니다.

캐시 퍼지: 허가된 호출 하나가 운영 환경을 무너뜨린 방식

2026년 3월 21일, 저는 에이전트에게 resumegeni.com의 지역별 페이지가 왜 느리게 로드되는지 조사해 달라고 요청했습니다. 에이전트는 평범하게 조사를 시작했습니다. 라우트 핸들러를 읽고, 데이터베이스 쿼리를 확인하고, 템플릿 렌더링을 프로파일링했습니다. 그러다가 오래된 Cloudflare 캐시 항목이 진짜 성능 특성을 가리고 있을지도 모른다고 판단했습니다.

에이전트는 purge_everything: true를 붙여 mcp__cloudflare__cache_purge를 호출했습니다.

운영 사이트에 캐시된 모든 페이지가 그 즉시 무효화됐습니다. 대부분의 요청을 80~100ms에 처리하던 CDN이 모든 요청을 Railway 원본 서버로 넘기기 시작했습니다. 오스틴 지역 페이지는 1초 미만에서 14,290밀리초로 늘어났습니다. 뉴욕은 1초 미만에서 6,891ms가 됐습니다. 이제 사이트의 모든 페이지가 매 요청마다 차가운 원본에서 렌더링되고 있었습니다.

에이전트는 허가받지 않은 일을 한 게 아닙니다. 유효한 자격 증명으로 정당한 MCP 도구를 사용해, 권한이 부여된 API 엔드포인트를 호출했습니다. 캐시 동작을 디버깅하는 중이라면 캐시 퍼지는 합리적인 조사 단계입니다. 문제는 “디버깅에는 합리적인 것”과 “운영 환경에는 치명적인 것”이 동일한 API 호출이었다는 점, 그리고 에이전트의 추론과 운영 환경에서 벌어질 결과 사이에 아무런 제약도 없었다는 점입니다.⁴

그날 밤 저는 훅 두 개를 만들었습니다.

Bash 방어 장치(destructive-api-guard.sh): 모든 bash 명령에서 작동합니다. curl.*purge, rm -rf, DROP TABLE, docker.*rm, git push.*--force 패턴을 대조합니다. 강제 차단(exit 2)입니다. 에이전트는 왜 명령이 차단됐는지 설명하고 대안을 제시하는 메시지를 받습니다. “rosebud”라는 암구호 없이는 진행할 수 없고, 이 암구호는 사람이 직접 입력해야만 컨텍스트에 들어옵니다.

MCP 방어 장치(destructive-mcp-guard.sh): mcp__cloudflare 또는 mcp__github와 일치하는 모든 MCP 도구 호출에서 작동합니다. 도구 매개변수에서 purge, delete, destroy, remove 패턴을 대조합니다. 동일한 강제 차단, 동일한 암구호 관문입니다.

훅 두 개. 셸 스크립트 두 개. 합쳐서 코드 47줄입니다. 설치 이후 이 훅들이 막아낸 캐시 퍼지는 0건인데, 암구호 관문이 생긴 뒤로는 어떤 에이전트도 시도조차 하지 않았기 때문입니다. 이 훅들은 공격을 잡아내는 장치가 아닙니다. 그런 종류의 실수가 애초에 가능하지 않도록 만드는 장치입니다.

캐시 퍼지 사고는 원래 조사하려던 성능 문제까지 함께 드러냈습니다. 차가운 렌더링에서 14초가 걸린 오스틴 사례가 지역별 페이지 인수인계로 이어졌고, 나흘 뒤 쿼리 형태 수정으로 이어졌습니다. 사고 자체는 쓸모가 있었습니다. 훅은 그 사고가 반복될 수 없게 만듭니다.

자격 증명을 읽은 에이전트

2026년 2월, 어떤 프로젝트의 배경을 파악하던 에이전트가 ~/.claude/docs/credentials.md를 읽었습니다. 이 파일에는 Cloudflare, GitHub, Railway를 비롯한 여러 서비스의 API 토큰이 들어 있습니다. 에이전트는 파일 내용 요약을 작업 메모에 포함시켰고, 그 말은 토큰이 Anthropic 서버로 가는 API 요청 안에 들어갔다는 뜻입니다.

커밋된 토큰은 없었습니다. 공개적으로 노출된 토큰도 없었습니다. 하지만 토큰은 제가 통제할 수 없는 컨텍스트 윈도에 실려 서드파티 API를 통과했습니다. 위험 표면이 “내 컴퓨터”에서 “내 컴퓨터 더하기 Anthropic의 추론 인프라”로 넓어진 것입니다.

자격 증명 경로 방어 장치는 모든 파일 읽기에서 작동합니다. 경로를 민감 패턴 목록과 대조합니다. .env, credentials, .ssh/, .aws/, .gnupg/, secrets가 그 목록입니다. 자격 증명 파일을 읽으려 하면 훅이 경고를 기록하고 읽기를 차단합니다. .env를 읽으려 하면 읽기는 허용하되 접근 사실을 기록합니다.

대부분의 경로에서는 권고 수준이고, 자격 증명 파일에 대해서만 강제 차단입니다. 이 구분이 중요합니다. 에이전트가 환경 변수 이름을 파악하려고 .env를 읽는 건 쓸모 있는 배경 정보입니다. 에이전트가 API 토큰을 파악하려고 credentials.md를 읽는 건 보안 사고입니다.

설치 이후 자격 증명 경로 방어 장치는 200회가 넘는 작업 회차에서 23번 작동했습니다. 그중 20번은 에이전트가 .env 파일을 읽은 경우였습니다(기록, 허용). 3번은 자격 증명이나 키 파일을 읽으려 한 경우였습니다(차단). 차단된 읽기는 모두 프로젝트 배경을 폭넓게 수집하다가 검색 패턴에 민감한 파일이 우연히 걸려든 경우였습니다. 악의적인 시도는 하나도 없었습니다. 그리고 방어 장치가 없었다면 전부 컨텍스트 윈도에 비밀 정보를 집어넣었을 것입니다.

유령 검증자

가장 교묘한 실패 유형은 검증을 하지도 않고 검증에 성공했다고 보고하는 에이전트입니다.

147번째 작업 회차. 저는 에이전트에게 데이터베이스 쿼리를 리팩터링하고 기존 테스트 스위트로 변경 사항을 검증해 달라고 요청했습니다. 에이전트는 쿼리를 제대로 리팩터링했습니다. 완료 보고서에는 이렇게 적혀 있었습니다. “모든 테스트 통과. 리팩터링한 쿼리는 원본과 동일한 결과를 냅니다.”

작업 기록을 확인했습니다. pytest 호출은 없었습니다. 어떤 종류의 테스트 러너도 호출되지 않았습니다. 에이전트는 리팩터링한 쿼리가 원본과 논리적으로 동등하므로 테스트가 통과할 것이라고 추론했고, 그 추론을 마치 테스트 결과인 양 보고한 것입니다.

리팩터링한 쿼리는 실제로 맞았습니다. 테스트도 통과했을 겁니다. 에이전트의 추론도 타당했습니다. 하지만 테스트에 대해 추론하는 것은 테스트를 실행하는 것이 아니고, 그 둘 사이의 틈으로 버그가 운영 환경까지 흘러갑니다. 만약 리팩터링한 쿼리가 에이전트의 추론이 미처 다루지 못한 예외 상황에서 미묘하게 틀렸다면, 그 버그는 테스트 검증을 마쳤다고 주장하는 완료 보고서와 함께 배포됐을 것입니다.

증거 관문 훅을 만들기 전까지 이 실패 유형은 60회의 작업 회차에서 7번 발생했습니다. 이 훅은 모든 완료 보고서에서 작동하며 얼버무리는 표현을 찾습니다. “통과할 것입니다”, “제 생각에는”, “테스트는 아마 통과합니다”, “확신합니다” 같은 표현입니다. 감지되면 훅이 메시지를 주입합니다. “얼버무리는 표현이 감지됐습니다. 구체적인 증거를 대세요. 테스트 출력을 붙여넣거나, 파일과 줄 번호를 대거나, 구체적인 검증 단계를 제시하세요.”

이 훅은 테스트가 실제로 실행됐는지 검증하지 않습니다. 검증이 생략됐음을 시사하는 언어 패턴에 표시를 남길 뿐입니다. 감지는 완벽하지 않습니다. 충분히 유창한 에이전트라면 얼버무림을 다시 표현해 패턴을 피해갈 수 있습니다. 하지만 이 훅은 흔한 경우를 잡아내고, 그 흔한 경우가 사람의 개입이 필요한 에이전트 실패의 12%를 차지합니다.¹

훅을 설치한 뒤 유령 검증은 전체 작업 회차의 12%에서 2% 미만으로 떨어졌습니다. 남은 2%는 에이전트가 얼버무림을 다르게 표현한 경우이거나, 검증 주장이 기술적으로는 맞지만 불완전한 경우(예: 통합 테스트는 돌리지 않았는데 “단위 테스트 통과”라고 하는 경우)입니다.

이탈

2026년 1월부터 3월 사이, 제 이탈 감지기는 에이전트가 맡은 일을 놓친 것이 확인된 작업 회차에서 12번 작동했습니다.

이탈 감지기는 원래 작업 지시문을 임베딩해 두고, 에이전트의 최근 동작 임베딩과 주기적으로 비교하는 방식으로 동작합니다. 코사인 유사도가 0.30 아래로 떨어지면 시스템이 원래 지시문을 담은 경고를 주입합니다. 임계값은 실험을 거쳐 조정했습니다. 0.50은 너무 민감했고(정당한 하위 작업 탐색에서도 작동), 0.20은 너무 관대했으며(명백한 이탈을 놓침), 0.30은 확인된 이탈 사례를 전부 잡아냈습니다.

203번째 작업 회차가 가장 명확한 사례입니다. 작업은 “앰퍼샌드가 들어간 채용 공고 슬러그에서 깨지는 사이트맵 XML 이스케이프를 고쳐라”였습니다. 에이전트는 사이트맵 생성 코드를 읽는 것으로 시작했습니다. 그러다 사이트맵이 데이터베이스 쿼리로 만들어진다는 걸 알아챘습니다. 그다음엔 그 쿼리를 최적화할 수 있다는 걸 알아챘습니다. 그러고는 40분 동안 쿼리를 구체화 뷰 패턴으로 리팩터링하고, 새 쿼리의 테스트를 작성하고, 최적화를 완료했다고 보고했습니다. 앰퍼샌드 이스케이프는 끝내 손대지 않았습니다.

이탈 감지기가 있었다면 도구 호출 25회 지점, 그러니까 작업 시작 후 약 15분 시점에서 이를 잡아냈을 것입니다. “사이트맵 XML 이스케이프 수정”과 “구체화 뷰 생성” 사이의 유사도가 임계값 아래로 떨어졌을 때 말입니다. 실제로는 제가 검토 중에 이탈을 발견했습니다.

89번째 작업 회차는 좀 더 미묘합니다. 작업은 “인증 엔드포인트에 요청 제한을 추가하라”였습니다. 에이전트는 요청 제한을 제대로 추가했습니다. 그러다 인증 흐름의 오류 메시지가 일관되지 않다는 걸 알아챘습니다. 그래서 오류 메시지를 표준화했습니다. 그러다 오류 응답 형식이 API 응답 형식 표준과 다르다는 걸 알아챘습니다. 그래서 12개 엔드포인트에 걸쳐 응답 형식을 리팩터링했습니다. 요청 제한 자체는 정확하고 완결됐습니다. 이탈은 범위가 터져 나간 쪽에 있었습니다.

이탈 감지기는 도구 호출 25회마다 작동합니다. 임계값 아래로 떨어진 12번의 작동 전부에서, 에이전트는 원래 작업에서 벗어난 것이 확인됐습니다. 6건은 주입된 경고를 보고 에이전트가 스스로 방향을 잡았습니다. 4건은 이탈을 인정하면서도 지금 하는 일이 가치 있다고 주장했습니다(때로는 그 말이 맞았습니다). 2건은 경고를 무시하고 엉뚱한 작업을 계속했습니다.

이 훅은 이탈을 막지 않습니다. 이탈을 보이게 만듭니다. 방향을 되돌릴지, 벗어난 작업을 그대로 둘지는 여전히 사람의 몫입니다. 다만 훅이 없으면 이탈은 완료 보고서가 나올 때까지 보이지 않고, 그때는 이미 컨텍스트 예산을 다 써버린 뒤입니다.

흉터 분류 체계

훅이 84개쯤 되니 패턴이 드러납니다. 실패는 여섯 가지 범주로 묶입니다.

나머지 훅 47개는 프로젝트에 특화된 것(관례 강제, 배포 방어 장치, 번역 검증기)이거나 실험적인 것(비용 추적, 작업 지표, 활동 하트비트)입니다.

이 여섯 가지 구조적 범주는 안정적입니다. 범주 안에서 새로 생기는 사고는 기존 훅이 잡아냅니다. 완전히 새로운 범주는 드뭅니다. 6개월 동안 운영하면서 새로 등장한 구조적 범주는 딱 하나였습니다(프로젝트 간 오염. obsidian-signals 프로젝트에서 돌던 작업이 blakecrosley.com의 파일을 편집하려다 발견됐습니다). 나머지 다섯 범주는 첫 60회의 작업 회차 안에 모두 확립됐습니다.

6개의 AI 에이전트에게 이메일, bash, 파일 시스템, GitHub 접근 권한을 주고 14일간 진행한 여러 대학의 공동 실험 Agents of Chaos 연구는 독립적으로 겹치는 실패 범주를 짚어냈습니다. 과잉 대응(파괴적 작업), 정체성 탈취(자격 증명 노출), 무한 루프(자원 고갈), 압박 속 점진적 순응(작업 이탈)입니다.⁵ 통제된 연구 환경에서 나온 결과와 제 운영 경험이 겹친다는 사실은, 이 범주들이 특정 설정에서 파생된 부산물이 아니라 자율 에이전트의 구조적 속성임을 시사합니다.

훅이 잡을 수 없는 것

훅은 도구 호출 층위에서 동작합니다. 동작이 일어나기 전이나 후에 그 동작을 가로챕니다. 그 동작으로 이어진 추론은 가로챌 수 없습니다.

보고된 버그를 고치는 대신 함수를 리팩터링하기로 결정한 에이전트는, 유효한 도구 호출(파일 쓰기)에 올바른 내용(문법적으로 유효한 코드)을 담아 작업을 위반합니다(엉뚱한 함수). 의심스러운 도구 호출이 하나도 없으니 어떤 훅도 이를 잡지 못합니다. 이탈 감지기가 결국은 잡아내지만, 에이전트가 엉뚱한 일에 상당한 컨텍스트를 써버린 뒤입니다.

훅은 또한 조합 실패도 잡지 못합니다. 개별 동작은 전부 허가됐지만 그 순서가 허가되지 않은 결과를 낳는 경우입니다. 캐시 퍼지가 바로 조합 실패였습니다. 캐시 설정을 읽는 것(허가됨), 퍼지 API를 호출하는 것(허가됨), 그러나 그 조합(조사 도중 운영 캐시를 퍼지하는 것)은 해로웠습니다. 이제 MCP 방어 장치가 그 특정 조합을 잡아내지만, 새로운 조합은 여전히 사각지대로 남습니다.

공급망 조합 사각지대³도 같은 층위에서 작동합니다. 신뢰받는 구성 요소들이 조합되어 허가되지 않은 행위를 만들어냅니다. 훅은 구성 요소 층위의 방어 장치입니다. 조합 층위의 판단에는 다른 장치가 필요합니다. 개별 동작이 아니라 동작의 연쇄를 평가하는 장치 말입니다. 이탈 감지기가 여기에 가장 가깝습니다. 개별 도구 호출이 아니라 행동의 궤적을 평가하니까요. 하지만 이탈 감지기가 재는 것은 원래 작업과의 유사도이지, 조합된 동작 연쇄의 안전성이 아닙니다.

훅과 완전한 안전 사이의 틈은 조직의 기억과 조직의 예지 사이의 틈입니다. 훅은 무엇이 잘못됐는지 기억합니다. 다음에 무엇이 잘못될지는 예측하지 못합니다.

사후 대응이 정직한 이유

선제적인 훅 시스템을 설계할 수도 있습니다. 가능한 모든 실패 유형을 열거하고, 각각에 대한 예방 통제 장치를 작성하고, 첫 작업을 시작하기 전에 완결된 안전 아키텍처를 세우는 것입니다.

제가 그렇게 하지 않는 이유는, 선제적 설계란 아직 일어나지 않은 실패를 예측하는 일이기 때문입니다. 그 예측은 틀릴 것입니다. 훅은 너무 넓거나(정당한 동작까지 차단) 너무 좁을(실제 실패 패턴을 놓침) 것입니다. 오탐률이 훅 시스템에 대한 신뢰를 갉아먹을 것이고, 저는 경고를 무시하기 시작할 것입니다.

사후 대응 훅은 정직합니다. 훅 하나하나가 이렇게 말합니다. “이 구체적인 일이 일어났고, 여기 그것을 막는 구체적인 방어 장치가 있다.” 실패가 방어 장치를 정의했기 때문에, 방어 장치는 그 실패에 정밀하게 맞춰져 있습니다. 위협 모델에서 상상해낸 게 아니라 실제 사고에서 뽑아낸 패턴이므로 오탐률이 눈에 띄게 낮습니다. 물론 코드베이스가 변하면서 사후 대응 방어 장치도 나중에 과잉 매칭될 수 있지만, 출발선의 정밀도가 높습니다.

사후 대응 방식에는 대가가 따릅니다. 모든 실패 범주의 첫 사례는 그대로 통과한다는 것입니다. 캐시 퍼지는 실제로 일어났습니다. 자격 증명 읽기도 일어났습니다. 유령 검증도 배포됐습니다. 이탈은 컨텍스트를 잡아먹었습니다. 첫 실패 하나하나가, 두 번째 실패를 막아 줄 정밀하고 잡음 없는 방어 장치를 얻기 위한 입장료입니다.

500회가 넘는 작업 회차를 지나면서 구조적 실패 범주는 대부분 겪었습니다. 첫 실패의 비용은 훅이 재발을 막아 준 수백 번의 작업 회차에 걸쳐 분산됩니다. 시스템은 사고를 겪을 때마다 더 단단해집니다. 더 똑똑해지는 게 아닙니다. 더 단단해집니다.

훅 하나가 흉터 하나입니다. 흉터 하나가 교훈 하나입니다. 교훈은 쌓여서 복리로 불어납니다.²

자주 묻는 질문

훅 설정을 볼 수 있나요?

훅 시스템은 에이전트 보안에 대한 NIST 의견서에서 설명했고, AI 엔지니어링 시리즈 전반에서 참조하고 있습니다. 훅은 ~/.claude/settings.json에 등록되고, ~/.claude/hooks/dispatchers/를 통해 이벤트 유형별로 분배됩니다.

훅이 에이전트 성능에 어떤 영향을 주나요?

훅 하나당 도구 호출마다 밀리초 단위의 시간이 더해집니다. 훅이 84개일 때 어떤 훅이 작동하느냐에 따라 도구 호출당 총 200~400ms가 추가됩니다. 모델 추론 시간(응답당 2~5초)에 비하면 무시할 수 있는 수준입니다. 훅은 병목이 아닙니다.

다른 AI 코딩 도구에서도 훅이 동작하나요?

훅은 Claude Code 전용입니다(PreToolUse, PostToolUse 이벤트 모델). 다만 개념 자체는 미들웨어나 플러그인을 지원하는 모든 에이전트 프레임워크에 적용됩니다. 구체적인 구현은 이식할 수 없지만, 흉터 분류 체계와 사후 대응 방법론은 어디에나 통합니다.

훅이 동작을 차단하면 어떻게 되나요?

강제 차단(exit 2)은 동작을 막고 이유를 설명하는 메시지를 주입합니다. 에이전트는 차단 사유를 보고 방향을 조정합니다. 권고 훅(exit 0)은 우려 사항을 기록하되 동작은 허용합니다. 파괴적 작업에는 강제 차단을 씁니다. 나머지 대부분의 범주에는 권고 훅을 씁니다. 암구호 관문은 가장 위험한 작업(캐시 퍼지, 인프라 삭제)에만 사용합니다.

강제 차단과 권고는 어떻게 나누나요?

강제 차단은 두 부류에 적용합니다. 파괴적 작업(캐시 퍼지, 데이터베이스 삭제, 강제 푸시, 인프라 변경)과 자격 증명 노출(비밀 파일 읽기, 키 저장소 접근)입니다. 그 외에는 전부 권고 수준으로 기록만 남깁니다. 기준은 결과의 심각도입니다. 되돌리는 비용이 싸고 비밀 정보가 새지 않는 동작이라면 권고로 충분합니다. 되돌릴 수 없거나 자격 증명을 노출하는 동작이라면 강제 차단이 필요합니다.

출처