Claude Code Hooks는 Claude Code를 쓰면서 반복하는 작업을 자동화해주는 기능입니다. “파일 저장할 때마다 서버에 올려줘”, “작업 시작하면 특정 폴더부터 확인해줘” 같은 걸 매번 말하지 않아도 알아서 실행되게 만들 수 있어요. 결론부터 말하면, Hooks를 설정해두면 Claude Code가 훨씬 똑똑하게 움직입니다.
Claude Code Hooks가 뭔가요?
쉽게 비유하면, Hooks는 Claude Code에 걸어두는 “자동 알림 + 자동 실행” 장치입니다.
예를 들어볼게요. 매번 Claude Code로 HTML 파일을 만들 때마다 “이거 서버에 올려줘”라고 따로 말해야 한다면 번거롭겠죠. Hooks를 설정해두면, 파일이 저장되는 순간 자동으로 서버 업로드 스크립트가 실행됩니다. 사람이 개입할 필요가 없어요.
프로그래밍에서 Hook이란 “특정 이벤트가 일어날 때 끼어드는 코드”를 뜻합니다. Claude Code Hooks도 같은 원리예요. Claude가 어떤 동작을 하기 전이나 후에, 미리 정해둔 명령을 자동으로 실행하는 겁니다.
Hooks의 4가지 유형, 언제 실행되나요?
Claude Code Hooks는 실행 시점에 따라 크게 4가지로 나뉩니다. 각각이 어떤 타이밍에 작동하는지 알면, 어디에 써야 할지 감이 와요.
1. PreToolUse — 도구 실행 직전
Claude가 파일을 읽거나, 수정하거나, 명령어를 실행하려는 직전에 끼어드는 훅입니다.
실전 예시: “중요한 설정 파일은 절대 수정하지 마” 같은 안전장치를 걸 수 있습니다. Claude가 특정 파일을 건드리려 하면 훅이 먼저 확인하고, 조건에 안 맞으면 실행을 막아요.
2. PostToolUse — 도구 실행 직후
Claude가 어떤 작업을 완료한 직후에 실행되는 훅입니다. 가장 많이 쓰이는 유형이에요.
실전 예시: HTML 파일을 Write(작성)하거나 Edit(수정)한 직후, 자동으로 FTP 서버에 업로드하는 스크립트를 돌릴 수 있습니다. 블로그 운영할 때 특히 유용해요. 파일을 만들면 바로 웹에 반영되니까요.
3. Notification — 알림이 발생할 때
Claude가 사용자에게 알림을 보내는 시점에 실행됩니다. 작업이 오래 걸릴 때 “끝났어요”라는 알림 대신 슬랙 메시지를 보내거나, 소리를 재생하는 식으로 활용할 수 있어요.
4. Stop — 응답 완료 시
Claude가 하나의 응답을 완전히 마쳤을 때 실행됩니다. 작업 결과를 로그 파일에 기록하거나, 완료 보고를 자동으로 남기는 데 쓸 수 있습니다.
Hooks는 어디에 설정하나요?
Hooks는 Claude Code의 설정 파일인 settings.json에 작성합니다. 위치는 두 군데예요.
- 프로젝트 설정: 작업 폴더 안의
.claude/settings.json— 해당 프로젝트에서만 적용 - 사용자 설정: 홈 폴더의
~/.claude/settings.json— 모든 프로젝트에 공통 적용
설정 파일 안에 "hooks" 항목을 추가하고, 어떤 이벤트에 어떤 명령을 실행할지 적어주면 됩니다. 간단한 예시를 보여드릴게요.
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"command": "bash upload.sh \"$CLAUDE_FILE_PATH\""
}
]
}
}이 설정의 의미는 간단합니다. “Claude가 Write 또는 Edit 도구를 사용한 직후, upload.sh 스크립트를 자동 실행해라”라는 뜻이에요. matcher는 어떤 도구에 반응할지, command는 무엇을 실행할지를 정합니다.
비개발자가 Hooks를 쓸 만한 상황 3가지
코딩을 모르더라도 Hooks가 유용한 경우가 분명히 있습니다.
1. 파일 자동 업로드: Claude Code로 블로그 글이나 보고서 HTML을 만들 때, PostToolUse 훅으로 저장 즉시 웹 서버에 올릴 수 있습니다. 매번 “이거 업로드해줘”라고 말할 필요가 없어져요.
2. 위험한 작업 차단: PreToolUse 훅으로 특정 폴더나 파일의 수정을 막을 수 있습니다. 실수로 중요한 데이터를 덮어쓰는 사고를 예방하는 안전장치가 됩니다.
3. 작업 완료 알림: 긴 분석 작업을 시키고 다른 일을 하고 있을 때, Notification 훅으로 데스크톱 알림이나 메시지를 받을 수 있습니다.
설정할 때 주의할 점
Hooks는 강력한 기능인 만큼, 몇 가지 주의사항이 있습니다.
- command에 들어가는 스크립트가 정상 동작하는지 먼저 확인하세요. 훅이 실패하면 Claude Code 전체 동작에 영향을 줄 수 있습니다
- matcher 범위를 너무 넓게 잡지 마세요. 모든 도구에 반응하게 하면 예상치 못한 동작이 생길 수 있어요
- 훅 안에서 오래 걸리는 작업은 피하세요. 훅이 끝날 때까지 Claude가 기다리기 때문에 응답이 느려집니다
- 환경 변수를 활용하세요.
$CLAUDE_FILE_PATH처럼 Claude가 제공하는 변수를 쓰면 어떤 파일에 대해 작업했는지 자동으로 전달받을 수 있습니다
정리하면
Claude Code Hooks는 “매번 같은 말 반복하기”를 없애주는 자동화 장치입니다. PreToolUse로 사전 점검, PostToolUse로 후처리 자동화, Notification과 Stop으로 알림과 기록을 자동화할 수 있어요.
처음에는 PostToolUse 훅 하나만 설정해보는 것을 추천합니다. 파일 하나 만들 때마다 자동으로 뭔가가 실행되는 걸 보면, “이거 되는구나” 하는 감이 바로 옵니다. 거기서부터 하나씩 늘려가면 됩니다.
함께 읽으면 좋은 글