CLAUDE.md 완전 정복 - Hooks 완전 가이드

이벤트 구동으로 AI 코딩을 자동화·강제화하는 7가지 패턴

Hooks란 무엇인가

Claude Code Hooks는 특정 이벤트가 발생했을 때 셸 커맨드를 자동으로 강제 실행하는 기능입니다.

CLAUDE.md에 작성하는 규칙이 "이렇게 해줬으면 한다"는 부탁이라면, Hooks는 "반드시 이렇게 된다"는 강제입니다.

CLAUDE.md가 "규칙"이라면 Hooks는 "가드레일"입니다. 규칙은 AI가 컨텍스트 상황에 따라 놓칠 가능성이 있지만, Hooks는 이벤트가 발생하는 한 반드시 실행됩니다.

설정 파일 위치

Hooks는 .claude/settings.json에 설정합니다. CLAUDE.md에 작성하는 것이 아닙니다.

{
"hooks": {
"PreToolUse": [
{
"matcher": "Edit|Write",
"command": "echo '파일 변경을 체크 중...'"
}
]
}
}

팀 공유가 필요한 Hook은 .claude/settings.json(프로젝트 설정)에, 개인용 Hook은 ~/.claude/settings.json(사용자 설정)에 작성합니다. 두 설정이 모두 있으면 양쪽 모두 실행됩니다.

Hook 이벤트 4종류

PreToolUse

툴(Edit, Write, Bash 등)이 실행되기 전에 발화합니다.

주 용도: 사전 검증, 위험 조작 차단

{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"command": "/path/to/check-command.sh \"$TOOL_INPUT\""
}
]
}
}

PostToolUse

툴이 실행된 후에 발화합니다.

주 용도: 자동 포맷, 결과 검증, 로그 기록

{
"hooks": {
"PostToolUse": [
{
"matcher": "Write",
"command": "npx prettier --write \"$TOOL_INPUT_FILE_PATH\""
}
]
}
}

Notification

Claude Code가 사용자에게 알림을 보내는 타이밍에 발화합니다.

주 용도: Slack·카카오워크 알림, 사운드 재생

{
"hooks": {
"Notification": [
{
"matcher": "",
"command": "afplay /System/Library/Sounds/Glass.aiff"
}
]
}
}

Stop

Claude Code가 태스크를 완료하고 턴을 종료할 때 발화합니다.