Hooks (이벤트 훅)
Claude가 뭔가 할 때마다 자동으로 추가 작업을 실행시킬 수 있어요.
Hooks란?
Hooks는 Claude가 뭔가를 할 때 자동으로 추가 작업을 실행시키는 기능이에요. 예를 들어 파일을 저장할 때마다 자동으로 코드 정리를 하거나, 저장 전에 검사를 하는 식으로 쓸 수 있어요.
자동 실행
따로 시키지 않아도 알아서 동작해요.
조건 지정
특정 동작(파일 저장, 명령어 실행 등)에만 적용할 수 있어요.
품질 보호
코드 검사, 보안 확인 등을 자동으로 해줘요.
간단한 설정
설정 파일 하나만 수정하면 돼요.
이벤트 종류
Hooks는 아래와 같은 상황에서 동작해요. 상황마다 실행되는 타이밍이 달라요.
| 이벤트 | 실행 시점 | 주요 용도 |
|---|---|---|
PreToolUse | 어떤 작업 직전 | 코드 검사, 확인 작업 |
PostToolUse | 어떤 작업 직후 | 코드 정리, 기록 남기기 |
Notification | 알림 발생 시 | 커스텀 알림 (소리, 팝업) |
Stop | Claude 답변 완료 시 | 결과 정리, 마무리 작업 |
SubagentStop | 하위 작업 끝날 때 | 하위 작업 정리 |
PreToolUse(작업 전)와 PostToolUse(작업 후)예요. 파일 저장 전에 검사하고, 저장 후에 정리하는 식으로 많이 써요.설정 위치
Hooks는 settings.json 파일에 적어요. 내 컴퓨터 전체용과 프로젝트용 두 곳이 있어요.
| 구분 | 경로 | 범위 |
|---|---|---|
| 개인 설정 | ~/.claude/settings.json | 내 컴퓨터 전체 |
| 프로젝트 설정 | .claude/settings.json | 해당 프로젝트만 |
Hook 구조
settings.json 파일 안에 아래처럼 적어요.matcher는 "어떤 동작일 때", command는 "뭘 실행할지"를 뜻해요.
{
"hooks": {
"PreToolUse": [
{
"matcher": "Write",
"hooks": [
{
"type": "command",
"command": "echo '파일 저장 전 실행됩니다'"
}
]
}
],
"PostToolUse": [
{
"matcher": "Write",
"hooks": [
{
"type": "command",
"command": "echo '파일 저장 후 실행됩니다'"
}
]
}
]
}
}| 필드 | 설명 |
|---|---|
matcher | 어떤 동작에 반응할지 (예: Write=파일 저장, Bash=명령어 실행) |
hooks | 실행할 명령 배열 |
type | 항상 "command" |
command | 실행할 명령어 (터미널에서 실행되는 명령) |
실전 예시
예시 1: 커밋 전 린트 검사
Bash에서 git commit 명령이 실행되기 전에 ESLint로 코드를 검사합니다.
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "if echo '$TOOL_INPUT' | grep -q 'git commit'; then npx eslint . --max-warnings 0; fi"
}
]
}
]
}
}검사에 실패하면 작업이 자동으로 중단돼요. 실수를 미리 막아주는 거예요.
예시 2: 파일 저장 후 자동 포맷팅
Claude가 파일을 작성한 후 Prettier로 자동 포맷팅합니다.
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write",
"hooks": [
{
"type": "command",
"command": "npx prettier --write '$TOOL_INPUT_FILE_PATH'"
}
]
}
]
}
}$TOOL_INPUT_FILE_PATH는 저장된 파일 경로로 자동 치환됩니다.
예시 3: 커스텀 알림 소리
Claude의 응답이 완료되면 알림 소리를 재생합니다.
{
"hooks": {
"Notification": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "afplay /System/Library/Sounds/Glass.aiff"
}
]
}
]
}
}macOS 기본 사운드를 사용합니다. matcher를 비워두면 모든 알림에 반응합니다.
주의사항
훅 명령은 60초 안에 끝나야 해요. 너무 오래 걸리는 작업은 피하세요.
프로젝트 폴더의 설정은 팀원도 볼 수 있어요. 비밀 정보가 포함된 명령은 개인 설정에 넣으세요.
훅이 안 되면 claude --debug로 실행해서 어디서 문제가 생기는지 확인해보세요.