훅(Hooks) 설정

훅(Hooks)이란?

훅은 Claude Code의 특정 이벤트 발생 시 자동으로 실행되는 셸 스크립트입니다. 로깅, 검증, 알림, 보안 정책 적용 등 다양한 자동화에 활용합니다.

---

훅 이벤트 유형

이벤트	실행 시점
PreToolUse	도구 실행 직전
PostToolUse	도구 실행 직후
Notification	Claude가 알림을 보낼 때
Stop	Claude가 작업을 완료했을 때
SubagentStop	서브에이전트가 완료됐을 때

---

훅 설정 방법

~/.claude/settings.json 또는 프로젝트 .claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/pre-bash.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npm run lint --silent"
          }
        ]
      }
    ]
  }
}

---

실용 훅 예시

파일 편집 후 자동 린트

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [{
          "type": "command",
          "command": "cd $PROJECT_ROOT && npx eslint --fix ${TOOL_INPUT_FILE_PATH} 2>/dev/null || true"
        }]
      }
    ]
  }
}

위험한 명령 실행 전 경고

#!/bin/bash
# ~/.claude/hooks/pre-bash.sh

COMMAND=$(echo "$TOOL_INPUT" | jq -r '.command // ""')

# rm -rf 감지
if echo "$COMMAND" | grep -qE 'rm\s+-rf'; then
  echo "경고: 위험한 삭제 명령이 감지되었습니다." >&2
  echo "명령: $COMMAND" >&2
  exit 2  # 0=허용, 1=비허용+경고, 2=차단
fi

exit 0

작업 완료 시 Slack 알림

#!/bin/bash
# ~/.claude/hooks/on-stop.sh

curl -s -X POST "$SLACK_WEBHOOK_URL" \
  -H "Content-Type: application/json" \
  -d "{\"text\": \"✅ Claude Code 작업 완료: $CLAUDE_SESSION_ID\"}"

{
  "hooks": {
    "Stop": [
      {
        "hooks": [{
          "type": "command",
          "command": "~/.claude/hooks/on-stop.sh"
        }]
      }
    ]
  }
}

---

훅 환경 변수

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

변수	설명
TOOL_NAME	실행된 도구 이름 (예: Bash, Edit)
TOOL_INPUT	도구 입력값 (JSON 문자열)
TOOL_OUTPUT	도구 출력값 (PostToolUse)
PROJECT_ROOT	프로젝트 루트 디렉토리
CLAUDE_SESSION_ID	현재 세션 ID

---

훅 종료 코드

종료 코드	의미
0	성공, 계속 진행
1	오류, 경고 메시지를 Claude에게 전달
2	해당 도구 실행 차단

훅의 표준 출력(stdout)은 Claude에게 추가 컨텍스트로 전달됩니다. 표준 오류(stderr)는 사용자에게 표시됩니다.