본문 바로가기
클로드(Claude)

[클로드 시리즈_26] AI가 잊어버려도 괜찮다 — Claude Code Hooks(훅)로 규칙을 강제하는 법

by AI 길라잡이 강사 강호종 2026. 5. 28.

강호종 AI 길라잡이 강사 | 2026.05.28

핵심 결론 먼저

Hooks(훅)은 Claude Code가 작동하는 특정 시점(이벤트)에 물리적으로 강제 실행되는 자동화 명령어입니다. 프롬프트나 CLAUDE.md에 지시해 두어도 AI가 가끔 잊어버리는 것과 달리, 훅은 조건이 맞으면 무조건 실행됩니다.
포맷팅, 린트(Lint), 위험 명령어 차단, 작업 완료 알림까지 — 이 글 하나로 Hooks 개념부터 실전 세팅까지 단계별로 정리합니다.

1. Hook의 핵심 개념 — AI의 판단을 거치지 않는 자동화

Hook(훅)이란 무엇인가

Hook은 Claude Code의 라이프사이클 특정 지점에서 결정론적으로 실행되는 사용자 정의 셸 명령입니다.

스킬(Skills)·메모리·CLAUDE.md는 Claude의 판단을 거칩니다. "이 상황에 이 규칙을 써야 할까?"라고 추론한 끝에 실행되거나, 때로는 잊고 안 쓰기도 합니다. Hook은 다릅니다. 등록한 이벤트가 발화하고 매처(Matcher) 조건이 맞으면, AI의 판단과 무관하게 반드시 실행됩니다.

Hook의 작동 원리

이벤트 발생 (예: 파일 저장, 도구 실행)
    ↓
Matcher 검사 (조건 일치 여부 확인)
    ↓
지정된 액션(Hook) 자동 실행

린트(Lint)란?

린트(Lint)는 소스 코드를 실행하지 않고 분석해서 잠재적 오류·버그·스타일 문제·의심스러운 패턴을 찾아주는 정적 분석 도구입니다. 린터(Linter)가 잡아주는 것들은 아래와 같습니다.

  • 문법 오류 직전의 의심스러운 코드 — 사용하지 않는 변수, 도달 불가능한 코드, 잘못된 비교(== vs ===)
  • 잠재적 버그 — 초기화 안 된 변수, null 가능성, 타입 불일치
  • 스타일 위반 — 들여쓰기, 따옴표 종류, 네이밍 컨벤션
  • 안티패턴 — 비효율적이거나 위험한 코딩 관행

2. Hook의 4가지 실행 타입

타입 설명 활용 예시
command 터미널 셸 명령어를 실행 (가장 일반적) 알림 전송, 린트/테스트 스크립트 실행
prompt 내장 AI 모델(Haiku)에게 검증 요청 코드 수정 결과가 지침에 맞는지 AI 판단
agent 서브에이전트 호출 (도구 사용 가능) 다단계 복합 검증
http 특정 URL로 JSON 데이터를 POST 전송 외부 시스템(Slack, Jira 등) 로깅 연동

3. Hook의 JSON 구조

훅은 settings.json 파일에 저장됩니다.

  • 개인용 전역 설정: ~/.claude/settings.json
  • 프로젝트 설정: .claude/settings.json
 
json
{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"작업 완료!\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

💡 설정 즉시 적용: settings.json에 반영된 내용은 Claude Code 재시작 없이 즉시 활성화됩니다. 현재 적용된 목록은 /hooks 명령어로 확인할 수 있습니다.

⚠️ /hooks 메뉴는 읽기 전용입니다. 훅을 추가·수정·삭제하려면 settings.json을 직접 편집하거나 Claude에게 요청하세요.

4. 주요 이벤트(Event) 타이밍

Claude Code에는 라이프사이클 전반에 걸쳐 다양한 이벤트가 있습니다. 버전이 업데이트될수록 이벤트 종류가 늘어나며, 2026년 5월 기준 27종 이상이 공식 확인됩니다. 자주 쓰이는 핵심 이벤트는 아래와 같습니다.

이벤트 실행 시점 주요 용도
PreToolUse 도구 호출 직전 입력값 검증, 위험한 명령어 차단, 권한 제어
PostToolUse 도구 호출 직후 결과 검증, 후처리(린트, 포맷팅, 테스트)
Notification 사용자 응답 대기 시 작업 완료 알림 전송 (팝업, 사운드 등)
Stop 턴 종료 시 최종 정리, 보고서 생성, 상태 저장
StopFailure API 오류(인증, 속도 제한 등)로 종료 시 에러 로깅, 재시도 트리거

5. 실전 Hook 세팅 가이드 (복붙 가능)

모든 훅 설정은 Claude에게 자연어로 부탁하면 자동으로 settings.json을 수정해 줍니다.

⚠️ 사전 준비: 터미널에서 JSON을 다루기 위해 jq 패키지가 설치되어 있어야 합니다.

  • macOS: brew install jq
  • Ubuntu/Debian: apt-get install jq

실습 1. 작업 완료 시 데스크탑 알림 받기

AI에게 작업을 시켜두고 다른 일을 할 때 유용한 알림 설정입니다.

프롬프트:

"Claude가 작업을 마치고 내 입력을 기다릴 때(Notification 이벤트),
macOS 데스크탑 팝업 알림을 보내주는 Hook을 전역 설정으로 만들어 줘."

settings.json 직접 설정 (macOS)

 
json
{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code가 입력을 기다립니다\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

Windows (PowerShell):

 
json
{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "powershell.exe -Command \"[System.Reflection.Assembly]::LoadWithPartialName('System.Windows.Forms'); [System.Windows.Forms.MessageBox]::Show('Claude Code가 입력을 기다립니다', 'Claude Code')\""
          }
        ]
      }
    ]
  }
}

실습 2. 위험 명령어(DB 삭제, Git 강제 푸시) 사전 차단

PreToolUse 이벤트를 사용하여 AI가 치명적인 터미널 명령어를 실행하는 것을 원천 차단합니다.

프롬프트:

"Bash 도구 실행 전에 위험한 명령어를 차단하는 PreToolUse Hook을 만들어 줘.
rm -rf /, git push --force, DROP TABLE 같은 패턴을 막아야 해.
차단 로직은 .claude/hooks/block.sh 스크립트로 분리해 줘."

차단 원리: 분리된 스크립트에서 위험 패턴이 감지되면 표준 출력(stdout)으로 {"decision":"block"} JSON을 뱉거나, exit 2 상태 코드로 스크립트를 종료하여 도구 실행을 막습니다.

실습 3. 코드 수정 후 자동 Lint(문법 검사) 피드백 루프

파일이 수정된 직후(PostToolUse) 린터를 돌리고, 에러가 있으면 AI가 그 결과를 읽어 스스로 고치게 만듭니다.

프롬프트:

"파일을 수정할 때마다 ESLint를 돌려서 에러가 있으면 그 결과를
Claude에게 피드백하는 PostToolUse Hook을 프로젝트 설정에 추가해 줘.
JS/TS 파일에만 동작하게 해."

settings.json 직접 설정:

 
json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

피드백 원리: 훅에서 실행한 명령어의 표준 출력(stdout)은 모두 Claude에게 피드백으로 전달됩니다. 에러가 없으면 아무것도 출력하지 않게 설정하여 불필요한 개입을 막습니다.

실습 4. 절대 건드리면 안 되는 '보호 파일' 지정

환경 설정 파일이나 패키지 락 파일 등을 AI가 임의로 수정하지 못하게 막습니다.

프롬프트:

".env, package-lock.json, .git/ 폴더는 Claude가 절대 수정하지 못하도록 막아줘.
PreToolUse 이벤트로 설정하고 종료 코드 exit 2를 사용해서 도구 실행을 중단시켜 줘."

보호 스크립트 예시 (.claude/hooks/protect-files.sh):

 
bash
#!/bin/bash
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

PROTECTED_PATTERNS=(".env" "package-lock.json" ".git/")

for pattern in "${PROTECTED_PATTERNS[@]}"; do
  if [[ "$FILE_PATH" == *"$pattern"* ]]; then
    echo "Blocked: $FILE_PATH matches protected pattern '$pattern'" >&2
    exit 2
  fi
done

exit 0

스크립트 생성 후 실행 권한 부여(macOS/Linux):

bash
chmod +x .claude/hooks/protect-files.sh

6. Hook 설정 시 주의사항 3가지

  1. 차단은 오직 exit 2: 스크립트에서 도구 실행을 차단하려면 반드시 종료 코드를 exit 2로 반환해야 합니다. exit 0은 실행 허용, exit 1은 에러(하지만 실행 허용)입니다.
  2. 타임아웃(Timeout) 필수: 훅이 실행되는 동안 Claude는 멈춰서 기다립니다. 훅 설정 시 반드시 timeout 값(예: 5초)을 주입하고, 무거운 백그라운드 작업은 끝에 &를 붙여 비동기 처리하세요.
  3. 즉시 적용: settings.json에 반영된 내용은 Claude Code 재시작 없이 즉시 활성화됩니다. 현재 적용된 목록은 /hooks 명령어로 확인할 수 있습니다.

7. Q&A — 자주 묻는 질문 5가지

Q1. CLAUDE.md에 규칙을 써두면 되는데 왜 Hook을 써야 하나요?

CLAUDE.md는 Claude가 읽고 판단합니다. "이 규칙을 지금 적용해야 하나?" 추론하다 놓칠 수 있습니다. Hook은 다릅니다. 이벤트 조건이 맞으면 Claude의 판단을 거치지 않고 반드시 실행됩니다. 포맷팅, 위험 명령어 차단처럼 예외 없이 100% 적용해야 하는 규칙은 Hook으로 걸어두는 것이 맞습니다.

Q2. exit 2와 exit 1의 차이가 헷갈립니다.

exit 0은 정상 종료(실행 허용), exit 1은 에러 발생이지만 실행은 허용, exit 2만이 도구 실행을 차단합니다. 보호 파일 차단 스크립트를 만들 때 exit 1로 잘못 설정하면 차단이 되지 않으니 반드시 exit 2를 사용하세요.

Q3. 훅이 너무 느리면 어떻게 되나요?

훅이 실행되는 동안 Claude는 멈춰서 기다립니다. 무거운 작업을 PreToolUse에 걸면 매 도구 호출마다 지연이 발생합니다. 자주 발화되는 이벤트(PreToolUse)에는 가벼운 명령만 두고, 무거운 작업은 PostToolUse나 Stop 이벤트에 비동기(&) 처리로 연결하세요.

Q4. 여러 개의 훅이 같은 이벤트에 걸려 있으면 어떻게 동작하나요?

같은 이벤트에 훅이 여러 개 있으면 모두 병렬로 실행됩니다. PreToolUse에서 하나라도 exit 2를 반환하면 다른 훅이 allow를 반환해도 도구 실행이 차단됩니다. 가장 제한적인 결과가 우선 적용되는 구조입니다.

Q5. 훅 설정을 팀원과 공유하려면 어떻게 하나요?

~/.claude/settings.json은 개인 설정으로 팀원과 공유되지 않습니다. 팀 전체에 적용할 훅은 프로젝트 루트의 .claude/settings.json에 설정하고 Git으로 공유하면 됩니다. 단, API Key 같은 민감한 정보가 포함되지 않도록 주의하세요.

마무리 — 오늘 당장 해볼 수 있는 3가지 액션

  1. Notification 훅 설치 — 위 실습 1 코드를 ~/.claude/settings.json에 복붙하고 /hooks로 확인
  2. 보호 파일 지정 — .env와 .git/ 폴더 보호 훅 설정으로 실수 방지
  3. PostToolUse 포맷팅 훅 — Prettier 자동 실행 훅으로 코드 스타일 강제 유지

AI가 규칙을 잊어버릴까 봐 걱정하지 않아도 됩니다. Hook이 그 걱정을 대신해줍니다. 실제로 써보고 가장 유용했던 훅 조합을 댓글로 공유해 주시면, 다음 편에서 직접 다뤄보겠습니다!

다음 편 예고: [클로드 코드 시리즈] Claude Code 토큰 아끼는 법 — 리밋이 빨리 걸리는 진짜 이유와 7가지 최적화 전략

작성자 | 강호종 AI 길라잡이 강사

생성형 AI 활용 업무 효율화 전문강사 · 디지털융합교육원 지도강사, 젠스파크 AI 전문강사 · (사)한국AINFT협회 이사
저서: 『생성형 AI 활용 업무혁신』(2026) · 『이것이 GEO마케팅이다』(2026)
📞 010-9912-9934 · 📧 art386@naver.com · blog.naver.com/art386 · aiart386.tistory.com

#ClaudeCodeHooks #클로드코드훅 #ClaudeCode자동화 #Hooks #AI자동화 #클로드코드 #품질검사 #린트자동화 #강호종강사 #AI길라잡이 #생성형AI #PreToolUse #PostToolUse #코드품질 #바이브코딩 #Anthropic #CLAUDE.md #settings.json #자동화엔진 #2026AI트렌드

 

 

'클로드(Claude)' 카테고리의 다른 글

[클로드 시리즈_28] 🖥️ 클로드 코워크(Claude Cowork) 설치부터 첫 화면까지 — 5분이면 충분합니다  (0) 2026.05.28
[클로드 시리즈_27] 한도가 빨리 찬다고요? Claude Code 토큰이 진짜로 새는 이유와 7가지 절약법  (0) 2026.05.28
[클로드 시리즈_25] Claude Code에 날개 달기 — MCP 서버 연동으로 Notion·Slack까지 자동화하는 법  (0) 2026.05.28
[클로드 시리즈_24] AI 직원을 고용하는 방법 — Claude Code 서브에이전트 & 에이전트 팀 완전 정복  (0) 2026.05.28
[클로드 시리즈_23] 터미널이 뭔지도 몰랐던 내가 Claude Code로 코딩을 시작한 방법  (0) 2026.05.28

관련글

티스토리툴바