Claude Code Hook 기능 완전정리 — 모든 단계에 내 스크립트 끼우기

 

Claude Code가 알아서 코드를 짜는 건 좋은데, "위험한 명령은 막고 싶고", "수정 후엔 자동으로 포맷하고 싶다"면? 그게 바로 Hook(훅)입니다. 세션·턴·도구 호출 같은 특정 시점에 내 스크립트를 자동 실행해주죠. 이 글에서 hook이 뭐고, 언제 실행되며, 어떻게 설정하는지 정리합니다.

📌 이 글에서 얻어갈 것

✓ hook이 무엇이고 언제 실행되나
✓ PreToolUse(차단) vs PostToolUse(후처리)
✓ settings.json 설정법 (실제 예시)
✓ 실전 활용 패턴

Hook이란?

Hook은 Claude Code의 라이프사이클 특정 시점에 자동으로 끼어드는 스크립트입니다. "Claude가 파일을 쓰기 직전", "도구 실행 직후", "세션 시작 시" 같은 순간에 내가 정한 명령을 실행하죠. AI의 행동을 통제하고 자동화하는 강력한 장치입니다.

언제 실행되나 — 3가지 시점

🟢 세션 단위 — SessionStart · SessionEnd

🔵 턴 단위 — UserPromptSubmit · Stop · StopFailure

🟡 도구 호출마다 — PreToolUse · PostToolUse (가장 많이 씀)

핵심 — PreToolUse vs PostToolUse

PreToolUse (도구 실행 전) 작업을 막거나 입력을 바꿀 수 있음. exit 2로 차단(이유는 Claude에 전달). 위험 명령·민감 파일 차단에.

PostToolUse (도구 실행 후) 성공 후 포맷·린트·테스트 실행(되돌리진 못함). 예: 편집 후 prettier 자동 실행.

※ PreToolUse는 tool_name·tool_input을 받아 입력 자체를 교체(updatedInput)할 수도 있습니다.

설정법 (settings.json)

.claude/settings.json(프로젝트, 팀 공유) 또는 ~/.claude/settings.json(내 전역)에 적습니다. 예시 — 편집 후 prettier 자동 실행:

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit|Write|MultiEdit",
      "hooks": [{ "type": "command",
        "command": "npx prettier --write \"$CLAUDE_FILE_PATHS\"" }]
    }],
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{ "type": "command",
        "command": "./scripts/block-dangerous.sh" }]
    }]
  }
}

※ matcher는 "Edit|Write|MultiEdit"(파일쓰기 도구), "Bash"(배시)처럼 도구를 지정. 핸들러는 shell 명령 또는 HTTP(엔드포인트로 POST)를 지원하고, async: true로 백그라운드 실행도 됩니다.

실전 활용 패턴

🛑 민감 파일 보호 — PreToolUse로 .env 읽기 차단

⚠️ 위험 명령 차단 — rm -rf 같은 명령 거부

✨ 자동 포맷·린트 — PostToolUse로 prettier·eslint 실행

🔔 완료 알림 — Stop 훅으로 작업 끝나면 소리·푸시

"AI를 신뢰하되, hook으로 통제·자동화"
권한 모드가 '문지기'라면, hook은 '맞춤 규칙'

자주 묻는 질문 (FAQ)

Q. 권한 모드랑 뭐가 다른가요?

권한 모드는 Claude가 제공하는 기본 승인 체계, hook은 내가 직접 코드로 정의하는 맞춤 규칙입니다. 둘을 함께 쓰면 통제가 촘촘해져요.

Q. exit 2가 뭔가요?

PreToolUse 훅이 종료 코드 2로 끝나면 그 도구 호출이 차단되고, stderr에 적은 이유가 Claude에게 전달됩니다. 0이면 통과예요.

Q. 팀과 공유할 수 있나요?

네. .claude/settings.json을 저장소에 커밋하면 팀 전체가 같은 hook을 씁니다. 프로젝트 설정이 전역 설정보다 우선해요.

마치며

Hook은 Claude Code를 "내 규칙대로 움직이는 도구"로 바꿔줍니다. 위험한 작업은 PreToolUse로 막고, 반복 후처리는 PostToolUse로 자동화하면, AI와 더 안전하고 깔끔하게 협업할 수 있어요. 자주 하는 수작업이 있다면 hook으로 옮겨보세요.

어떤 hook을 만들어 쓰고 싶으신가요? 아이디어를 댓글로 공유해주세요 🙌

---

※ 본 글은 2026년 7월 기준 Claude Code 공식 문서(code.claude.com/docs/en/hooks)를 확인해 작성했습니다. 이벤트·옵션은 버전에 따라 바뀔 수 있으니 공식 문서에서 현행 사양을 확인하세요.