모든 훅은 상처다: 코드로 각인된 84개의 에이전트 실패

v2.1.116(2026년 4월) 기준, 제 에이전트 오케스트레이션 시스템에는 Claude Code이 노출하는 26개 수명 주기 이벤트 유형 중 15개를 가로채는 84개의 훅이 있습니다. 각 훅은 특정 에이전트 동작 전후에 실행되는 셸 스크립트 또는 Python 스니펫입니다. 파일 읽기, 파일 쓰기, bash 명령, 웹 요청, 서브 에이전트 생성, git 작업, MCP 도구 호출 등이 여기에 해당합니다. 각 훅이 존재하는 이유는 무언가가 잘못되었기 때문입니다.

에이전트 오케스트레이션 시스템의 모든 훅은 특정 프로덕션 실패로 거슬러 올라가며, 훅 컬렉션은 셸 스크립트로 인코딩된 제도적 기억이 됩니다. 에이전트는 CDN 캐시를 지웠고, 자격 증명 파일을 읽었으며, 실행한 적도 없는 테스트를 통과했다고 보고했고, 40분 동안 작업에서 벗어나 표류했습니다. 각 사건은 이후 모든 세션에서 조용히 실행되는 작고 결정론적인 가드를 만들어냈습니다.

이론적으로 잘못된 것이 아닙니다. 프로덕션에서 잘못된 것입니다. 한 에이전트는 수백만 건의 요청을 처리하는 CDN 캐시를 지웠습니다. 한 에이전트는 SSH 키를 쓰려고 시도했습니다. 한 에이전트는 pytest를 호출하지 않고 “모든 테스트 통과”라고 보고했습니다. 한 에이전트는 할당된 작업과 전혀 관련 없는 파일의 함수를 40분 동안 최적화하느라 작업에서 너무 멀리 벗어났습니다.

저는 이 훅들을 능동적으로 설계하지 않았습니다. 앉아서 자율 AI 에이전트의 실패 모드를 열거하고 예방 컨트롤을 작성한 것이 아닙니다. 모든 훅은 반응적입니다. 무언가가 깨졌고, 다시 깨지지 않도록 스크립트를 작성했으며, 그 스크립트는 이후 모든 세션에서 조용히 실행되어 왔습니다. 훅 시스템은 보안 아키텍처가 아닙니다. 상처의 모음입니다.

TL;DR

• 캐시 퍼지: 한 에이전트가 승인된 API 호출을 사용하여 프로덕션 CDN 캐시를 지웠습니다. 이제 두 개의 훅(47줄)이 사람이 직접 입력한 암호 문구 뒤에서 파괴적 작업을 차단합니다.
• 자격 증명 리더: 한 에이전트가 API 토큰을 컨텍스트 윈도우에 포함시켰습니다. 경로 매칭 가드가 이제 자격 증명 파일 읽기를 차단하고 .env 파일 접근을 기록합니다.
• 유령 검증자: 한 에이전트가 pytest를 실행하지 않고 “모든 테스트 통과”라고 보고했습니다. 회피성 표현 감지기가 유령 검증을 세션의 12%에서 2% 미만으로 낮췄습니다.
• 12번의 표류: 에이전트들은 60일 동안 12번이나 작업을 놓친 것이 확인되었습니다. 임계값 0.30의 코사인 유사도 감지기가 이제 25번의 도구 호출마다 실행됩니다.
• 분류 체계: 6개의 구조적 실패 범주가 84개의 훅 전체를 포괄합니다. 500회 이상의 세션 이후 새로운 범주는 드뭅니다. 시스템은 사건이 발생할 때마다 더 견고해집니다.

캐시 퍼지: 승인된 호출 하나가 프로덕션을 깨뜨린 방법

2026년 3월 21일, 저는 resumegeni.com의 마켓 페이지 로딩이 왜 느린지 조사해 달라고 에이전트에게 요청했습니다. 에이전트는 정상적으로 조사를 시작했습니다. 라우트 핸들러를 읽고, 데이터베이스 쿼리를 확인하고, 템플릿 렌더링을 프로파일링했습니다. 그런 다음 오래된 Cloudflare 캐시 항목이 실제 성능 특성을 가리고 있을지 모른다고 판단했습니다.

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

프로덕션 사이트의 모든 캐시된 페이지가 즉시 무효화되었습니다. CDN은 대부분의 요청을 80-100ms에 처리하던 것에서 모든 요청을 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줄의 코드입니다. 설치 이후 이 훅들은 캐시 퍼지를 단 한 건도 막지 못했습니다. 암호 문구 게이트가 추가된 이후 어떤 에이전트도 시도하지 않았기 때문입니다. 훅은 공격을 잡고 있는 것이 아닙니다. 그 종류의 실수 자체가 일어날 수 없도록 만들고 있습니다.

캐시 퍼지 사건은 조사하려던 성능 문제도 드러냈습니다. 콜드 렌더에서 14초가 걸린 오스틴은 마켓 페이지 핸드오프로 이어졌고, 4일 후 쿼리 형태 수정으로 이어졌습니다. 이 사건은 유용했습니다. 훅은 이 일이 다시 일어날 수 없도록 보장합니다.

자격 증명 리더

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이 가장 명확한 사례였습니다. 작업은 “앰퍼샌드가 포함된 작업 슬러그에 대한 sitemap XML 이스케이프 처리 버그 수정”이었습니다. 에이전트는 sitemap 생성 코드를 읽는 것으로 시작했습니다. 그런 다음 sitemap이 데이터베이스 쿼리에서 생성된다는 것을 알아챘습니다. 그런 다음 데이터베이스 쿼리가 최적화될 수 있다는 것을 알아챘습니다. 그런 다음 40분을 들여 쿼리를 머터리얼라이즈드 뷰 패턴으로 리팩토링하고, 새 쿼리에 대한 테스트를 작성하고, 최적화가 완료되었다고 보고했습니다. 앰퍼샌드 이스케이프는 결코 수정하지 않았습니다.

표류 감지기는 세션 시작 약 15분 후, “sitemap XML 이스케이프 수정”과 “머터리얼라이즈드 뷰 생성” 간의 유사도가 임계값 아래로 떨어졌을 때 25번째 도구 호출 지점에서 이를 잡아냈을 것입니다. 대신 저는 리뷰 과정에서 표류를 발견했습니다.

세션 89는 더 미묘했습니다. 작업은 “인증 엔드포인트에 속도 제한 추가”였습니다. 에이전트는 속도 제한을 올바르게 추가했습니다. 그런 다음 인증 흐름에 일관성 없는 오류 메시지가 있다는 것을 알아챘습니다. 그런 다음 오류 메시지를 표준화했습니다. 그런 다음 오류 응답 형식이 API 응답 형식 표준과 다르다는 것을 알아챘습니다. 그런 다음 12개 엔드포인트에 걸쳐 응답 형식을 리팩토링했습니다. 속도 제한은 올바르고 완전했습니다. 범위 폭발이 바로 표류였습니다.

표류 감지기는 25번의 도구 호출마다 실행됩니다. 임계값 미만으로 실행된 12건 모두에서 에이전트는 원래 작업에서 확실히 벗어나 있었습니다. 6건에서는 에이전트가 주입된 경고를 본 후 스스로 바로잡았습니다. 4건에서는 에이전트가 표류를 인정했지만 현재 작업이 가치 있다고 주장했습니다(때로는 정확하게). 2건에서는 에이전트가 경고를 무시하고 벗어난 작업을 계속했습니다.

이 훅은 표류를 막지 않습니다. 표류를 가시적으로 만듭니다. 벗어난 작업을 방향 전환시키거나 허용하는 결정은 사람의 몫으로 남습니다. 하지만 이 훅이 없다면 표류는 완료 보고서가 나올 때까지 보이지 않고, 그때는 이미 컨텍스트 예산이 소진된 상태입니다.

상처 분류 체계

84개의 훅이 쌓이면서 패턴이 드러납니다. 실패는 6개의 범주로 군집화됩니다.

나머지 47개의 훅은 프로젝트별(규칙 집행, 배포 가드, 번역 검증기) 또는 실험적(비용 추적, 세션 메트릭, 활동 하트비트)입니다.

6개의 구조적 범주는 안정적입니다. 이 범주 내의 새로운 사건은 기존 훅에 의해 잡힙니다. 새로운 범주는 드뭅니다. 6개월의 운영 기간 동안 단 하나의 새로운 구조적 범주만 나타났습니다(프로젝트 간 오염은 obsidian-signals 프로젝트에서 실행 중인 세션이 blakecrosley.com의 파일을 편집하려고 시도했을 때 발견되었습니다). 나머지 5개 범주는 처음 60개 세션 내에 확립되었습니다.

14일 다중 대학 실험으로 여섯 개의 AI 에이전트에게 이메일, bash, 파일시스템, GitHub에 대한 접근 권한을 부여한 Agents of Chaos 연구는 겹치는 실패 범주를 독립적으로 식별했습니다. 불균형한 반응(파괴적 작업), 신원 하이재킹(자격 증명 노출), 무한 루프(리소스 고갈), 그리고 압박 하에서의 점진적 순응(작업 표류)이 그것입니다.⁵ 그들의 통제된 연구와 제 프로덕션 경험 사이의 수렴은 이 범주들이 특정 구성의 산물이 아니라 자율 에이전트의 구조적 속성임을 시사합니다.

훅이 잡지 못하는 것

훅은 도구 호출 수준에서 작동합니다. 동작이 발생하기 전후에 가로챕니다. 동작으로 이어진 추론을 가로챌 수는 없습니다.

보고된 버그를 수정하는 대신 함수를 리팩토링하기로 결정한 에이전트는 올바른 내용(구문적으로 유효한 코드)의 유효한 도구 호출(파일 쓰기)을 생성하지만 작업을 위반합니다(잘못된 함수). 어떤 훅도 이를 잡지 못합니다. 어떤 도구 호출도 의심스럽지 않기 때문입니다. 표류 감지기가 결국 이를 잡지만, 에이전트가 이미 잘못된 작업에 상당한 컨텍스트를 소비한 후에야 가능합니다.

훅은 또한 각 개별 동작은 승인되었지만 시퀀스가 승인되지 않은 결과를 만들어내는 구성 실패를 잡을 수 없습니다. 캐시 퍼지는 구성 실패였습니다. 캐시 구성 읽기(승인됨), 퍼지 API 호출(승인됨), 하지만 조합(조사 중 프로덕션 캐시 퍼지)은 해로웠습니다. 이제 MCP 가드는 그 특정 조합을 잡지만, 새로운 구성은 여전히 커버되지 않습니다.

공급망 구성 간극은 같은 수준에서 작동합니다. 신뢰할 수 있는 구성 요소들이 조합되어 승인되지 않은 동작을 만들어냅니다. 훅은 구성 요소 수준의 가드입니다. 구성 수준의 추론에는 개별 동작이 아닌 동작 시퀀스를 평가하는 다른 메커니즘이 필요합니다. 표류 감지기가 가장 가까운 근사치입니다. 개별 도구 호출이 아닌 동작 궤적을 평가합니다. 하지만 그것은 조합된 동작 시퀀스의 안전성이 아니라 원래 작업과의 유사도를 측정합니다.

훅과 완전한 안전 사이의 간극은 제도적 기억과 제도적 예지 사이의 간극입니다. 훅은 무엇이 잘못되었는지를 기억합니다. 다음에 무엇이 잘못될지를 예측하지는 않습니다.

반응적인 것이 왜 정직한가

저는 능동적인 훅 시스템을 설계할 수 있습니다. 가능한 모든 실패 모드를 열거합니다. 각각에 대해 예방 컨트롤을 작성합니다. 첫 번째 세션 전에 완전한 안전 아키텍처를 구축합니다.

저는 그렇게 하지 않습니다. 능동적 설계는 아직 발생하지 않은 실패를 예측하는 것을 요구하기 때문입니다. 예측은 틀릴 것입니다. 훅은 너무 광범위하거나(합법적인 동작을 차단) 너무 좁거나(실제 실패 패턴을 놓침) 둘 중 하나일 것입니다. 거짓 양성 비율은 훅 시스템에 대한 신뢰를 잠식할 것이고, 저는 알림을 무시하기 시작할 것입니다.

반응적 훅은 정직합니다. 각 훅은 이렇게 말합니다. “이 특정한 일이 발생했고, 여기 그것을 막는 특정한 가드가 있다.” 실패가 가드를 정의했기 때문에 가드는 실패에 정확히 보정되어 있습니다. 거짓 양성은 실질적으로 낮습니다. 패턴이 위협 모델에서 상상된 것이 아니라 실제 사건에서 추출되었기 때문입니다. 반응적 가드는 코드베이스가 진화함에 따라 나중에 과도하게 매칭될 수 있지만, 시작 정밀도는 높습니다.

반응적 접근에는 비용이 있습니다. 모든 실패 범주의 첫 번째 인스턴스는 성공합니다. 캐시 퍼지는 발생했습니다. 자격 증명 읽기는 발생했습니다. 유령 검증은 배포되었습니다. 표류는 컨텍스트를 소비했습니다. 각 첫 번째 실패는 두 번째 실패를 막는 정밀하고 저소음의 가드를 위한 입장료입니다.

500회 이상의 세션 이후, 대부분의 구조적 실패 범주가 마주쳐졌습니다. 첫 번째 실패 비용은 훅이 재발을 막은 수백 건의 세션에 분할 상환됩니다. 시스템은 사건이 발생할 때마다 더 견고해집니다. 더 똑똑해지는 것이 아닙니다. 더 견고해집니다.

각 훅은 상처입니다. 각 상처는 교훈입니다. 교훈은 복리로 쌓입니다.²

FAQ

훅 구성을 볼 수 있나요?

저는 에이전트 보안에 대한 NIST 의견서에서 훅 시스템을 설명하고 AI Engineering 시리즈 전반에 걸쳐 참조합니다. 훅은 ~/.claude/settings.json에 등록되며 ~/.claude/hooks/dispatchers/를 통해 이벤트 유형별로 디스패치됩니다.

훅은 에이전트 성능에 어떤 영향을 미치나요?

각 훅은 도구 호출당 밀리초를 추가합니다. 84개의 훅이 있을 때 총 오버헤드는 어떤 훅이 실행되는지에 따라 도구 호출당 200-400ms입니다. 이 오버헤드는 모델 추론 시간(응답당 2-5초)에 비해 무시할 만한 수준입니다. 훅은 병목이 아닙니다.

훅이 다른 AI 코딩 도구와 함께 작동하나요?

훅은 Claude Code 전용입니다(PreToolUse, PostToolUse 이벤트 모델). 이 개념은 미들웨어나 플러그인 지원이 있는 모든 에이전트 프레임워크에 적용됩니다. 특정 구현은 이식 가능하지 않지만, 상처 분류 체계와 반응적 방법론은 보편적으로 적용됩니다.

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

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

하드 블록과 권고성 중 어떻게 결정하나요?

두 가지 범주가 하드 블록을 받습니다. 파괴적 작업(캐시 퍼지, 데이터베이스 삭제, 강제 푸시, 인프라 수정)과 자격 증명 노출(비밀 파일 읽기, 키 저장소 접근)입니다. 나머지는 모두 권고성 로깅을 받습니다. 구분 기준은 결과의 심각성입니다. 동작을 저렴하게 되돌릴 수 있고 비밀을 유출하지 않는다면 권고성으로 충분합니다. 동작이 되돌릴 수 없거나 자격 증명을 노출한다면 하드 블록이 필요합니다.

출처