한 줄 요약: 훅 시스템(Hook System)이란, 소프트웨어나 AI 에이전트에서 특정 이벤트(파일 저장, 도구 실행, 메시지 전송 등)가 발생할 때 미리 등록된 사용자 정의 코드를 자동으로 실행하는 이벤트 기반 콜백 메커니즘이다.

1. 훅 시스템이란 무엇인가?

낚시 훅(갈고리)처럼, 소프트웨어 훅은 특정 시점에 “걸려” 코드를 실행합니다. 피아노 선생님이 학생이 틀린 음을 치는 순간 바로 교정해 주는 것처럼, 훅은 이벤트 발생 시점에 정확히 개입합니다.

훅의 핵심 개념:

  • 이벤트(Event): 훅이 트리거되는 시점 (파일 저장, 커밋, API 호출 등)
  • 핸들러(Handler): 이벤트 발생 시 실행될 함수/스크립트
  • 훅 포인트(Hook Point): 이벤트가 발생하는 위치

2. 핵심 개념 이해하기

훅 유형별 분류

유형 설명 예시
Pre-hook 작업 실행 전 코드 린팅, 입력 검증
Post-hook 작업 실행 후 알림 전송, 로그 기록
Error hook 오류 발생 시 에러 리포팅, 롤백
Async hook 비동기 실행 백그라운드 처리

Claude Code 훅 시스템

Claude Code는 AI 작업 흐름에 사용자 정의 훅을 삽입할 수 있는 훅 시스템을 제공합니다:

AI 도구 실행 사이클:
  PreToolUse hook  →  도구 실행  →  PostToolUse hook
       ↑                                    ↓
  사용자 검증                          결과 로깅/알림

지원 이벤트:

  • PreToolUse: 도구 실행 전 (차단 가능)
  • PostToolUse: 도구 실행 후
  • Notification: 알림 발생 시
  • Stop: 응답 완료 시

Git 훅

git commit 실행
    ↓
pre-commit 훅 실행 (코드 린팅, 테스트)
    → 실패 시: 커밋 중단
    → 성공 시: 커밋 진행
    ↓
commit-msg 훅 (커밋 메시지 검증)
    ↓
post-commit 훅 (슬랙 알림 전송)

3. 실무 적용 예시

Claude Code 훅 설정 (.claude/settings.json)

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python scripts/validate_command.py"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "python scripts/log_file_change.py"
          }
        ]
      }
    ],
    "Notification": [
      {
        "matcher": ".*",
        "hooks": [
          {
            "type": "command",
            "command": "python scripts/send_slack.py"
          }
        ]
      }
    ]
  }
}

훅 스크립트 예시

# scripts/validate_command.py
# Bash 도구 실행 전 위험한 명령어 차단

import sys
import json

# Claude가 stdin으로 도구 정보 전달
tool_input = json.loads(sys.stdin.read())
command = tool_input.get("command", "")

DANGEROUS_PATTERNS = ["rm -rf", "DROP TABLE", "format c:", "> /dev/sda"]

for pattern in DANGEROUS_PATTERNS:
    if pattern in command:
        # exit code 2: 훅이 Claude에게 차단 메시지 전달
        print(json.dumps({
            "decision": "block",
            "reason": f"위험한 명령어 감지: {pattern}"
        }))
        sys.exit(2)

# exit code 0: 허용
sys.exit(0)

# scripts/log_file_change.py
# 파일 변경 시 자동 로그 기록

import sys
import json
from datetime import datetime

tool_result = json.loads(sys.stdin.read())
file_path = tool_result.get("file_path", "unknown")

with open("ai_changes.log", "a") as f:
    f.write(f"{datetime.now().isoformat()} | WRITE | {file_path}\n")

sys.exit(0)

4. 훅 시스템 vs 유사 개념 비교

구분 훅 시스템 미들웨어 이벤트 리스너
실행 시점 특정 이벤트 모든 요청/응답 이벤트 발생 시
차단 가능 ✅ (pre-hook) ✅ 제한적
비동기 선택적 보통 동기 ✅
적용 범위 특정 이벤트 전체 파이프라인 특정 이벤트
사용 사례 Git, Claude Code API 게이트웨이 UI, Node.js

5. 마치며

훅 시스템은 기존 시스템을 변경하지 않고 동작을 확장하는 강력한 패턴입니다. Claude Code의 훅 시스템을 활용하면 AI 작업에 보안 검증, 로깅, 알림을 추가할 수 있습니다. 비동기 훅(Async Hook)을 이해하면 성능에 영향 없이 백그라운드에서 추가 작업을 처리하는 고급 패턴을 구현할 수 있습니다.

참고 자료

함께 읽으면 좋은 용어

이 개념과 함께 알아두면 이해가 깊어지는 관련 용어들입니다.

비동기 훅 가드레일 관측 가능성 플러그인 시스템 루프 엔진

댓글 남기기

참고