[공식문서읽기] Claude Code Hooks 완벽 가이드 - 자동화의 핵심

개요

Claude Code Hooks는 도구 실행 전후에 사용자 정의 명령을 자동으로 실행할 수 있는 강력한 기능입니다. 코드 포매팅 자동화, 민감한 파일 보호, 알림 전송 등 다양한 워크플로우를 구현할 수 있습니다.

특별히 의미있지 않은 이미지

Hooks란 무엇인가?

Hooks는 Claude Code 애플리케이션이 특정 이벤트 발생 시 자동으로 호출하는 사용자 정의 스크립트입니다. Claude AI가 아닌 Claude Code 시스템이 실행하므로, 결정론적이고 예측 가능한 자동화가 가능합니다.

주요 사용 사례

사용 사례	설명
자동 포매팅	파일 수정 후 Prettier, Black 등 자동 실행
린팅	코드 작성 시 ESLint, Pylint 자동 검사
파일 보호	.env, secrets 등 민감한 파일 접근 차단
알림	작업 완료 시 Slack, 시스템 알림 전송
환경 설정	세션 시작 시 가상환경 자동 활성화

Hook 이벤트 종류

특별히 의미있지 않은 이미지

 

Claude Code는 다양한 라이프사이클 이벤트를 지원합니다:

1. PreToolUse

도구 실행 직전에 호출됩니다. 도구 호출을 차단하거나 수정할 수 있습니다.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/validate-command.sh"
          }
        ]
      }
    ]
  }
}

2. PostToolUse

도구 실행 직후에 호출됩니다. 결과 검증이나 후처리에 사용합니다.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "prettier --write \"$CLAUDE_PROJECT_DIR\"/**/*.{js,ts}"
          }
        ]
      }
    ]
  }
}

3. SessionStart

세션 시작 시 호출됩니다. 환경 설정에 유용합니다.

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'source ~/.venv/bin/activate' >> \"$CLAUDE_ENV_FILE\""
          }
        ]
      }
    ]
  }
}

4. Stop / SubagentStop

Claude가 작업을 완료하려 할 때 호출됩니다. 작업 완료 여부를 검증할 수 있습니다.

5. UserPromptSubmit

사용자가 프롬프트를 제출할 때 호출됩니다. 입력 검증이나 컨텍스트 추가에 사용합니다.

설정 방법

Hooks는 settings.json 파일에서 구성합니다:

위치	용도
~/.claude/settings.json	전역 설정 (모든 프로젝트)
.claude/settings.json	프로젝트 설정 (팀 공유)
.claude/settings.local.json	로컬 설정 (개인용)

특별히 의미있지 않은 이미지

 

기본 구조

{
  "hooks": {
    "이벤트명": [
      {
        "matcher": "도구패턴",
        "hooks": [
          {
            "type": "command",
            "command": "실행할 명령"
          }
        ]
      }
    ]
  }
}

Matcher 패턴

• 정확히 일치: "Write" - Write 도구만
• 정규식: "Edit|Write" - Edit 또는 Write
• 와일드카드: "*" - 모든 도구

실전 예제

예제 1: Python 파일 자동 포매팅

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "black \"$CLAUDE_PROJECT_DIR\" --quiet"
          }
        ]
      }
    ]
  }
}

예제 2: 민감한 파일 보호

#!/usr/bin/env python3
import json
import sys

input_data = json.load(sys.stdin)
file_path = input_data.get("tool_input", {}).get("file_path", "")

PROTECTED = [".env", "secrets", "credentials"]

for pattern in PROTECTED:
    if pattern in file_path:
        print(f"접근 차단: {file_path}", file=sys.stderr)
        sys.exit(2)  # 종료 코드 2 = 차단

sys.exit(0)

예제 3: 작업 완료 알림

#!/bin/bash
# macOS 알림
osascript -e 'display notification "Claude Code 작업 완료!" with title "Claude Code"'

Hook 입출력

입력 (stdin)

Hooks는 JSON 형식으로 컨텍스트를 받습니다:

{
  "session_id": "abc123",
  "hook_event_name": "PreToolUse",
  "tool_name": "Write",
  "tool_input": {
    "file_path": "/path/to/file.txt",
    "content": "파일 내용"
  }
}

출력 (종료 코드)

종료 코드	의미
0	성공, 계속 진행
2	차단, stderr를 Claude에 표시
기타	비차단 오류, 경고만 표시

프롬프트 기반 Hooks

LLM을 활용한 지능형 결정도 가능합니다:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "모든 작업이 완료되었는지 평가하세요. 완료되면 {\"ok\": true}, 아니면 {\"ok\": false, \"reason\": \"이유\"} 반환"
          }
        ]
      }
    ]
  }
}

보안 주의사항

Hooks는 시스템에서 임의의 명령을 실행하므로 주의가 필요합니다:

1. 입력 검증 - 모든 입력 데이터를 검증하세요
2. 변수 인용 - $VAR 대신 "$VAR" 사용
3. 절대 경로 - 스크립트는 절대 경로로 지정
4. 민감 파일 제외 - .env, .git 등 주의

마무리

Claude Code Hooks는 개발 워크플로우를 자동화하는 강력한 도구입니다. 코드 품질 관리부터 보안까지, 반복적인 작업을 자동화하여 생산성을 크게 높일 수 있습니다.

핵심 포인트:

• PreToolUse로 사전 검증, PostToolUse로 후처리
• 종료 코드 2로 작업 차단
• settings.json에서 범위별 구성 가능
• 프롬프트 기반 hooks로 지능형 결정 가능

---

이 글은 Claude Code를 활용하여 작성되었습니다.

참고 자료:

• Claude Code Hooks 공식 문서
• Claude Code 설정 가이드