Claude Code Hooks 완전정리, PreToolUse·PostToolUse로 자동화하는 법

Claude Code Hooks 완전정리, PreToolUse·PostToolUse로 자동화하는 법

이 글에서 사용하는 주요 용어 정의

용어	정의
Hook	특정 이벤트(도구 호출 전후 등) 시점에 자동으로 실행되는 셸 명령/스크립트
PreToolUse	에이전트가 도구를 실행하기 직전에 발동하는 훅
PostToolUse	에이전트가 도구 실행을 완료한 직후에 발동하는 훅
matcher	훅이 어떤 도구(Bash, Write, Edit 등)에 반응할지 지정하는 패턴

---

도입

Claude Code로 작업하다 보면 "파일 저장할 때마다 자동으로 포맷팅해줬으면", "특정 명령어는 아예 실행 자체를 막고 싶다" 같은 니즈가 생깁니다. 이런 요구를 프롬프트로 매번 반복하는 대신, 규칙을 코드로 강제할 수 있게 해주는 기능이 바로 Hooks입니다. 오늘은 Claude Code Hooks의 개념과 실제 설정 방법을 정리해보겠습니다.

---

Hooks란?

Hooks는 Claude Code가 세션 시작, 도구 호출 전후, 작업 종료 같은 특정 이벤트가 발생할 때 자동으로 실행되는 셸 명령입니다. ~/.claude/settings.json(전역) 또는 프로젝트의 .claude/settings.json(프로젝트 전용)에 등록하며, 프롬프트로 "이렇게 해줘"라고 부탁하는 것과 달리 조건을 만족하면 반드시 실행되는 규칙이라는 점이 다릅니다.

[에이전트가 도구 호출 시도]
        │
        ▼
  PreToolUse 훅 실행 ──── 종료코드 2 반환 시 → 도구 실행 차단
        │ (통과)
        ▼
   실제 도구 실행 (Bash, Write, Edit 등)
        │
        ▼
  PostToolUse 훅 실행 (포맷팅, 테스트 등 후처리)

---

핵심 내용

설정 방법

PreToolUse 훅은 도구 실행을 검사하거나 막을 때, PostToolUse 훅은 실행 후 후처리를 자동화할 때 사용합니다. matcher로 어떤 도구에 반응할지 지정합니다.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": ".claude/hooks/check-command.sh" }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          { "type": "command", "command": "npx prettier --write" }
        ]
      }
    ]
  }
}

훅 스크립트는 session_id, tool_name, tool_input 등이 담긴 JSON을 표준입력(stdin)으로 전달받아, 이를 기반으로 허용/차단 여부를 판단할 수 있습니다.

실무에서 자주 쓰는 조합

훅 종류	활용 예시
PreToolUse + Bash	저장소 바깥 파일 쓰기, 위험한 명령어(rm -rf 등) 사전 차단
PostToolUse + Write/Edit	파일 저장 직후 prettier, eslint --fix 자동 실행
Stop	세션 종료 시 테스트 스위트 자동 실행
PreToolUse + Bash	셸 명령에 포함된 API 키·비밀번호 등 시크릿 자동 마스킹(redact)

차단(거부) 처리 방식

PreToolUse 훅이 종료 코드 2를 반환하면 해당 도구 실행 자체가 취소됩니다. 이 방식으로 "이 폴더 바깥으로는 파일을 쓸 수 없다" 같은 규칙을 프롬프트가 아닌 코드 레벨에서 강제할 수 있습니다.

---

마무리

Hooks는 "매번 부탁해야 지켜지는 규칙"을 "반드시 지켜지는 규칙"으로 바꿔주는 장치입니다. 자동 포맷팅처럼 간단한 것부터 시작해서, 위험한 명령어 차단이나 시크릿 마스킹처럼 보안에 직결되는 규칙까지 단계적으로 확장해보시는 걸 추천드립니다.

---

참고 자료

• Vincent's Blog - Claude Code settings.json Hooks
• morphllm.com - Claude Code Hooks (2026)