프롬프트에 "포맷 맞춰줘", "위험한 명령 실행하지 마"라고 적어본 적 있다면, 이미 한계를 경험한 것이다. LLM은 기억하지 않는다. 세션이 바뀌면 규칙도 희미해진다. 이 문제를 해결하는 구조가 바로 Claude Code Hooks다. 그리고 그 훅을 서브에이전트 설계와 결합하면, 팀 워크플로우 자동화가 비로소 '설정'이 아닌 '인프라' 수준으로 올라간다.
훅은 LLM의 의지와 무관하게 실행된다
dev.to에 공개된 Claude Code Hooks 가이드(2026년 4월 기준)를 보면, 훅은 단순한 편의 기능이 아니다. 훅은 결정론적 제어 레이어다. LLM이 무엇을 생성하든, 특정 이벤트가 발생하면 셸 명령이 자동으로 실행된다. PreToolUse는 도구 실행 전에 개입하고, PostToolUse는 실행 후 후처리를 강제한다. 핵심은 "Claude가 기억하는가"가 아니라 "이벤트가 발생했는가"다.
실무에서 가장 자주 쓰이는 패턴 두 가지를 짚어보자. 첫째, 자동 포맷팅. Claude가 파일을 편집하거나 작성할 때마다 Prettier가 자동으로 실행되도록 PostToolUse에 등록해두면, 포맷은 더 이상 개발자가 신경 쓸 항목이 아니다. 둘째, 위험 명령 차단. .env 파일 편집이나 git push --force를 시도하면 PreToolUse 훅이 exit code 2를 반환하며 실행 자체를 막는다. Claude는 차단 이유를 stderr로 받아 접근 방식을 수정하고, 팀은 실수를 사후에 복구하는 대신 사전에 봉쇄한다.
훅 타입은 네 가지다. command(셸 명령), http(웹훅 POST), prompt(Haiku 모델로 단발성 판단), agent(도구를 쓸 수 있는 서브에이전트 호출, 최대 50턴). 대부분의 팀 워크플로우는 command만으로 충분하다. 그러나 "이 커밋이 배포 가능한가"처럼 판단이 필요한 게이트를 만들 때는 agent 타입이 의미를 갖는다.
서브에이전트는 속도 해킹이 아니라 컨텍스트 정리 메커니즘이다
Bruce He의 Sub-Agent Architecture 아티클이 내린 정의가 팀 리드로서 가장 공감됐다. "서브에이전트는 병렬 속도 해킹이 아니다. 컨텍스트 가비지 컬렉션 메커니즘이다." 처음 컨텍스트 한계에 부딪히면 자연스럽게 팬아웃을 시도한다. 그런데 한 달 후 디버깅하다 보면 예외 없이 같은 문제를 만난다. 공유 메모리가 필요한 판단을 여러 콜드-스타트 프로세스에 분산시킨 탓에 출력이 서로 어긋나는 것이다.
서브에이전트가 진짜 효과를 내는 조건은 하나다. 높은 입력, 낮은 출력, 무상태(stateless). 코드베이스 검색, 로그 분석, 문서 트리아지가 전형적인 케이스다. 서브에이전트가 수십 개 파일을 읽고 grep을 돌린 뒤 요약본만 부모 에이전트에게 넘긴다. 부모는 노이즈를 보지 않아도 된다. 반대로, 이후 단계에서 부모가 반드시 알아야 할 중간 결과물이라면 서브에이전트로 분리하는 순간 손해다. 버려야 할 게 아니라 이어받아야 할 맥락이기 때문이다.
모델 라우팅에서도 팀이 흔히 저지르는 실수가 있다. "오케스트레이터는 가장 똑똑한 모델이어야 한다"는 가정이다. Bruce He의 케이스 스터디에서 "Opus 오케스트레이터 + Sonnet 워커" 구조를 "Sonnet 오케스트레이터 + Opus 라이터 + Haiku 서처" 구조로 바꾼 결과, 토큰 비용이 60% 줄었고 출력 품질은 올랐다. 오케스트레이션은 라우팅과 상태 추적이 주 업무다. Sonnet이면 충분하다. Opus는 최종 생성 단계, 판단이 복잡하게 쌓이는 지점에 투입해야 값어치를 한다. 서브에이전트 스폰 비용도 현실적으로 계산해야 한다. 시스템 프롬프트 재토크나이징, CLAUDE.md 리로드 오버헤드가 있어서 실제 작업이 2,000 토큰 수준이면 오버헤드가 작업량을 초과한다. 손익분기점은 서브에이전트당 약 10,000 입력 토큰이다.
하네스 관점에서 훅과 서브에이전트를 연결하면
Harness Engineering 아티클(dev.to)은 이 두 구성요소를 더 큰 그림 안에 배치한다. 하네스는 CLAUDE.md, Skills, MCP, Hooks, Sub-agents 다섯 요소로 이뤄진 AI의 작업장 설계다. 이 중에서 훅과 서브에이전트는 각각 다른 역할을 맡는다. 훅은 규칙을 강제하는 가드레일이고, 서브에이전트는 노이즈를 걸러내는 필터다. 이 둘을 연결하는 지점이 바로 agent 타입 훅이다. PreToolUse 훅이 서브에이전트를 스폰해 "이 파일 변경이 보안 정책에 위배되는가"를 50턴 이내에 검증하게 하고, 결과에 따라 allow 또는 deny를 반환한다. 프롬프트로 부탁하는 게 아니라 구조로 강제하는 것이다.
팀 레벨에서 실제 세팅을 설계한다면 이렇게 접근한다. 먼저 settings.json의 스코프 구조를 명확히 한다. 전역 훅(~/.claude/settings.json)에는 .env 차단, force push 차단처럼 어떤 프로젝트에서도 어겨선 안 될 규칙을 넣는다. 프로젝트 단위 훅(.claude/settings.json, 커밋 가능)에는 포맷터, 린터, 테스트 트리거를 배치한다. 개인 로컬 훅(.claude/settings.local.json, gitignore)에는 개발자별 알림이나 로컬 도구 연동을 둔다. 이 레이어를 구분해두면 온보딩 신규 팀원도 프로젝트 훅만 클론하면 팀 규칙이 자동 적용된다.
내일 팀에 적용할 수 있는 시작점
이론적으로는 모든 게 그럴듯하다. 현실에서 팀이 직면하는 문제는 "어디서부터 시작하는가"다. 세 가지만 먼저 잡는다. ① PostToolUse에 Prettier 훅 하나. 포맷 논쟁이 즉시 사라진다. ② PreToolUse에 .env 차단 스크립트. 사고는 예방이 복구보다 10배 싸다. ③ 코드베이스 검색 작업은 Haiku 서브에이전트로 분리. 메인 컨텍스트를 깨끗하게 유지하는 습관을 팀이 먼저 체화해야 더 복잡한 서브에이전트 아키텍처로 확장할 수 있다.
훅은 학습 곡선이 낮다. 셸 스크립트를 쓸 수 있으면 오늘 당장 배포할 수 있다. 서브에이전트 아키텍처는 모델 라우팅과 비용 계산이 따라와야 하니 한 주 정도 실험 기간이 필요하다. 그러나 이 두 가지를 제대로 설계한 팀과 그렇지 않은 팀의 차이는 시간이 지날수록 벌어진다. AI가 생성한 코드의 품질을 프롬프트 품질이 아니라 워크플로우 구조가 결정하는 세계가 이미 여기 있다.