훅 시스템

훅이란?

훅(Hook)은 Claude Code의 이벤트 기반 자동화 메커니즘입니다. 특정 이벤트가 발생했을 때 셸 명령어, HTTP 요청, LLM 프롬프트, 또는 에이전트를 자동으로 실행할 수 있습니다. 이를 통해 코드 포맷팅, 보안 검사, 알림 전송 등 반복적인 작업을 자동화할 수 있습니다.

Exit 코드 의미

훅 명령어의 종료 코드에 따라 Claude Code의 동작이 달라집니다.

Exit 코드	의미	동작
`0`	성공	정상 진행, stdout이 있으면 Claude에게 주입
`2`	차단/주입	도구 실행 차단 또는 응답에 텍스트 주입
기타 (`1` 등)	오류	stderr 내용만 표시, 실행은 계속

# exit 2로 도구 실행 차단 예시
#!/bin/bash
if echo "$CLAUDE_TOOL_INPUT" | grep -q "rm -rf"; then
  echo "위험한 명령어가 감지되었습니다" >&2
  exit 2
fi
exit 0

훅 이벤트 유형

Claude Code는 20가지 이상의 이벤트를 제공합니다.

도구 이벤트

이벤트	시점	차단 가능
`PreToolUse`	도구 실행 직전	예 (exit 2)
`PostToolUse`	도구 실행 성공 후	아니오
`PostToolUseFailure`	도구 실행 실패 후	아니오

세션 이벤트

이벤트	시점
`SessionStart`	세션 시작 시
`Stop`	응답 생성 완료 시
`UserPromptSubmit`	사용자 메시지 전송 시
`SessionEnd`	세션 종료 시

대화 관리

이벤트	시점
`PreCompact`	컨텍스트 압축 직전
`PostCompact`	컨텍스트 압축 완료 후

설정 및 파일

이벤트	시점
`Setup`	초기 환경 구성 시
`ConfigChange`	설정 파일 변경 시
`CwdChanged`	작업 디렉토리 변경 시
`FileChanged`	파일 변경 감지 시
`InstructionsLoaded`	CLAUDE.md 로드 시 (차단 불가)

멀티에이전트

이벤트	시점
`SubagentStart`	서브에이전트 시작 시
`SubagentStop`	서브에이전트 종료 시
`TeammateIdle`	팀메이트 에이전트 유휴 상태 시

권한 및 태스크

이벤트	시점
`PermissionRequest`	권한 요청 시
`PermissionDenied`	권한 거부 시
`Notification`	알림 발생 시
`TaskCreated`	태스크 생성 시
`TaskCompleted`	태스크 완료 시

워크트리

이벤트	시점
`WorktreeCreate`	Git 워크트리 생성 시
`WorktreeRemove`	Git 워크트리 제거 시

훅 명령어 유형

유형	설명	사용 사례
`command`	셸 명령어 실행	코드 포맷팅, 린트, 파일 검사
`http`	HTTP POST 요청 전송	외부 서비스 알림, 웹훅
`prompt`	LLM 프롬프트 실행	AI 기반 코드 리뷰, 자동 설명 생성
`agent`	도구 접근 가능한 에이전트	복잡한 자동화, 멀티스텝 작업

// settings.json 훅 설정 예시
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "/usr/local/bin/check-dangerous-cmd.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "prettier --write $CLAUDE_FILE_PATH"
          }
        ]
      }
    ]
  }
}

훅 변수

훅 실행 시 다음 환경 변수가 자동으로 주입됩니다.

변수	설명
`$CLAUDE_FILE_PATH`	현재 작업 중인 파일 경로
`$CLAUDE_TOOL_NAME`	실행된 도구 이름
`$CLAUDE_TOOL_INPUT`	도구에 전달된 입력 (JSON)
`$ARGUMENTS`	훅에 전달된 추가 인수

훅 시스템을 통해 Claude Code를 팀의 개발 워크플로우에 긴밀하게 통합할 수 있습니다.