Claude Code Hooks 101: AI 코딩 어시스턴트를 자동화된 팀원으로 만들기

안녕하세요, Shrijith Venkatramana입니다. 저는 모든 커밋(commit)마다 실행되는 AI 코드 리뷰어인 git-lrc를 만들고 있습니다. 개발자들이 이 프로젝트를 발견할 수 있도록 Star를 눌러 도와주세요. 꼭 한 번 사용해 보시고 제품 개선을 위한 피드백을 공유해 주시기 바랍니다.

대부분의 개발자들은 Claude Code를 매우 똑똑한 터미널 어시스턴트처럼 사용합니다. 하지만 이것이 이벤트 시스템(event system)을 갖추고 있다는 사실을 깨닫는 사람은 거의 없습니다. 그리고 그 사실은 확장 가능성의 범위를 크게 변화시킵니다.

Hooks를 사용하면 Claude가 작업을 수행하는 도중에, 즉 명령이 실행되기 전, 파일이 변경된 후, 프롬프트(prompt)가 제출될 때, 세션(session)이 시작될 때, 심지어 MCP 도구(tool)가 호출될 때 등 Claude가 무엇을 하고 있는지 가로챌 수 있습니다. 이는 Claude Code가 단순한 "터미널 안의 AI"가 아니라, 프로그래밍 가능한 인프라(programmable infrastructure)가 된다는 것을 의미합니다.

여러분은 다음과 같은 일을 할 수 있습니다:

• 위험한 명령 차단 (block)
• 린터 (linters) 자동 실행
• 프로젝트 컨텍스트 (project context) 동적 주입
• 배포 검증 (validate deployments)
• Claude를 내부 도구에 연결
• 승인 시스템 구축
• 에이전트 루프 (agent loop) 자체를 중심으로 자율적인 워크플로우 구축

공식 Hooks 레퍼런스는 방대하고 포괄적입니다. 이 가이드는 제가 처음 이를 탐색할 때 가졌으면 좋았을 실용적인 "Hooks 101" 버전입니다.

1. Hooks란 실제로 무엇인가
   Claude Code hooks는 이벤트 기반 자동화 (event-driven automations)입니다. Hook은 Claude Code 내부에서 특정 상황이 발생할 때 실행됩니다.

예시:

이벤트	발생 시점
SessionStart	Claude 세션이 시작될 때
UserPromptSubmit	Claude가 프롬프트를 확인하기 전
PreToolUse	도구가 실행되기 전
PostToolUse	도구가 성공적으로 실행된 후
Stop	Claude가 응답을 마쳤을 때

공식 라이프사이클 (lifecycle) 다이어그램은 매우 방대합니다. Hooks가 Claude 실행 라이프사이클의 거의 전체를 다루기 때문입니다. 하지만 개념적으로는 간단합니다:

이벤트 발생 ↓ Hook이 JSON 컨텍스트 수신 ↓ 여러분의 코드가 무엇을 할지 결정

그게 전부입니다. Hook은 다음과 같은 역할을 할 수 있습니다:

• 관찰 (observe)
• 차단 (block)
• 수정 (modify)
• 컨텍스트 강화 (enrich context)
• 외부 시스템 트리거 (trigger external systems)
• 사람에게 알림 (notify humans)
• 상태 유지 (persist state)

AI 동작을 위한 미들웨어 (middleware)라고 생각하면 됩니다.

핵심 멘탈 모델 (Core Mental Model)

훅 (hook) 설정은 3개의 계층으로 구성됩니다:

{ "hooks" : { "PreToolUse" : [ { "matcher" : "Bash" , "hooks" : [ { "type" : "command" , "command" : "./check.sh" } ] } ] } }

이는 다음과 같이 매핑됩니다:

이벤트 (Event) ↓ 매처 (Matcher) ↓ 핸들러 (Handler)

이벤트 (Event): “어떤 라이프사이클 지점에 관심이 있는가?”
예시: PreToolUse, SessionStart, PostToolUse

매처 (Matcher): “무엇이 구체적으로 이를 트리거해야 하는가?”
예시: "matcher" : "Bash" 또는 "matcher" : "Edit|Write" 또는 정규표현식: "matcher" : "^Notebook"

핸들러 (Handler): “무엇이 실행되어야 하는가?”
예시: 셸 명령 (shell command), HTTP 엔드포인트 (HTTP endpoint), MCP 도구 (MCP tool), 프롬프트 평가 (prompt evaluation), 서브 에이전트 (subagent)

이 아키텍처는 놀라울 정도로 우아합니다. 이는 흔히 발생하는 “AI 플러그인 스파게티 (AI plugin spaghetti)” 현상을 방지합니다.

3. 당신의 첫 번째 유용한 훅 (Your First Useful Hook)

문서에 나와 있는 전형적인 예시는 파괴적인 셸 명령 (shell commands)을 차단하는 것입니다.

설정 (Configuration):
{ "hooks" : { "PreToolUse" : [ { "matcher" : "Bash" , "hooks" : [ { "type" : "command" , "if" : "Bash(rm *)" , "command" : "./block-rm.sh" } ] } ] } }

스크립트 (Script):

#!/bin/bash
COMMAND = $( jq -r '.tool_input.command' )
if echo " $COMMAND " | grep -q 'rm -rf' ; then
  jq -n '{ hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "deny", permissionDecisionReason: "Destructive command blocked" } }'
else
  exit 0
fi

이제 Claude는 말 그대로 rm -rf를 실행할 수 없습니다. 이는 매우 중요합니다. 대부분의 사람들은 AI 안전성 (AI safety)이 “더 나은 프롬프팅 (better prompting)”을 의미한다고 생각합니다. 하지만 훅은 실행 경계 (execution boundaries)에서 작동하기 때문에 프롬프팅보다 강력합니다. 이것은 제안이 아니라 정책 집행 (policy enforcement)입니다.

4. 가장 과소평가된 기능: 컨텍스트 주입 (Context Injection)

이 지점이 훅이 극도로 강력해지는 부분입니다. 훅은 Claude의 추론 루프 (reasoning loop)에 컨텍스트를 동적으로 주입할 수 있습니다. 문서에서는 이를 additionalContext라고 부릅니다.

예시:
{ "hookSpecificOutput" : { "hookEventName" : "PostToolUse" , "additionalContext" : "This file is generated. Edit schema.ts instead." } }

이는 Claude가 런타임 (runtime)에 컨텍스트 규칙을 학습한다는 것을 의미합니다. 이는 모든 내용을 CLAUDE.md에 밀어 넣는 것보다 훨씬 더 확장성이 높습니다.

다음 내용을 주입할 수 있습니다:

• 현재 git 브랜치 (current git branch)
• 배포 대상 (deployment target)
• CI 상태 (CI status)
• 활성 장애 (active incidents)
• 소유권 규칙 (ownership rules)
• 생성된 파일 경고 (generated-file warnings)
• 모노레포 전용 컨벤션 (monorepo-specific conventions)

그리고 훅 (hooks)은 조건부로 실행되기 때문에, 컨텍스트 (context)가 정적 (static)인 대신 적응형 (adaptive)이 됩니다. 이것이 많은 "AI 엔지니어링 (AI engineering)" 설정에서 빠져 있던 핵심 요소입니다. 사람들은 거대한 시스템 프롬프트 (system prompts)에 집착하지만, 동적 컨텍스트 시스템 (dynamic context systems)이 대개 더 중요합니다.

5. 훅은 기본적으로 내부 이벤트 버스 (Internal Event Bus)입니다
   이 개념을 이해하고 나면, 여러분의 아키텍처 (architecture)가 바뀝니다. Claude Code는 이벤트를 방출 (emit)하고, 훅은 이를 소비 (consume)합니다. 즉, AI 에이전트 루프 (AI agent loop) 자체를 중심으로 자동화를 구축할 수 있다는 의미입니다.

몇 가지 정말 흥미로운 패턴은 다음과 같습니다:

수정 후 자동 린트 (Auto-lint after edits)
{ "matcher" : "Edit|Write" }
실행: Claude가 파일을 수정한 직후에 ESLint, Ruff, cargo fmt, gofmt, typecheck를 실행합니다.

Bash 명령어를 위한 보안 검토 (Security review for Bash commands)
셸 실행을 가로챕니다: { "matcher" : "Bash" }
그 다음:

• 운영 DB 접근 차단 (deny production DB access)
• 자격 증명 노출 차단 (block credential exposure)
• curl | sh 탐지 (detect curl | sh)
• 안전하지 않은 Docker 명령어 방지 (prevent unsafe Docker commands)

AI 배포 승인 (AI deployment approvals)
배포 스크립트가 실행되기 전: { "if" : "Bash(kubectl apply *)" }
필수 사항: 티켓 번호 (ticket number), 스테이징 검증 (staging validation), 사람의 승인 (human approval), CI 성공 (CI success)

이것은 단순히 "AI를 믿으라"는 방식보다 실제 기업 거버넌스 (enterprise governance)에 훨씬 더 가깝습니다.

MCP 인식 워크플로 (MCP-aware workflows)
Claude 훅은 다음과 같은 패턴을 사용하여 MCP 도구 호출을 가로챌 수도 있습니다:
"matcher" : "mcp__github__.*" 또는 "matcher" : "mcp__memory__.*"

이는 흥미로운 가능성을 열어줍니다:

• MCP 사용량 감사 (audit MCP usage)
• 비용이 많이 드는 도구의 속도 제한 (rate limit expensive tools)
• 정책 계층 추가 (add policy layers)
• 쓰기 작업 검증 (validate writes)
• 도구 출력값 보강 (enrich tool outputs)

대부분의 사람들은 MCP 도구가 사실상 Claude의 운영 체제 (operating system)의 일부가 된다는 사실을 아직 깨닫지 못했습니다. 훅은 여러분이 그 OS를 계측 (instrument)할 수 있게 해줍니다.

6. 훅의 다섯 가지 유형
   문서에서는 다섯 가지 핸들러 (handler) 유형을 정의합니다. 각 유형은 서로 다른 아키텍처 스타일을 가능하게 합니다.

7. 커맨드 훅 (Command Hooks)
   셸 스크립트 (shell scripts)를 실행합니다. 가장 일반적입니다.
   { "type" : "command" }
   용도: 스크립트 검증 (scripts validation), git 통합 (git integration), 로컬 자동화 (local automation)

8. HTTP 훅 (HTTP Hooks)
   웹 서비스로 이벤트를 전송합니다.

{ "type" : "http" }

적합한 사례: 중앙 집중식 정책 엔진 (centralized policy engines), 텔레메트리 대시보드 (telemetry dashboards), 조직 전체의 거버넌스 (org-wide governance)
이 지점에서 기업용 도입이 본격화됩니다.

3. MCP 도구 훅 (MCP Tool Hooks)
MCP 도구를 직접 호출합니다.

{ "type" : "mcp_tool" }

적합한 사례: 내부 플랫폼 (internal platforms), 보안 도구 (security tooling), 지식 시스템 (knowledge systems), 자동화 프레임워크 (automation frameworks)

4. 프롬프트 훅 (Prompt Hooks)
다른 Claude 호출을 사용하여 동작을 평가합니다.

{ "type" : "prompt" }

예시: 이 명령이 위험해 보이는지 여부를 결정하십시오. 허용(allow) 또는 거부(deny)를 반환하십시오. 이는 AI가 AI를 감독하는 구조를 만듭니다.

5. 에이전트 훅 (Agent Hooks)
결정을 내리기 전에 조사할 수 있는 하위 에이전트 (subagents)를 생성합니다. 이는 가장 파격적인 카테고리입니다. 다음과 같은 에이전트를 가질 수 있습니다:
리포지토리 상태 검사, 정책 위반 사항 검색, 차이점(diffs) 분석, 다른 에이전트가 진행하기 전에 아키텍처 제약 조건 확인. 우리는 이제 "에이전트가 에이전트를 감독하는" 영역에 진입하고 있습니다.

7. 훅(Hooks)이 기존의 개발 자동화와 다른 점
훅은 단순히 미화된 Git 훅이 아닙니다. 차이점은 에이전트 루프 (agent loop) 내부의 배치에 있습니다.

기존의 자동화는 보통 다음과 같이 진행됩니다:
개발자 → 도구 → CI

훅은 추론(reasoning)과 실행(execution) 중에 발생합니다:
개발자 ↓ Claude 추론 ↓ 훅 가로채기 (Hook interception) ↓ 도구 실행 ↓ 훅 피드백 ↓ Claude 적응

이 피드백 루프가 중요합니다. Claude는 훅의 출력에 반응할 수 있습니다. 훅은 단순히 동작을 거부하는 것이 아닙니다. 세션 동안 에이전트의 미래 동작을 형성하는 것입니다. 이는 정적인 자동화 파이프라인과는 근본적으로 다른 모델입니다.

마치며
Claude Code 훅은 Claude를 다음과 같이 조용히 변화시킵니다:
"명령을 실행할 수 있는 AI 어시스턴트"에서
"정책, 오케스트레이션(orchestration), 그리고 적응형 컨텍스트(adaptive context)를 갖춘 프로그래밍 가능한 AI 런타임(runtime)"으로.

이는 훨씬 더 큰 개념입니다. 특히 MCP 생태계가 성숙해지면 더욱 그렇습니다. 저는 미래의 많은 "AI 엔지니어링 플랫폼"이 본질적으로 다음과 같을 것이라고 추측합니다:
모델, 도구, 이벤트 시스템, 정책 계층, 컨텍스트 주입 시스템... 그리고 훅은 개발자가 오늘날 실제로 만질 수 있는 그 아키텍처의 첫 번째 진지한 구현 중 하나입니다.

훅의 정신적 모델(mental model)을 이해하고 나면 전체 훅 레퍼런스를 읽어볼 가치가 있습니다.

그래서 이제 궁금해집니다. 여러분이 가장 먼저 만들고 싶은 훅은 무엇인가요? AI 에이전트는 코드를 빠르게 작성합니다. 하지만 사용자에게 알리지도 않고 조용히 로직을 제거하거나, 동작을 변경하고, 버그를 유발하기도 합니다. 이는 종종 프로덕션(production) 환경에서 발견되곤 합니다. git-lrc는 이를 해결합니다. git commit에 훅(hook)을 걸어 모든 diff를 반영하기 전에 검토합니다. 60초면 설정이 완료됩니다. 완전히 무료입니다. 피드백이나 기여자는 언제나 환영합니다! 이 프로젝트는 온라인에 공개되어 있으며, 소스 코드를 확인할 수 있고(source-available), 누구나 사용할 준비가 되어 있습니다. HexmosTech / git-lrc 무료, 커밋 시 실행되는 마이크로 AI 코드 리뷰 | 🇩🇰 Dansk | 🇪🇸 Español | 🇮🇷 Farsi | 🇫🇮 Suomi | 🇯🇵 日本語 | 🇳🇴 Norsk | 🇵🇹 Português | 🇷🇺 Русский | 🇦🇱 Shqip | 🇨🇳 中文 | git-lrc 무료, 커밋 시 실행되는 마이크로 AI 코드 리뷰 AI 에이전트는 코드를 빠르게 작성합니다. 하지만 사용자에게 알리지도 않고 조용히 로직을 제거하거나, 동작을 변경하고, 버그를 유발하기도 합니다. 이는 종종 프로덕션(production) 환경에서 발견되곤 합니다. git-lrc는 이를 해결합니다. git commit에 훅(hook)을 걸어 모든 diff를 반영하기 전에 검토합니다. 60초면 설정이 완료됩니다. 완전히 무료입니다. 작동 모습 보기 git-lrc가 유출된 자격 증명(credentials), 비용이 많이 드는 클라우드 작업, 로그 문구 내 민감한 자료와 같은 심각한 보안 문제를 잡아내는 모습을 확인하세요 git-lrc-intro-60s.mp4 왜 🤖 AI 에이전트가 조용히 문제를 일으킬까요. 코드가 제거됩니다. 로직이 변경됩니다. 엣지 케이스(edge cases)가 사라집니다. 프로덕션에 배포될 때까지 알아차리지 못할 것입니다. 🔍 배포되기 전에 잡아내세요. AI 기반의 인라인 코멘트(inline comments)가 무엇이 변경되었고 무엇이 잘못되어 보이는지 정확히 보여줍니다. 🔁 구축하기 … GitHub에서 보기