훅(Hooks) 설정

훅(Hooks)이란?

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

훅 이벤트 유형

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

훅 설정 방법

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

1{2  "hooks": {3    "PreToolUse": [4      {5        "matcher": "Bash",6        "hooks": [7          {8            "type": "command",9            "command": "~/.claude/hooks/pre-bash.sh"10          }11        ]12      }13    ],14    "PostToolUse": [15      {16        "matcher": "Edit",17        "hooks": [18          {19            "type": "command",20            "command": "npm run lint --silent"21          }22        ]23      }24    ]25  }26}

실용 훅 예시

파일 편집 후 자동 린트

1{2  "hooks": {3    "PostToolUse": [4      {5        "matcher": "Edit",6        "hooks": [{7          "type": "command",8          "command": "cd $PROJECT_ROOT && npx eslint --fix ${TOOL_INPUT_FILE_PATH} 2>/dev/null || true"9        }]10      }11    ]12  }13}

위험한 명령 실행 전 경고

1#!/bin/bash2# ~/.claude/hooks/pre-bash.sh3 4COMMAND=$(echo "$TOOL_INPUT" | jq -r '.command // ""')5 6# rm -rf 감지7if echo "$COMMAND" | grep -qE 'rm\s+-rf'; then8  echo "경고: 위험한 삭제 명령이 감지되었습니다." >&29  echo "명령: $COMMAND" >&210  exit 2  # 0=허용, 1=비허용+경고, 2=차단11fi12 13exit 0

작업 완료 시 Slack 알림

1#!/bin/bash2# ~/.claude/hooks/on-stop.sh3 4curl -s -X POST "$SLACK_WEBHOOK_URL" \5  -H "Content-Type: application/json" \6  -d "{\"text\": \"✅ Claude Code 작업 완료: $CLAUDE_SESSION_ID\"}"

1{2  "hooks": {3    "Stop": [4      {5        "hooks": [{6          "type": "command",7          "command": "~/.claude/hooks/on-stop.sh"8        }]9      }10    ]11  }12}

훅 환경 변수

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

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

훅 종료 코드

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

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