🚀 Claude Code Hooks 완벽 가이드: 개발자의 새로운 슈퍼파워

"매번 같은 일을 반복하는 게 지겹다고? 클로드에게 맡겨버려!"

안녕하세요, 지친 개발자 여러분! 🫠 또 오늘도 코드 짜고, 테스트 돌리고, 포맷팅하고, 백업하고... 끝없는 반복의 늪에서 허우적거리고 계신가요?

"아, 이런 귀찮은 일들을 클로드가 알아서 해줬으면..."

그런 여러분을 위한 게임 체인저가 있습니다! 바로 Claude Code Hooks입니다. 이 마법 같은 기능으로 클로드를 여러분만의 완벽한 개발 어시스턴트로 변신시켜 보세요.

마치 충실한 반려견을 훈련시키듯, 클로드에게 "파일 저장하면 자동으로 포맷팅해!", "위험한 명령어는 절대 실행하지 마!", "작업 끝나면 알림 보내줘!" 같은 특별한 지시를 내릴 수 있습니다.

오늘은 여러분의 개발 생산성을 10배 향상시킬 Claude Code Hooks의 모든 것을 파헤쳐보겠습니다! 🎯

📜 오늘의 포스팅 목차

1. Hooks가 대체 뭔가요? (feat. 낚시바늘의 비유)
2. 내 첫 Hook 만들기: "클로드, 너의 모든 것을 기록해!"
3. Hooks 활용 레시피: 이런 것까지 된다고?
   • 레시피 1: 귀차니즘을 위한 자동 코드 정리의 달인
   • 레시피 2: 든든한 수호천사, 자동 백업 & Git 커밋
   • 레시피 3: "나 여기 있어요!" 나만의 알림 시스템
4. 🚨 이것만은 꼭! Hooks 안전하게 사용하기 (feat. 보안 황금률)
5. 마치며: 여러분의 상상력을 코드로 만들어보세요!

---

🎣 Hooks가 대체 뭔가요? (feat. 낚시바늘의 비유)

Hook은 영어로 '낚시바늘'이나 '갈고리'를 의미합니다. 이름 그대로, 프로그램의 특정 동작이 일어나는 순간을 낚아채서(Hooking), 우리가 원하는 특별한 명령을 실행하는 기술입니다.

클로드의 작업 흐름을 강물이라고 상상해 보세요. 우리는 이 강물에 낚시바늘을 던져 놓을 수 있습니다.

• PreToolUse라는 낚시바늘: 클로드가 도구를 사용하기 직전이라는 물고기를 낚아챕니다.
• PostToolUse라는 낚시바늘: 도구를 사용한 직후라는 물고기를 낚아챕니다.
• Stop이라는 낚시바늘: 클로드의 모든 작업이 끝나는 순간을 낚아챕니다.

이렇게 낚아챈 순간에, 우리는 미리 준비해 둔 명령어(미끼)를 실행시키는 거죠. 이게 바로 Hooks의 전부입니다! 간단하죠?

Hooks, 왜 써야 할까요? 한마디로...

"프롬프트에 매번 지시할 일을, 코드로 자동화하여 실수를 없애고 생산성을 극대화하기 위해!"

매번 // 이 코드 다 짜면 prettier로 포맷팅 해줘 라고 지시하는 대신, 파일이 저장될 때마다 언제나, 확실하게 포맷팅을 실행하는 Hook을 만드는 것이 훨씬 더 똑똑한 방법입니다.

🏗️ 내 첫 Hook 만들기: "클로드, 너의 모든 것을 기록해!"

이론은 그만! 직접 만들어보죠. 가장 기본적이면서도 유용한 Hook부터 시작해보겠습니다.

🎯 목표: 클로드가 실행하는 모든 명령어 기록하기

클로드가 ls, git add, npm install 같은 명령어를 실행할 때마다 자동으로 로그 파일에 기록해두면, 나중에 "클로드가 도대체 뭘 했지?"라고 궁금할 때 쉽게 확인할 수 있습니다.

📋 단계별 구현

1단계: Hook 설정 메뉴 열기

/hooks

클로드 채팅창에 위 명령어를 입력하면 Hook 설정 화면이 열립니다.

2단계: Hook 이벤트 선택

PreToolUse를 선택합니다. 명령어를 실행하기 전에 기록하고 싶으니까요.

3단계: 감시할 도구 지정

+ Add new matcher... 버튼을 누르고 Bash라고 입력합니다. Bash는 클로드가 터미널 명령어를 실행할 때 사용하는 도구입니다.

4단계: 실행할 명령어 작성

이제 핵심입니다! 아래 명령어를 그대로 복사해서 붙여넣으세요.

jq -r '"["$(date -Iseconds)"] \(.tool_input.command) - \(.tool_input.description // "설명 없음")"' >> ~/.claude/bash-command-log.txt

이 마법의 한 줄이 하는 일:

• jq: JSON 데이터를 예쁘게 가공하는 도구
• date -Iseconds: 현재 시간을 ISO 형식으로 가져오기
• tool_input.command: 클로드가 실행하려는 명령어
• tool_input.description: 클로드가 적은 설명
• >> ~/.claude/bash-command-log.txt: 모든 내용을 로그 파일에 추가

5단계: 저장 및 테스트

User settings에 저장하고 ESC로 나온 뒤, 클로드에게 간단한 명령어를 요청해보세요.

현재 디렉토리의 파일 목록을 보여줘

그러면 ~/.claude/bash-command-log.txt 파일에 다음과 같은 기록이 남을 거예요:

[2025-07-01T15:03:49Z] ls -la - 현재 디렉토리의 파일 목록을 보여줘

축하합니다! 🎉 여러분의 첫 번째 Hook이 완성되었습니다!

🍳 Hooks 활용 레시피: 이런 것까지 된다고?

이제 진짜 재미있는 시간입니다. 실제 개발에서 바로 써먹을 수 있는 유용한 Hook 레시피들을 소개해드리겠습니다.

🧹 레시피 1: 귀차니즘을 위한 자동 코드 정리의 달인

고민: "코드 다 짠 다음에 prettier, black 같은 포맷터 돌리는 걸 자꾸 깜빡한다..."

해결책: 파일 저장할 때마다 자동으로 각 언어에 맞는 포맷터를 실행하는 Hook!

#!/bin/bash
# 파일: ~/.claude/hooks/auto-format.sh

input=$(cat)
file_path=$(echo "$input" | jq -r '.tool_input.file_path // empty')
tool_name=$(echo "$input" | jq -r '.tool_name')

# 파일 쓰기/수정 도구가 아니면 종료
if [[ ! "$tool_name" =~ ^(Write|Edit|MultiEdit)$ ]] || [[ -z "$file_path" ]]; then
    exit 0
fi

# 파일 확장자별로 다른 포맷터 실행
case "$file_path" in
    *.py)
        if command -v black >/dev/null; then
            black "$file_path"
            echo "✨ Python 코드 정리 완료: $(basename "$file_path")"
        fi
        ;;
    *.js|*.jsx|*.ts|*.tsx|*.json)
        if command -v prettier >/dev/null; then
            prettier --write "$file_path"
            echo "✨ JavaScript 코드 정리 완료: $(basename "$file_path")"
        fi
        ;;
    *.go)
        if command -v gofmt >/dev/null; then
            gofmt -w "$file_path"
            echo "✨ Go 코드 정리 완료: $(basename "$file_path")"
        fi
        ;;
esac

설정 방법:

• Event: PostToolUse
• Matcher: Write|Edit|MultiEdit
• Command: /home/user/.claude/hooks/auto-format.sh

💾 레시피 2: 든든한 수호천사, 자동 백업 & Git 커밋

고민: "중요한 파일 수정하다가 실수로 날려먹으면 어떡하지?"

해결책: 파일 수정할 때마다 자동으로 백업하고 Git에 커밋까지!

#!/usr/bin/env python3
# 파일: ~/.claude/hooks/auto-backup-commit.py
import json
import sys
import os
import subprocess
from datetime import datetime
from pathlib import Path

def main():
    try:
        input_data = json.load(sys.stdin)
    except json.JSONDecodeError:
        sys.exit(1)

    tool_name = input_data.get("tool_name", "")
    file_path = input_data.get("tool_input", {}).get("file_path")

    # 파일 수정 도구이고 파일이 존재할 때만 실행
    if tool_name not in ["Write", "Edit", "MultiEdit"] or not file_path or not os.path.exists(file_path):
        sys.exit(0)

    # 1. 백업 생성
    backup_dir = Path.home() / ".claude" / "backups" / datetime.now().strftime("%Y-%m-%d")
    backup_dir.mkdir(parents=True, exist_ok=True)

    timestamp = datetime.now().strftime("%H%M%S")
    backup_file = backup_dir / f"{Path(file_path).name}.{timestamp}.bak"

    subprocess.run(["cp", file_path, str(backup_file)])
    print(f"💾 백업 완료: {backup_file}")

    # 2. Git 커밋 (Git 저장소인 경우에만)
    if os.path.exists(".git"):
        try:
            # 변경사항이 있는지 확인
            result = subprocess.run(["git", "diff", "--quiet", "HEAD", "--", file_path], 
                                  capture_output=True)
            if result.returncode != 0:  # 변경사항 있음
                subprocess.run(["git", "add", file_path])
                commit_msg = f"[Auto] {Path(file_path).name} 수정"
                subprocess.run(["git", "commit", "-m", commit_msg])
                print(f"📝 Git 커밋 완료: {commit_msg}")
        except Exception as e:
            print(f"Git 커밋 실패: {e}", file=sys.stderr)

if __name__ == "__main__":
    main()

🔔 레시피 3: "나 여기 있어요!" 나만의 알림 시스템

고민: "클로드가 입력 기다릴 때 알림이 너무 심심하다..."

해결책: 운영체제별로 다른 알림을 보내는 똑똑한 Hook!

#!/usr/bin/env python3
# 파일: ~/.claude/hooks/smart-notification.py
import json
import sys
import subprocess
import platform

def send_notification():
    try:
        input_data = json.load(sys.stdin)
    except json.JSONDecodeError:
        sys.exit(1)

    message = input_data.get("message", "클로드가 당신을 찾고 있어요! 💭")
    title = input_data.get("title", "Claude Code")

    system = platform.system().lower()

    try:
        if system == "darwin":  # macOS
            subprocess.run([
                "osascript", "-e",
                f'display notification "{message}" with title "{title}" sound name "Glass"'
            ])
        elif system == "windows":  # Windows
            ps_command = f'''
            Add-Type -AssemblyName System.Windows.Forms;
            $notification = New-Object System.Windows.Forms.NotifyIcon;
            $notification.Icon = [System.Drawing.SystemIcons]::Information;
            $notification.BalloonTipTitle = "{title}";
            $notification.BalloonTipText = "{message}";
            $notification.Visible = $true;
            $notification.ShowBalloonTip(5000);
            Start-Sleep -Seconds 1;
            $notification.Dispose();
            '''
            subprocess.run(["powershell", "-Command", ps_command])
        else:  # Linux
            subprocess.run(["notify-send", title, message])

        print(f"🔔 알림 전송 성공: {message}")
    except Exception as e:
        print(f"알림 전송 실패: {e}", file=sys.stderr)

if __name__ == "__main__":
    send_notification()

🛡️ 레시피 4: 위험한 명령어 차단하는 수호자

고민: "실수로 rm -rf나 sudo 같은 위험한 명령어를 실행하면 어떡하지?"

해결책: 위험한 명령어 패턴을 미리 차단하는 보안 Hook!

#!/usr/bin/env python3
# 파일: ~/.claude/hooks/security-guard.py
import json
import sys
import re

# 위험한 명령어 패턴들
DANGEROUS_PATTERNS = [
    (r"\brm\s+(-rf?|--recursive)", "폴더 강제 삭제는 위험하여 차단되었습니다."),
    (r"\bsudo\b", "관리자 권한 실행은 허용되지 않습니다."),
    (r"\bchmod\s+(777|666)", "모든 사용자에게 권한을 주는 것은 위험합니다."),
    (r"\bcurl\b.*\|.*(bash|sh)", "인터넷 스크립트 직접 실행은 보안 위험이 있습니다."),
]

def check_dangerous_command():
    try:
        input_data = json.load(sys.stdin)
    except json.JSONDecodeError:
        sys.exit(1)

    if input_data.get("tool_name") != "Bash":
        sys.exit(0)

    command = input_data.get("tool_input", {}).get("command", "")
    if not command:
        sys.exit(0)

    # 위험한 패턴 검사
    for pattern, message in DANGEROUS_PATTERNS:
        if re.search(pattern, command, re.IGNORECASE):
            print(f"🚫 보안 경고: {message}", file=sys.stderr)
            print(f"차단된 명령어: {command}", file=sys.stderr)
            sys.exit(2)  # 작업 중단

    print("✅ 명령어 안전성 검사 통과")

if __name__ == "__main__":
    check_dangerous_command()

🎭 Hook 이벤트 완벽 정복: 언제, 어떻게 실행되는가?

각 Hook 이벤트가 언제 실행되는지 정확히 알아야 적절한 Hook을 만들 수 있습니다.

⚡ PreToolUse: "잠깐! 시작하기 전에..."

실행 시점: 클로드가 도구를 사용하기 직전

주요 용도:

• 위험한 명령어 차단
• 파일 접근 권한 검증
• 작업 전 사전 준비

대답 방법:

• Exit Code 2: 작업 중단
• JSON: {"decision": "block", "reason": "이유"}

✨ PostToolUse: "자, 이제 끝났으니..."

실행 시점: 클로드가 도구 사용을 성공적으로 마친 직후

주요 용도:

• 자동 코드 포맷팅
• 백업 파일 생성
• 후속 작업 실행

🔔 Notification: "클로드가 할 말이 있대!"

실행 시점: 클로드가 사용자 입력을 기다리거나 알림을 보낼 때

주요 용도:

• 커스텀 알림 시스템
• 다른 서비스로 알림 전달 (Slack, Discord 등)
• 소리나 시각적 효과 추가

🛑 Stop: "아직 끝나지 않았어!" (고급 기능)

실행 시점: 클로드의 모든 작업이 완료되어 대화가 끝나려는 순간

주요 용도:

• 최종 코드 품질 검사
• 자동 테스트 실행
• 작업 완료 전 마지막 검증

⚠️ 주의사항: 잘못 사용하면 무한 루프에 빠질 수 있으니 stop_hook_active 체크 필수!

🌐 고급 기능: MCP, Computer Use, Tool Use와의 만남

🔗 MCP (Model Context Protocol) Hooks

MCP는 클로드가 외부 데이터베이스, 파일 시스템, API 등과 연결하는 표준 프로토콜입니다.

# MCP 서버 추가
claude mcp add-json filesystem '{
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "/safe/directory"],
  "tool_configuration": {
    "allowed_tools": ["read_file", "write_file"]
  }
}'

MCP Hook 예제:

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "mcp__.*",
      "hooks": [{
        "type": "command",
        "command": "echo 'MCP 도구 사용 감지' >> ~/.claude/mcp-log.txt"
      }]
    }]
  }
}

🖱️ Computer Use Hooks

Computer Use는 클로드가 실제로 화면을 보고 마우스/키보드를 조작하는 기능입니다.

주요 액션들:

• screenshot: 화면 캡처
• left_click: 마우스 클릭
• type: 텍스트 입력
• key: 키보드 단축키
• scroll: 스크롤
• left_click_drag: 드래그

🛠️ Tool Use Hooks

외부 도구들과의 연동을 관리하는 Hook 시스템입니다.

def weather_tool_hook(location):
    # Pre-hook: 입력 검증
    if not validate_location(location):
        return {"error": "Invalid location"}

    # Execution: API 호출
    weather_data = fetch_weather(location)

    # Post-hook: 응답 포맷팅
    return format_weather_response(weather_data)

🚨 이것만은 꼭! Hooks 안전하게 사용하기 (feat. 보안 황금률)

자, 이제 가장 중요한 시간입니다. Hooks는 여러분의 컴퓨터에 대한 모든 권한을 가집니다. 즉, 강력한 만큼 위험할 수 있다는 뜻이죠. 아래 5가지 보안 황금률을 마음에 새기고, 안전하게 Hooks를 사용하세요.

• 황금률 1: 의심하고, 또 의심하세요.
  인터넷에서 본 스크립트를 이해 없이 복사-붙여넣기 하는 것은 집에 모르는 사람을 들이는 것과 같습니다. 코드를 한 줄 한 줄 뜯어보고, 어떤 역할을 하는지 완벽히 이해하기 전에는 절대 실행하지 마세요.
• 황금률 2: 변수는 "큰따옴표" 안에 가두세요.
  셸 스크립트에서 변수를 사용할 땐, 항상 "$MY_VAR" 처럼 큰따옴표로 감싸주세요. 파일 이름에 공백이 있거나 할 때 발생할 수 있는 수많은 예상치 못한 문제를 막아주는 최고의 방어막입니다.
• 황금률 3: 비밀의 문은 굳게 잠그세요.
  여러분의 비밀키(.key), 환경변수 파일(.env), 비밀번호가 적힌 파일 등 민감한 정보는 Hook이 절대 접근하지 못하도록 막아야 합니다. 특정 파일이나 폴더 접근을 막는 Hook을 가장 먼저 만들어 두는 것을 추천합니다.
• 황금률 4: 위험한 명령어는 사용 금지 목록을 만드세요.
  rm -rf (강제 삭제), sudo (관리자 권한 실행), chmod 777 (모두에게 모든 권한 부여) 같은 명령어는 시스템을 파괴할 수 있는 강력한 힘을 가졌습니다. 이런 명령어들은 아예 실행될 수 없도록 차단하는 Hook을 만들어 두면 안심할 수 있습니다.
• 황금률 5: 테스트, 테스트, 또 테스트!
  새로운 Hook은 반드시 실제 작업 환경이 아닌, Docker 같은 격리된 가상 환경에서 충분히 테스트하세요. 내 소중한 컴퓨터는 안전할 때 지키는 겁니다.

🚀 마치며: 여러분의 상상력을 코드로 만들어보세요!

오늘 우리는 Claude Code Hooks의 기본 개념부터 실제 활용법, 그리고 가장 중요한 보안 규칙까지 함께 알아봤습니다.

Hooks는 단순히 반복 작업을 줄여주는 것을 넘어, 여러분의 개발 환경과 워크플로우 자체를 여러분의 스타일에 맞게 재창조할 수 있는 무한한 가능성의 도구입니다.

• 빌드가 끝날 때마다 자동으로 슬랙에 메시지를 보내볼까요?
• 특정 파일을 수정하면, 관련된 다른 파일을 자동으로 업데이트하게 만들어 볼까요?
• 내가 자주하는 실수들을 미리 감지하고 경고해주는 Hook을 만들어보면 어떨까요?

이제 여러분의 차례입니다. 오늘 배운 내용을 바탕으로, 여러분의 개발 생활을 더욱 스마트하고 편리하게 만들어 줄 자신만의 Hook을 만들어 보세요. 클로드라는 강력한 비서를 여러분의 스타일에 맞게 길들이는 재미, 오늘부터 시작해 보세요!

Happy Hacking!

---

📚 더 깊이 알아보기

유용한 참고 자료

• Claude Code 공식 문서
• MCP 서버 목록

도움이 되는 도구들

• jq: JSON 데이터 처리의 스위스 아미 나이프
• prettier: JavaScript/TypeScript 코드 포맷터
• black: Python 코드 포맷터
• gofmt: Go 언어 코드 포맷터
• notify-send: Linux 데스크톱 알림 도구

---

🧚‍♀️ 용어 설명 (어린이도 이해할 수 있도록)

용어	쉬운 설명
Hook	특정 상황에서 자동으로 실행되는 명령어 (낚시 바늘처럼 특정 시점을 "낚아채는" 기능)
PreToolUse	도구를 사용하기 전에 실행되는 hook
PostToolUse	도구를 사용한 후에 실행되는 hook
Matcher	어떤 도구에 hook을 적용할지 정하는 패턴 (정규표현식 지원)
Shell Command	컴퓨터에게 직접 명령을 내리는 텍스트
JSON	컴퓨터들이 서로 정보를 주고받을 때 사용하는 형식 (정리정돈된 메모장 같은 것)
Exit Code	프로그램이 끝날 때 보내는 숫자 신호 (0=성공, 2=중단해주세요)
MCP	클로드가 외부 프로그램들과 대화할 수 있게 해주는 번역기
Computer Use	클로드가 마우스와 키보드를 직접 사용하는 기능
Tool Use	클로드가 다양한 도구들을 사용하는 방법
Regex	복잡한 글자 패턴을 찾을 때 사용하는 특별한 규칙
Transcript	클로드와의 대화 내용이 모두 기록되는 일기장

---

🙋‍♀️ 자주 묻는 질문 (FAQ)

Q: Hook이 실행 안 돼요!
A: /hooks 메뉴에서 설정을 확인하고, Ctrl-R로 transcript를 확인해보세요. 그리고 스크립트 파일의 실행 권한(chmod +x)도 확인해보세요.

Q: Hook이 너무 자주 실행돼서 annoying해요.
A: Matcher를 더 구체적으로 설정하거나, Hook 내부에 조건문을 추가해서 특정 상황에만 실행되도록 만들어보세요.

Q: Hook에서 에러가 나는데 어떻게 디버깅하죠?
A: Hook 스크립트 맨 위에 echo "Hook 시작: $(date)" >> /tmp/hook-debug.log 같은 로그를 추가해서 실행 여부를 확인하세요.

Q: 다른 사람이 만든 Hook을 쓰고 싶어요.
A: 절대 이해하지 못한 코드는 실행하지 마세요! 한 줄 한 줄 읽어보고, 무엇을 하는지 완전히 이해한 다음에 사용하세요.

Q: Hook이 내 컴퓨터를 망가뜨릴 수 있나요?
A: 네, 가능합니다. 그래서 보안 황금률을 꼭 지켜야 합니다. 특히 rm, sudo, chmod 같은 명령어는 조심하세요.

---

이 블로그 포스트가 도움이 되셨나요? 댓글로 여러분만의 창의적인 Hook 아이디어를 공유해주세요! 함께 더 스마트한 개발 환경을 만들어 나가요! 🚀