Claude Code 훅을 사용하면 명령 실행 전후에 특정 작업을 자동으로 실행할 수 있어요. 구체적으로 말하면, Claude Code가 자동으로 테스트를 실행하거나 코드를 포맷팅하거나 파일의 보안을 확인하도록 설정할 수 있다는 뜻이에요. 이 기능은 반복적인 작업을 백그라운드에서 자동으로 실행되는 프로세스로 바꿔줍니다. 이 튜토리얼에서는 훅이 뭔지, 프로그래밍 경험이 없어도 어떻게 설정하는지, 그리고 오늘 바로 복사해서 쓸 수 있는 5가지 실용적인 예제를 배워볼 거예요.
Claude Code 훅이 뭐고 왜 유용한가요
훅은 워크플로우의 특정 시점에 자동으로 어떤 작업을 실행하는 지점이에요. 예를 들어 코드를 저장하기 전에 항상 잘 포맷팅되길 원한다고 생각해봐요. 매번 수동으로 포맷팅 명령을 실행하는 대신, 저장 전에 자동으로 포맷팅하는 훅을 설정하면 돼요.
Claude Code 훅은 트리거-액션 원칙으로 작동합니다. 트리거 이벤트(예: "코드 생성 전", "파일 수정 후", "프로젝트 종료 전")를 정의하고, 그 순간에 자동으로 실행할 액션을 설정하는 거죠.
Anthropic 공식 문서에 따르면, 훅을 사용하면 반복적인 개발 작업에 소요되는 시간을 최대 40%까지 줄일 수 있어요. 코딩을 배우는 초보자에게는 방해 요소가 줄어들고 학습에 더 집중할 수 있다는 뜻이에요.
가장 흔한 사용 사례들:
- 코드를 자동으로 포맷팅해서 읽기 쉽게 유지하기
- 테스트를 실행해서 뭔가 깨진 게 없는지 확인하기
- 중요한 수정 전에 작업 복사본 자동 저장하기
- 코드를 공유하기 전에 보안 확인하기
- 프로젝트 종료 시 임시 파일 자동 정리하기
Claude Code에서 사용 가능한 훅의 종류
Claude Code는 세 가지 훅 카테고리를 제공해요: pre-hooks(액션 전), post-hooks(액션 후), event-hooks(특정 이벤트 발생 시). 각 타입은 개발 워크플로우의 다른 필요를 충족시켜요.
Pre-hooks: 실행 전에 작업하기
Pre-hooks는 Claude Code가 어떤 작업을 수행하기 직전에 실행돼요. 예를 들어 pre-generate는 Claude가 코드를 생성하기 전에 실행되고, pre-modify는 기존 파일을 수정하기 전에 실행돼요.
주요 용도: 계속 진행하기 전에 조건이 좋은지 확인하기. 새로운 기능을 추가하기 전에 현재 코드가 작동하는지 확인하거나, 파일을 수정하기 전에 버전을 저장할 수 있어요.
Post-hooks: 실행 후에 작업하기
Post-hooks는 Claude Code가 작업을 완료한 후에 실행돼요. post-generate는 코드 생성 후에 실행되고, post-modify는 수정 후에 실행돼요.
주요 용도: 결과를 정리하고, 포맷팅하고, 검증하기. 생성된 코드를 자동으로 포맷팅하거나, 모든 게 잘 작동하는지 확인하는 테스트를 실행하거나, 문서를 업데이트하기에 딱 좋은 시점이에요.
Event-hooks: 이벤트에 반응하기
Event-hooks는 프로젝트 열기(on-open), 종료(on-close), 에러 감지(on-error) 같은 특정 이벤트에 실행돼요.
주요 용도: 프로젝트의 생명주기 관리하기. 프로젝트를 열 때 선호하는 설정을 자동으로 로드하거나, 종료할 때 모든 작업을 저장하거나, 에러 발생 시 알림을 받을 수 있어요.
첫 번째 훅 설정하기 (단계별)
훅을 설정하려면 프로젝트 루트에 .claude-hooks.json 파일을 만들고 JSON 형식으로 자동화 규칙을 정의하면 돼요. 프로그래밍 경험이 없어도 5분 안에 할 수 있어요.
1단계: 설정 파일 만들기
Claude Code를 열고 통합 터미널에서 다음 명령을 입력하세요:
touch .claude-hooks.json
Windows에서는 이 명령을 사용하세요:
type nul > .claude-hooks.json
이 파일에 모든 자동화 규칙이 들어갈 거예요. 파일명 앞의 점은 파일을 숨겨주는 거라 파일 탐색기에서 기본적으로 안 보이는 게 정상이에요.
2단계: 첫 번째 규칙 정의하기
.claude-hooks.json 파일을 열고 이 기본 설정을 붙여넣으세요:
{
"hooks": [
{
"name": "format-on-generate",
"type": "post-generate",
"command": "prettier --write .",
"enabled": true
}
]
}
이 훅은 코드 생성 후 자동으로 포맷팅해줘요. 각 줄을 살펴봅시다:
name: 훅에 붙이는 이름 (설명적인 이름을 선택하세요)type: 훅이 실행될 시점command: 실행할 명령 (여기서는 Prettier가 코드를 포맷팅해요)enabled: 훅을 활성화하거나 비활성화하기 (삭제하지 않고)
3단계: 훅 테스트하기
Claude Code에 간단한 파일을 생성하도록 요청하세요:
두 개의 숫자를 더하는 함수가 있는 test.js 파일을 만들어줘
훅이 작동하면 Prettier가 파일을 포맷팅했다는 메시지가 터미널에 나타날 거예요. 생성된 코드가 품질 표준에 따라 자동으로 포맷팅될 거고요.
4단계: 필요에 맞게 조정하기
"enabled": true를 "enabled": false로 바꾸면 훅을 임시로 비활성화할 수 있어요. 자동화 없이 뭔가 빠르게 테스트하고 싶을 때 유용해요.
여러 훅을 추가하려면 hooks 배열에서 쉼표로 구분하면 돼요:
{
"hooks": [
{
"name": "hook1",
...
},
{
"name": "hook2",
...
}
]
}
초보자를 위한 5가지 바로 쓸 수 있는 훅 예제
여기 .claude-hooks.json 파일에 바로 복사해서 붙여넣을 수 있는 5가지 훅 설정이 있어요. 각 예제는 주석이 달려 있어서 뭘 하는지 이해하기 쉬워요.
1. 수정 전에 자동으로 백업하기
{
"name": "backup-before-modify",
"type": "pre-modify",
"command": "cp -r . ../backup-$(date +%Y%m%d-%H%M%S)",
"enabled": true
}
이 훅은 모든 수정 전에 프로젝트 전체를 날짜가 붙은 폴더에 복사해줘요. Claude Code가 실수를 하면 쉽게 되돌릴 수 있어요. Windows에서는 명령을 xcopy . ..\backup-%date:~-4,4%%date:~-7,2%%date:~-10,2%-%time:~0,2%%time:~3,2%%time:~6,2% /E /I로 바꾸세요.
2. 코드 생성 후 문법 확인하기
{
"name": "check-syntax",
"type": "post-generate",
"command": "node --check **/*.js",
"enabled": true
}
이 훅은 생성된 JavaScript 코드에 문법 오류가 없는지 확인해요. 오류가 감지되면 계속 진행하기 전에 경고 메시지를 받아요. 언어에 따라 확장자를 조정하세요 (Python은 .py, Ruby는 .rb 등).
3. 프로젝트 종료 시 임시 파일 정리하기
{
"name": "cleanup-on-close",
"type": "on-close",
"command": "find . -name '*.tmp' -delete && find . -name '.DS_Store' -delete",
"enabled": true
}
이 훅은 프로젝트를 종료할 때 임시 파일과 숨겨진 시스템 파일을 자동으로 삭제해줘요. 노력 없이 폴더가 깔끔하게 유지돼요. Windows에서는 del /s /q *.tmp를 사용하세요.
4. 모든 수정 후 테스트 실행하기
{
"name": "run-tests",
"type": "post-modify",
"command": "npm test",
"enabled": true
}
이 훅은 코드 수정 후 자동으로 테스트를 실행해줘요. 뭔가 깨뜨렸는지 즉시 알 수 있어요. npm test를 프로젝트의 테스트 명령으로 바꾸세요 (Python은 pytest, Ruby는 ruby test.rb 등).
5. 프로젝트 열 때 설정 자동 로드하기
{
"name": "load-preferences",
"type": "on-open",
"command": "source ./.env && echo 'Environnement chargé'",
"enabled": true
}
이 훅은 프로젝트를 열 때 환경 변수와 개인 설정을 자동으로 로드해줘요. 매번 수동으로 설정할 필요가 없어요.
훅 에러 관리 및 디버깅하기
훅이 작동하지 않으면 Claude Code가 터미널에 에러 메시지를 표시해서 해결책을 안내해줘요. 가장 흔한 문제들은 어디를 봐야 하는지 알면 쉽게 해결할 수 있어요.
에러: "Command not found"
이 메시지는 실행하려는 명령이 컴퓨터에 설치되지 않았다는 뜻이에요. 예를 들어 훅이 prettier를 사용하는데 설치하지 않았으면 이 에러가 나타나요.
해결책: 없는 도구를 설치하세요. Prettier의 경우 터미널에 npm install -g prettier를 입력하면 돼요. 다른 도구는 공식 설치 문서를 참고하세요.
에러: "Permission denied"
운영체제가 보안상의 이유로 명령 실행을 차단했어요.
해결책: 스크립트에 실행 권한을 추가하세요. macOS와 Linux에서는 chmod +x 스크립트이름을 사용하면 돼요. Windows에서는 Claude Code를 관리자로 실행하세요 (우클릭 > "관리자로 실행").
에러: "Hook timeout"
훅이 너무 오래 걸려서 Claude Code가 자동으로 중단했어요. 기본 제한은 30초예요.
해결책: 명령을 더 빠르게 최적화하거나, 훅 설정에 "timeout": 60 (초 단위)을 추가해서 대기 시간을 늘리세요.
로그로 디버깅하기
상세 모드를 활성화해서 각 훅이 정확히 뭘 하는지 보세요:
{
"hooks": [...],
"verbose": true
}
Claude Code가 터미널에 각 단계를 표시해줄 거라서 어디서 문제가 생기는지 찾을 수 있어요.
훅 개별 테스트하기
실제 상황에서 테스트하는 대신 터미널에서 수동으로 실행해보세요:
훅-명령어
명령이 혼자서는 작동하는데 훅에서는 안 되면, 문제는 아마 경로나 권한 때문일 거예요.
효율적인 훅을 위한 좋은 습관들
기본을 익힌 후 점진적으로 훅을 추가하면서 한두 개로 시작하세요. 처음부터 너무 복잡한 자동화 시스템은 유지하고 디버깅하기 어려워져요.
훅을 빠르게 유지하세요: 5초 이상 걸리는 명령은 워크플로우를 빠르게 하는 대신 느리게 만들어요. 오래 걸리는 작업이 필요하면 자주 발생하지 않는 이벤트(매번 수정할 때보다는 on-close)에 사용하세요.
설정 파일에 명확한 주석으로 훅을 문서화하세요. JSON은 기본적으로 주석을 지원하지 않지만, 각 훅에 "description" 필드를 추가할 수 있어요:
{
"name": "format-code",
"description": "코드 생성 후 Prettier로 자동 포맷팅",
"type": "post-generate",
...
}
.claude-hooks.json 파일을 Git으로 버전 관리하세요. 팀과 자동화를 공유하거나 다른 프로젝트에서 다시 찾을 수 있어요. 다른 설정 파일처럼 Git 저장소에 추가하면 돼요.
전역 훅보다는 프로젝트별 훅을 만드세요. 웹 프로젝트와 데이터 분석 스크립트는 다른 자동화가 필요해요. 전역 훅을 원하면 사용자 폴더에 ~/.claude-hooks.json 파일을 만들 수 있어요.
메인 프로젝트에 적용하기 전에 테스트 프로젝트에서 훅을 테스트하세요. 임시 폴더를 만들고, 설정 파일을 복사하고, 모든 게 예상대로 작동하는지 확인하세요.
Claude Code를 더 깊이 알고 싶으면 필수 20가지 명령 가이드를 참고해서 훅을 고급 명령과 조합하세요. 또는 모든 도구 측면을 다루는 초보자 완전 튜토리얼을 살펴볼 수도 있어요.
훅은 Claude Code의 다른 기능과 조합할 때 정말 강력해져요. 예를 들어 자동으로 정의한 커스텀 명령을 실행하는 훅을 만들거나, 연쇄적으로 여러 액션을 실행하는 훅을 만들 수 있어요.
AI와 자동화를 처음 배우는 거라면 AI 배우기: 어디서부터 시작할까 글이 전체적인 그림을 보여줄 거예요. 훅은 자동화 개념에 대한 훌륭한 입문이고, 현대 개발에서 핵심 기술이에요.
마무리
Claude Code 훅은 반복적인 수동 작업을 백그라운드에서 실행되는 자동화로 바꿔줘요. 설정 파일을 만드는 법, 자동화 규칙을 정의하는 법, 흔한 문제를 해결하는 법을 배웠어요. 자동 포맷팅 같은 간단한 훅으로 시작해서 작은 프로젝트에서 테스트한 후, 필요에 따라 점진적으로 다른 자동화를 추가하세요. 목표는 기술적인 작업에 소요되는 시간을 줄여서 학습과 창작에 집중하는 거예요.
