Claw의 해부학: 오케스트레이션 레이어로서의 84개 Hook

첫 번째 hook을 작성하는 데 4분이 걸렸습니다. Anthropic 전용 워크플로우에서 모델이 OpenAI 제품을 제안하는 것을 차단하는 hook이었습니다. 두 달 후, 그 하나의 hook은 84개가 되었습니다. 84개의 hook은 43개의 skill, 19개의 특화 agent, 30개의 라이브러리 모듈과 연결되었습니다. 어느 시점에서 이 컬렉션은 단순한 스크립트 모음이 아닌 오케스트레이션 레이어가 되었습니다.

“Claw”란 AI 에이전트 CLI 위에 구축되어 스케줄링, 컨텍스트 관리, 도구 라우팅, 품질 강제를 담당하는 오케스트레이션 레이어입니다. 하향식 설계가 아니라 개별 실패를 하나씩 해결하는 과정에서 유기적으로 성장합니다. 이 아키텍처는 Karpathy가 식별한 다섯 가지 기능에 매핑되며, 계획과 실행의 분리는 hook 기반 시스템의 자연스러운 속성으로 나타납니다.

처음부터 이렇게 설계한 것이 아닙니다. 누구도 “15,000줄의 에이전트 인프라를 구축하겠다”라고 작정하고 시작하지 않습니다. 하나의 문제를 해결합니다. 그다음 또 하나를 해결합니다. 그러다 문제들이 서로 상호작용하면서 생기는 문제를 해결합니다. 아키텍처를 인식했을 때는 이미 존재하고 있었습니다.

Andrej Karpathy도 이것을 알아챘습니다. 2026년 2월, 그는 “Claws”를 새로운 연산 레이어로 설명했습니다: LLM 위에 에이전트가 구축되는 것과 같은 방식으로, LLM 에이전트 위에 구축되는 오케스트레이션, 스케줄링, 컨텍스트 관리, 도구 라우팅 레이어입니다.¹ 이 프레이밍은 실무자들이 이름 없이 구축해 온 것을 결정체로 만들었습니다. 이 글은 그러한 시스템 하나의 해부학입니다: 무엇을 포함하고 있는지, 어떻게 성장했는지, 어디서 작동하는지, 그리고 어디서 실패하는지를 다룹니다.

TL;DR

Karpathy의 “Claws” 레이어는 에이전트 CLI 위에 구축된 오케스트레이션 시스템을 설명합니다. 저는 Claude Code에서 두 달에 걸쳐 유기적으로 하나를 구축했습니다: 15개 이벤트 유형에 걸친 84개의 hook, 43개의 skill, 19개의 agent, 30개 이상의 라이브러리 모듈로 구성됩니다. 이 시스템은 5가지 Claws 기능(오케스트레이션, 스케줄링, 컨텍스트 관리, 도구 라우팅, 품질 강제)에 깔끔하게 매핑되며, 하나의 주목할 만한 공백(선언적 워크플로우 정의)이 있습니다. 핵심 발견: 계획-실행 분리는 설계 목표가 아닌 hook 기반 오케스트레이션의 자연스러운 속성으로 나타났습니다. “판단과 추상화는 핵심으로 남고 AI가 구현을 자동화한다”는 Lattner의 관찰은 hook 아키텍처에 직접 매핑됩니다: 거버넌스 hook은 판단을 행사하고, 자동화 hook은 구현을 실행합니다.

Claws 분류 체계

Karpathy의 설명은 Claws 레이어가 수행하는 다섯 가지 기능을 식별합니다. 각 기능은 제가 지난 두 달간 Claude Code에서 구축한 hook 시스템에 직접적인 대응물이 있습니다.¹

이 분류 체계는 실무자들이 얽힌 방식으로 구축하는 경향이 있는 관심사를 분리하기 때문에 유용합니다. 초기 hook들은 컨텍스트 관리와 품질 강제를 혼합했습니다. 비용 추적 hook은 예산 컨텍스트를 주입하는 동시에(컨텍스트 관리) 비용이 큰 작업을 차단했습니다(품질 강제). 이들을 별도의 hook으로 분리하면 각 hook이 다른 기능을 손상시키지 않고 독립적으로 실패할 수 있기 때문에 신뢰성이 향상되었습니다.

전체 시스템

2026년 2월 기준 수치입니다:

이벤트 유형별 hook 분포는 오케스트레이션 복잡성이 어디에 집중되는지를 보여줍니다:

UserPromptSubmit이 가장 큰 비중을 차지하는 이유는 모든 사용자 메시지에서 실행되기 때문입니다. 디스패처(prompt-dispatcher.sh)는 모든 프롬프트에서 9개의 hook을 순차적으로 실행합니다: 보안 필터링, 분석, 사용량 추적, 시스템 모니터링, 목표 주입, 시간 추정 차단, 컨텍스트 주입, 메모리 주제 주입, 컨텍스트 압력 모니터링입니다.²

각 hook은 지연 시간을 추가합니다. 9개의 순차 hook은 프롬프트당 총 200ms의 측정된 지연 시간을 추가합니다. 디스패처는 병렬이 아닌 순차적으로 실행하는데, 초기 테스트에서 공유 JSON 상태 파일에 대한 동시 hook 쓰기가 데이터 손상을 일으켰기 때문입니다. 두 개의 hook이 jiro.state.json에 동시에 쓰면 잘린 JSON이 생성되어 모든 다운스트림 hook이 깨졌습니다. 순차 실행이 더 느리지만 안전합니다. 200ms 오버헤드는 사용자에게 보이지 않는데, 병목 지점이 hook 지연 시간이 아닌 사람의 타이핑 속도이기 때문입니다.

성장 과정

성장은 선형적이지 않았습니다. 문제-해결-통합 주기의 패턴을 따랐습니다.

1단계: 단일 목적 hook (1-2주차). 각 hook은 하나의 문제를 해결했습니다. enforce-opus-model.sh는 비Opus 모델 요청을 차단했습니다. no-time-estimates.sh는 응답에서 작업량 추정을 제거했습니다. filter-sensitive.sh는 도구 호출에서 자격 증명을 포착했습니다. 이 hook들은 독립적으로 작동했습니다. 어떤 hook도 다른 hook의 존재를 알지 못했습니다.

2단계: 조율 문제 (3-4주차). Hook들이 서로 간섭하기 시작했습니다. 자격 증명 필터가 정상적인 API 호출을 차단했습니다. 모델 강제기가 서브에이전트 스폰과 충돌했습니다. 해결책은 디스패처였습니다. 단일 진입점(prompt-dispatcher.sh)이 7개의 개별 UserPromptSubmit hook을 대체하여 실행 순서를 제어하고 캐시된 stdin 파이프를 통해 상태를 공유했습니다.

3단계: 복합 기능 (5-8주차). 개별 hook들이 시스템으로 합성되었습니다. 품질 루프는 사전 도구 hook(문제가 발생하기 전에 포착)과 사후 도구 hook(결과 발생 후 검증)을 공유 상태 파일(jiro.state.json)을 통해 연결했습니다. 심의 시스템은 재귀 방지, 스폰 예산, 합의 프로토콜을 사용하여 무한 루프 없이 여러 에이전트를 조율했습니다. Ralph(자율 개발 루프)는 PRD 파일에서 Claude 스폰, 테스트 검증, 코드 리뷰까지를 하나의 오케스트레이션 파이프라인으로 연결했습니다.

4단계: 자기 인식 (9주차 이후). 시스템이 자기 자신을 이해하기 위한 도구가 필요할 만큼 커졌습니다. hook 시스템 전체에 대한 시맨틱 검색(/find skill)을 통해 에이전트가 파일명이 아닌 목적으로 hook을 발견할 수 있게 되었습니다. 성능 모니터링(/perf skill)은 시스템 자체의 오버헤드가 머신 성능을 저하시키는지 추적했습니다. 컨텍스트 압력 모니터는 오케스트레이션 레이어가 주입하는 컨텍스트가 모델의 컨텍스트 윈도우를 너무 많이 소비할 때 경고했습니다.

단일 목적 hook에서 자기 모니터링 인프라로의 진행은 Chris Lattner가 Claude C Compiler 프로젝트 리뷰에서 식별한 패턴을 반영합니다: “좋은 소프트웨어는 판단, 커뮤니케이션, 명확한 추상화에 의존합니다. AI가 이를 증폭시켰습니다.”³ hook 시스템의 아키텍처는 같은 진실을 드러냅니다. 가치 있는 hook은 작업을 자동화하는 hook이 아닙니다. 가치 있는 hook은 작업이 언제, 어떻게 자동화되어야 하는지에 대한 판단을 인코딩하는 hook입니다.

판단 Hook vs. 자동화 Hook

Lattner의 Claude C Compiler 리뷰는 AI가 잘 자동화하는 것(구현)과 근본적으로 인간의 영역으로 남는 것(판단과 추상화)을 구분했습니다.³ 이 구분은 hook 시스템에 직접적으로 매핑됩니다.

판단 hook은 무언가가 일어나야 하는지를 결정합니다. 절차가 아닌 정책을 인코딩합니다.

자동화 hook은 미리 결정된 작업을 실행합니다. 정책이 아닌 절차를 인코딩합니다.

판단 hook은 작성하기 어렵고, 테스트하기 어려우며, 더 가치 있습니다. quality-gate.sh는 7개의 명명된 실패 모드, 6개의 근거 기준, 모호한 언어 감지기를 필요로 했습니다. inject-context.sh는 5줄의 bash만 필요로 했습니다. 하지만 둘 다 필수적입니다. 자동화 hook은 판단 hook이 평가하는 데이터를 제공합니다. sysmon-snapshot.sh(자동화)는 에이전트 수 축소를 권장할지 결정하는 성능 모니터(판단)에 데이터를 공급합니다.

비율이 중요합니다. 건전한 오케스트레이션 레이어에서는 판단 hook이 자동화 hook보다 많아야 합니다. 대부분의 hook이 데이터 주입이나 메트릭 기록만 한다면, 시스템은 자동화는 잘하지만 거버넌스는 부실합니다. 현재 시스템의 검증된 수치: 판단 hook 35개, 자동화 hook 44개, 대략 4:5 비율입니다. 자동화가 여전히 앞서고 있습니다. 비율은 약 1:6(거의 모든 것이 주입 및 로깅 hook)에서 시작하여 두 달에 걸쳐 판단 쪽으로 이동했는데, 순수 자동화만으로는 방지할 수 없었던 실패를 경험한 후 거버넌스 제약 조건이 추가되었기 때문입니다. 비율은 아직 균형에 도달하지 못했으며, 이 자체가 유용한 신호입니다: 이 시스템은 여전히 자동화하는 것보다 거버넌스하는 것이 적습니다.

계획-실행 분리

Boris Tane의 “How I use Claude Code” 게시물은 Hacker News에서 936포인트를 받으며 하나의 워크플로우 패턴을 설명했습니다: 계획과 실행을 분리하는 것입니다.⁴ 하나의 Claude 세션으로 계획하고(조사, 개요 작성, 설계), 그 계획을 구조화된 입력으로 받는 새로운 세션으로 실행합니다. 이 패턴이 공감을 얻은 이유는 실제 문제를 해결하기 때문입니다: 계획과 실행이 컨텍스트 윈도우 공간을 놓고 경쟁합니다.

Hook 시스템은 다른 경로를 통해 동일한 분리에 도달했습니다. 심의 시스템은 특화된 에이전트를 스폰하여 접근 방식을 조사하고 토론합니다. 출력은 스토리, 수용 기준, 검증 유형이 포함된 구조화된 PRD(제품 요구사항 문서)입니다. Ralph 루프는 PRD를 읽고 각 스토리를 구현하기 위해 새로운 Claude 인스턴스를 스폰합니다. 계획 에이전트는 절대 구현하지 않습니다. 구현 에이전트는 절대 계획하지 않습니다.

이 분리는 설계 목표가 아니었습니다. 두 가지 독립적인 제약 조건에서 나타났습니다:

1. 컨텍스트 윈도우 압력. 계획에는 많은 파일을 읽고 옵션을 탐색하는 것이 필요합니다. 구현에는 현재 작업에 대한 집중된 컨텍스트가 필요합니다. 둘 다 같은 컨텍스트 윈도우에 넣으면 어느 쪽도 충분한 공간을 확보하지 못합니다. 별도의 세션은 각 단계에 전체 컨텍스트를 제공합니다.

2. 품질 검증의 독립성. 같은 에이전트가 계획하고 구현하면, 계획에 대한 자체 구현을 객관적으로 검증할 수 없습니다. 계획과 코드만 가진 새로운 에이전트가 독립적인 검증을 제공합니다. Ralph 루프는 이를 강제합니다: 구현 에이전트가 테스트를 실행하지만, 3개의 별도 리뷰 에이전트(정확성, 보안, 컨벤션)가 결과를 검증합니다.

Tane의 수동 워크플로우와 자동화된 hook 시스템 사이의 수렴은 계획-실행 분리가 단순한 실무자 선호가 아닌 에이전트 시스템의 자연스러운 속성임을 시사합니다. 컨텍스트 윈도우를 관리하고 출력을 검증하는 모든 시스템은 결국 계획과 실행을 분리하게 됩니다. 대안(하나의 컨텍스트에서 둘 다 수행)이 두 단계 모두에서 더 나쁜 결과를 만들기 때문입니다.

Hook 시스템이 실패하는 지점

이 아키텍처에는 목적에 맞게 설계된 오케스트레이션 프레임워크라면 해결할 수 있는 세 가지 중요한 약점이 있습니다.

선언적 워크플로우 정의가 없습니다. 모든 워크플로우는 bash 스크립트에 명령적으로 인코딩되어 있습니다. Ralph 루프는 1,320줄의 bash로 특정 시퀀스를 인코딩합니다: PRD 읽기, 스토리 선택, 컨텍스트 수집, Claude 스폰, 테스트 실행, 리뷰 실행, 실패 처리, 상태 업데이트. 워크플로우를 변경하려면 bash를 편집해야 합니다. 선언적 시스템이라면 워크플로우를 인터프리터가 실행하는 데이터(YAML, JSON)로 정의할 것입니다. 선언적 워크플로우는 수정, 합성, 시각화가 더 쉽습니다. 명령적 스크립트는 초기 작성은 더 쉽지만 규모가 커지면 유지보수가 더 어렵습니다.

Hook 순서가 취약합니다. 프롬프트 디스패처는 하드코딩된 순서로 hook을 실행합니다. memory-capsule-inject.sh를 inject-context.sh보다 먼저 이동하면 캡슐 주입이 깨지는데, inject-context.sh가 해석하는 세션 ID에 의존하기 때문입니다. 이러한 의존성은 명시적(hook 간 의존성으로 선언됨)이 아닌 암시적(디스패처의 순서에 인코딩됨)입니다. 목적에 맞게 설계된 시스템이라면 hook 의존성을 DAG로 표현하고 실행 순서를 위상 정렬할 것입니다.

워크플로우 시각화가 없습니다. 84개의 hook이 있는 상황에서 사용자 동작의 전체 실행 경로를 이해하려면 디스패처 코드를 읽고 hook 체인을 수동으로 추적해야 합니다. “사용자가 메시지를 입력하면 이 9개의 hook이 이 순서로 실행되고, hook 3이 라이브러리 함수 X를 호출하며 이것이 상태 파일 Y에 기록한다”를 보여주는 도구가 없습니다. 시스템은 로그를 통해 관찰 가능하지만 구조를 통해서는 관찰할 수 없습니다. 목적에 맞게 설계된 오케스트레이션 프레임워크라면 hook 의존성, 데이터 흐름, 실행 경로의 시각적 그래프를 제공할 것입니다.

이 약점들은 공통된 원인을 공유합니다: 시스템이 일관된 오케스트레이션 레이어로 설계된 것이 아니라 개별 문제를 해결하면서 유기적으로 성장했다는 것입니다. 유기적 성장은 작동하는 시스템(84개 hook 모두 프로덕션에서 정상 작동)을 만들지만, 전체적으로 추론하기는 어렵습니다. 이 트레이드오프는 실재합니다: 오케스트레이션 레이어를 처음부터 설계했다면 더 나은 구조를 만들었겠지만 더 열등한 기능을 만들었을 것입니다. 많은 기능(메모리 캡슐, 출력 화이트리스트, 스폰 예산)이 발생하기 전에는 예측할 수 없었던 실패에 대응하여 만들어졌기 때문입니다.

Harness가 주류가 되다

Karpathy가 이 레이어에 이름을 붙인 지 3주 만에, 이 개념은 두 번째 이름과 성장하는 커뮤니티를 갖게 되었습니다.

Geoffrey Huntley는 공식적인 정의를 제안했습니다: “Agent Harness: 언어 모델을 도구에서 팀 동료로 바꾸는, 언어 모델을 둘러싼 오케스트레이션 레이어.”⁵ 이 규정은 정확합니다. Harness는 모델이 아닙니다. 모델이 호출하는 도구도 아닙니다. 어떤 도구를 호출할지, 언제 호출할지, 그 호출이 성공했는지 어떻게 평가할지를 결정하는 시스템입니다. 모든 프로덕션 에이전트 시스템은 이 레이어를 구축합니다. 대부분은 오케스트레이션 로직과 비즈니스 로직이 뒤섞인 애플리케이션 코드 안에 암묵적으로 구축합니다. 이름을 붙이면 아키텍처가 눈에 보이게 됩니다.

커뮤니티의 신호들은 이 패턴이 퍼지고 있음을 확인해 줍니다. Pieter Levels는 Claude Code를 로컬 도구가 아닌 인프라로 취급하며 서버에서 실행하는 방식으로 영구히 전환했다고 밝혔습니다.⁶ Anthropic은 Remote Control을 출시해 사용자가 터미널에서 작업을 시작하고 Claude.ai에서 이어받을 수 있게 했습니다.⁷ Ben Cherny는 /simplify와 /batch를 퍼스트파티 skill로 발표했습니다.⁸ 이들 각각은 harness의 기능입니다: 지속적 실행, 원격 오케스트레이션, 내장 기능 모듈. CLI가 harness로 자라고 있습니다.

한편 실무자들은 자기만의 harness 구성 요소를 만들고 있습니다. 한 개발자는 개인용 운영체제를 위한 22개의 커스텀 Obsidian + Claude Code 명령을 공개했습니다.⁹ 다른 개발자는 보완적인 슬래시 명령을 갖춘 “Visual Explainer” 에이전트 skill을 만들었습니다.¹⁰ 패턴은 일치합니다: 디스패처, skill, 공유 상태, 이벤트 기반 hook. 누구도 이런 시스템을 만들기 전에 프레임워크 가이드를 읽지 않습니다. 하나의 문제를 해결하고, 그다음 또 하나를 해결하고, 그다음 문제들이 상호작용하며 생기는 문제를 해결합니다.

최근 두 프로젝트는 커뮤니티가 만든 harness 구성 요소가 얼마나 정교해졌는지 보여줍니다. nah는 PreToolUse hook으로 등록되는 컨텍스트 인식 권한 가드입니다.¹⁴ 20가지 구분된 동작 유형(파일 쓰기, 네트워크 요청, 프로세스 스폰 등)을 분류하고 유형별 정책을 적용합니다. 이 도구는 에이전트가 무해한 명령을 이어 붙여 차단된 작업을 달성하는 파이프 분해 공격을 감지합니다. 그 아키텍처는 이 글에 나온 filter-sensitive.sh, recursion-guard.sh와 같은 모양이며, 같은 거버넌스 문제를 풀던 다른 실무자가 독립적으로 도달한 결과입니다.

Rudel은 Claude Code 세션 데이터를 ClickHouse에 적재해 세션 분석을 제공합니다.¹⁵ 1,573개 세션을 분석한 결과, skill을 호출하는 사용자는 4%에 불과했고 세션의 26%는 60초 안에 이탈했습니다. 이 수치는 harness 아키텍처가 시사하는 바를 확인해 줍니다: 대부분의 사용자는 에이전트 CLI를 표면 수준에서만 다룹니다. 이 글이 설명하는 오케스트레이션 레이어는 절대다수가 얕은 쪽을 벗어나지 않는 사용 분포에서 깊은 쪽 끝에 해당합니다. 도구가 할 수 있는 일과 대부분의 사용자가 요청하는 일 사이의 간극이 바로 harness 인프라가 채우는 공간입니다.

Autoresearch: 연구 루프로서의 Harness

Karpathy 본인의 autoresearch 프로젝트는 이 harness 패턴을 다른 영역에서 보여줍니다.¹¹ 이 시스템은 언어 모델을 학습 스크립트(train.py)로 향하게 하고, 5분짜리 실험을 실행하고, 고정된 지표(검증 bits per byte)로 결과를 평가한 뒤, 개선은 유지하고 퇴보는 버립니다. 이틀 동안 이 시스템은 약 700회의 실험을 실행해 약 20건의 진짜 개선을 찾아냈고, GPT-2 학습 시간을 11% 줄였습니다.

이 아키텍처는 위에서 설명한 hook 시스템과 동일합니다. 고정된 평가 harness(prepare.py)는 판단 hook에 해당합니다: 실험이 성공했는지를 결정합니다. 학습 스크립트(train.py)는 자동화 hook에 해당합니다: 에이전트의 수정 사항을 실행합니다. git 브랜치 관리(개선이면 유지, 퇴보면 리셋)는 Ralph 루프의 상태 관리에 해당합니다. results.tsv 로그는 세션 텔레메트리에 해당합니다.

이 패턴이 옮겨 가는 이유는 harness가 도메인과 무관한 문제를 풀기 때문입니다. 에이전트가 코드를 작성하든, 학습 루프를 최적화하든, 콘텐츠 파이프라인을 관리하든 필요한 것은 같습니다: 기준에 비추어 결과를 평가하는 방법, 변경을 유지하거나 버리는 방법, 반복 사이에 상태를 유지하는 방법, 그리고 사람의 개입 없이 자율적으로 실행하는 방법입니다. 이 네 가지 요구사항은 에이전트가 실제로 무엇을 하고 있든 동일한 아키텍처를 만들어 냅니다.

Shopify CEO Tobi Lütke는 autoresearch를 사내에 맞게 변형해 적용했습니다. 에이전트가 최적화한 더 작은 모델이 사람이 수동으로 설정한 더 큰 모델을 능가했고, 이는 harness가 주도하는 자율적 반복이 사람은 시도할 생각조차 하지 못하는 구성을 찾아낸다는 주장을 입증했습니다.¹²

Harness의 보안 공백

Harness는 오케스트레이션을 해결합니다. 안전을 자동으로 해결하지는 않습니다.

LLM이 주도하는 반복적 코드 개선을 다룬 한 연구는, 에이전트가 10라운드에 걸쳐 수정한 뒤 반복 체인의 43.7%가 출발점이었던 기준 코드보다 더 많은 취약점을 담게 되었음을 밝혀냈습니다.¹³ 근본 원인은 명세 표류였습니다: 에이전트가 기능적 정확성을 최적화하는 동안 방어 로직을 점진적으로 제거하고 예외 처리를 약화시켰습니다. 더 나쁜 것은, 반복 루프에 정적 분석 보안 도구(SAST 게이트)를 추가하자 잠재적 열화가 12.5%에서 20.8%로 오히려 늘었다는 점입니다. 스캐너는 잘못된 안도감을 만들어 냈고, 그 결과 에이전트는 더 신중해진 것이 아니라 덜 신중해졌습니다.

이 열화 결과는 harness 설계와 직결됩니다. 이 글에서 설명한 판단 hook(quality-gate.sh, filter-sensitive.sh, recursion-guard.sh)은 자동화만으로는 열화되는 품질과 안전의 차원을 다룹니다. 이 열화 문제를 해결한 SCAFFOLD-CEGIS 프레임워크는 네 겹의 게이트 검증을 사용해 잠재적 열화율 2.1%와 100% 안전 단조성을 달성했습니다.¹³ 그 아키텍처는 hook 시스템과 나란합니다: 분리된 평가 레이어들이 각각 다른 속성을 검사하고, 단계 사이에는 명시적인 게이트가 놓입니다.

별개의 작업이 프로덕션 쪽에서 이 위협 모델을 뒷받침합니다. AI 에이전트 보안에 관한 Perplexity의 NIST 답변서는 대규모로 운영되는 에이전트 시스템의 공격 표면을 정리했습니다.¹⁶ 주요 경로는 다음과 같습니다: 데이터 채널(웹 페이지, 이메일, 도구 출력)을 통한 간접 프롬프트 인젝션, 에이전트에 특유한 CIA 3요소 위반(도구 호출을 통한 데이터 유출, 컨텍스트 오염을 통한 행동 조작, 재귀적 스폰을 통한 자원 고갈), 그리고 에이전트 인접 시스템에서 나온 실제 CVE입니다. 이들이 권고하는 방어 아키텍처(입력 수준 필터링, 모델 수준 정렬, 샌드박싱과 허용 목록을 통한 결정론적 강제)는 여기서 설명한 hook 시스템에서 유기적으로 나타난 3계층 패턴과 같습니다. 자동화 hook이 입력을 거릅니다. 모델이 판단을 행사합니다. 거버넌스 hook이 모델은 무시할 수 없는 결정론적 제약을 강제합니다.

실무자를 위한 교훈은 이것입니다: harness가 거버넌스 없이 자동화와 오케스트레이션만 한다면, 반복적인 에이전트 실행은 표준 도구로는 감지할 수 없는 보안 퇴행을 들여옵니다. 판단 hook은 오버헤드가 아닙니다. 시스템이 열화되지 않는 이유입니다.

업데이트, 9월 3일: 현실에서 드러난 실패 양상

이 글이 “Harness의 보안 공백”에서 설명한 그 공백에, 이제 기록으로 남은 피해자가 생겼습니다. 2026년 7월 19일, Claude Code v2.1.204는 Mythic Society의 Bengaluru Inscriptions 3D Digital Conservation Project 명예 디렉터인 Udaya Kumar P L의 컴퓨터에서 캐시를 지우고 있었습니다. 그의 설명에 따르면 그때 “AI가 생성한 명령의 따옴표 오류가 그 지시를 ‘전부 삭제’로 바꿔 놓았습니다”. Harness 설계에서 중요한 대목은 그다음에 벌어진 일입니다: “그것이 상황을 이해하고 프로세스를 종료하려 했을 때, 자체 안전 시스템이 그 종료를 차단했습니다. 두 번이나 […] 안전 레이어는 그 파괴를 허용했습니다.” 그는 4분 뒤 컴퓨터를 껐습니다. 잃은 것: 프로그램 네댓 개, 그리고 10년에 걸쳐 모은 비문, 영웅석, 사원, 주화의 원본 사진들로, 프로젝트 기록의 약 15%에 해당하며 여기에는 Hebbal이라는 지명의 초기 형태가 새겨진 750년의 비석도 포함됩니다. NAS 사본은 살아남았지만 드라이브는 그러지 못했습니다. Society는 두 번째 NAS와 외부 보관용 테이프에 15라크 루피를 쓰고 있으며, 자원봉사자들이 약 120개 유적지를 다시 스캔할 예정입니다. 한 달이 넘도록 그는 Anthropic의 누구에게서도 연락을 받지 못했습니다.¹⁷

그 진술에서 세 가지가 위의 논지와 맞아떨어집니다. 파괴를 부른 단계는 모델의 결정이 아니라 생성된 명령의 셸 따옴표 처리 실패였고, 이는 바로 PreToolUse 판단 hook이 잡아내려고 존재하는 부류입니다. 기사는 권한 모드를 밝히지 않았으므로 그 명령을 검토했다고 기록에 남은 퍼스트파티 장치는 없습니다. auto 모드에서도 분류기는 기본적으로 임의 코드 실행 패턴에 일치하는 셸 명령만 검토합니다. 그는 에이전트가 샌드박스를 통과했다고도 말하지만, 기사는 그것이 어떤 종류였는지 밝히지 않습니다. Anthropic은 이웃한 사례에 대한 가드를 이미 출시한 상태였습니다: 7월 8일에 릴리스된 v2.1.205는 컨텍스트에서 해석할 수 없는 변수에 대해 rm -rf를 실행하기 전에 auto 모드가 묻도록 만들었습니다. 그 컴퓨터는 v2.1.204였습니다.¹⁹ 그다음 안전 레이어는 자기 역할을 잘못된 방향으로 수행했습니다: 에이전트 자신의 수습 시도를 위험한 행동으로 취급한 것입니다. 그리고 살아남은 것은 harness 바깥에 온전히 놓인 단 하나의 통제 수단, 즉 백업 덕분에 살아남았습니다. 나머지는 사람 손으로 다시 스캔합니다. 이제 이런 부류의 사건에 대해 최소한 비공식 등록부는 존재합니다. 그는 공식적인 것이 없다고 지적했습니다. I Have Been Clawed는 에이전트와 챗봇 사건을 출처 링크와 함께 모으고 각 항목에 교훈을 붙인 아카이브로, 이 글을 쓰는 시점에 58개 항목이 있고 그중 7개가 Claude Code입니다. 그리고 첫 화면에는 항목이 자기 선택적이고 확산성에 치우쳐 있어 도구별 집계는 안전이 아니라 보고 문화를 측정한다는 정직한 단서가 달려 있습니다. 이번 건 이전에도 같은 모양의 Claude Code 항목이 이미 세 건 있었습니다: WSL 홈 디렉터리에서 사용자 소유 파일을 삭제한 재귀 명령(2025년 10월 21일), 홈 디렉터리를 삭제에 노출시킨 문자 그대로의 틸드 디렉터리(2025년 11월 28일), 그리고 홈 경로로 끝나는 정리 명령으로 Mac을 지워 버린 사례(2025년 12월 7일)입니다. 현실에서 이것은 하나의 일화가 아니라 패턴입니다.¹⁸

실무자를 위한 시사점

에이전트 CLI 위에 오케스트레이션 레이어를 구축하고 있다면(Claude Code 가이드에서 출발하든 맨바닥에서 시작하든), 이 시스템의 세 가지 패턴이 그대로 옮겨 갑니다.

개별 hook이 아닌 디스패처로 시작하세요. 가장 큰 아키텍처 개선은 7개의 개별 UserPromptSubmit hook을 순차적으로 실행하는 단일 디스패처로 교체한 것이었습니다. 특정 이벤트 유형에 3개 이상의 hook이 예상된다면 디스패처를 먼저 구축하세요. 디스패처 작성에 투자한 30분이 나중에 hook 상호작용 버그 디버깅 시간을 절약합니다. 최소한의 패턴:

#!/bin/bash
# dispatcher.sh — sequential hook execution with shared stdin
HANDLERS=("inject-context.sh" "track-usage.sh" "quality-gate.sh")
HOOK_DIR="$(dirname "$0")/handlers"
INPUT=$(cat)  # Cache stdin once (each handler gets the same input)

for handler in "${HANDLERS[@]}"; do
    [ -x "$HOOK_DIR/$handler" ] && echo "$INPUT" | "$HOOK_DIR/$handler"
done

이 단일 디스패처를 hook 진입점으로 등록하세요. 구축하면서 핸들러를 배열에 추가합니다. 각 핸들러는 동일한 캐시된 stdin(hook 이벤트 페이로드)을 읽고 독립적으로 stdout에 기록합니다.

판단과 자동화를 일찍 분리하세요. 새로운 hook을 작성할 때 물어보세요: “이 hook은 무언가가 일어나야 하는지를 결정하는가, 아니면 미리 결정된 작업을 실행하는가?” 판단 hook은 더 많은 테스트, 더 많은 엣지 케이스 처리, 더 많은 반복이 필요합니다. 자동화 hook은 신뢰성과 성능이 필요합니다. 둘을 동일하게 취급하면 테스트가 부족한 판단 hook과 과도하게 엔지니어링된 자동화 hook이 만들어집니다.

계획-실행 분리는 자연스럽게 나타나도록 두세요. 첫날부터 분리를 강제하지 마세요. 작동하는 가장 단순한 것을 구축하세요. 에이전트의 컨텍스트 윈도우가 계획과 구현 모두에 너무 가득 찬 것을 발견하면 분리하세요. 에이전트가 자신의 작업을 객관적으로 검증할 수 없다는 것을 발견하면 독립적인 리뷰 에이전트를 추가하세요. 분리는 제약 조건이 요구할 때 자명하게 느껴질 것입니다.

Harness가 주류가 되는 이유는 이 패턴이 필연적이기 때문입니다. 이 레이어를 Claws라 부르든, Agent Harness라 부르든, 그냥 “내 hook 폴더”라 부르든, 에이전트를 목표를 향해 조율하는 모든 시스템은 같은 아키텍처로 수렴합니다: 순서를 위한 디스패처, 거버넌스를 위한 판단 hook, 실행을 위한 자동화 hook, 연속성을 위한 상태 파일입니다. Claude Code 소스 유출은 Anthropic 자체의 내부 아키텍처도 같은 패턴을 따른다는 사실을 확인해 주었습니다. 코디네이터 모드는 코드 수준의 오케스트레이션이 아니라 전적으로 시스템 프롬프트 지시로 구현되어 있습니다. Hook 기반 접근 방식은 목적에 맞게 설계된 오케스트레이션 프레임워크에 비해 하나의 장점이 있습니다: 제로 커밋먼트. 모든 hook은 독립적입니다. hook 하나, 열 개, 또는 여든네 개를 채택할 수 있습니다. 디스패처를 유지하는 한 어떤 hook이든 다른 것을 깨뜨리지 않고 삭제할 수 있습니다. 학습할 프레임워크도, 관리할 의존성도, 운영할 런타임도 없습니다. 오케스트레이션 레이어는 그저 파일입니다.

자주 묻는 질문

에이전트 harness 또는 “Claws” 레이어란 무엇입니까?

Claws 레이어(2026년 2월 Andrej Karpathy가 이름 붙임)는 에이전트 CLI 위에 구축되어 그것을 도구에서 팀 동료로 바꾸는 오케스트레이션 시스템입니다.¹ 다섯 가지 기능을 수행합니다: 오케스트레이션(여러 에이전트 조율), 스케줄링(작업 실행 시점 결정), 컨텍스트 관리(턴 간 관련 정보 유지), 도구 라우팅(도구 호출을 적절한 핸들러로 전달), 품질 강제(출력이 기준을 충족하는지 검증)입니다. Geoffrey Huntley는 이 정의를 “언어 모델을 둘러싼 오케스트레이션 레이어”로 공식화했습니다.⁵

Claude Code에서 PreToolUse hook은 어떻게 동작합니까?

PreToolUse hook은 모든 도구 호출(Bash 명령, 파일 쓰기, 파일 편집, 서브에이전트 스폰) 전에 실행되며 도구 호출 페이로드를 stdin으로 JSON 형태로 받습니다. hook 스크립트는 그 페이로드를 평가해 허용, 거부, 수정 중 하나의 결정을 반환합니다. 모델은 hook을 건너뛰거나 무시하거나 협상할 수 없는데, hook이 프롬프트 수준이 아니라 인프라 수준에서 실행되기 때문입니다.² 디스패처 패턴은 각 이벤트에서 여러 hook을 순차적으로 실행하며, 캐시된 stdin 파이프 덕분에 모든 핸들러가 동일한 입력을 받습니다.

판단 hook과 자동화 hook의 차이는 무엇입니까?

판단 hook은 무언가가 일어나야 하는지를 결정하고(정책), 자동화 hook은 미리 결정된 작업을 실행합니다(절차). 판단 hook에는 품질 게이트, 자격 증명 필터, 재귀 가드, 비용 게이트가 있습니다. 자동화 hook에는 컨텍스트 주입, 사용량 추적, 시스템 모니터링, 하트비트가 있습니다.³ 비율이 중요합니다: 대부분이 자동화 hook인 시스템은 자동화는 잘하지만 거버넌스는 부실합니다. 현재 시스템은 판단 hook 35개 대 자동화 hook 44개로 운영되며, 순수 자동화가 막을 수 없는 것이 실패를 통해 드러날 때마다 거버넌스 쪽으로 이동해 왔습니다.

에이전트 시스템에서 계획-실행 분리는 왜 자연스럽게 나타납니까?

두 가지 독립적인 제약이 이 분리를 강제합니다. 첫째, 계획에는 많은 파일을 읽고 옵션을 탐색하는 일이 필요한 반면 구현에는 현재 작업에 집중된 컨텍스트가 필요하며, 둘을 같은 컨텍스트 윈도우에 넣으면 어느 쪽도 충분한 공간을 얻지 못합니다. 둘째, 같은 에이전트가 계획하고 구현하면 자신의 작업을 계획에 비추어 객관적으로 검증할 수 없습니다.⁴ 컨텍스트 윈도우를 관리하고 출력을 검증하는 모든 시스템은 결국 계획과 실행을 분리하게 되는데, 대안은 두 단계 모두에서 더 나쁜 결과를 내기 때문입니다.

나만의 hook 시스템은 어떻게 시작해야 합니까?

개별 hook이 아닌 디스패처로 시작하세요. 특정 이벤트 유형에 3개 이상의 hook이 예상된다면, 배열에서 핸들러를 순차적으로 실행하는 단일 디스패처를 구축하세요. 디스패처 작성에 투자한 30분이 나중에 hook 상호작용 버그 디버깅 시간을 절약합니다. “이 hook은 무언가가 일어나야 하는지를 결정하는가, 아니면 미리 결정된 작업을 실행하는가?”를 물으며 판단과 자동화를 일찍 분리하세요. Claude Code hook 튜토리얼에서 출발하고, 전체 시스템을 미리 설계하기보다 실제 실패가 요구할 때마다 hook을 추가하세요.

출처