프로그래밍 보조 AI 도구가 점점 진화하는 가운데, Anthropic의 Claude Code는 단순한 코드 생성에 그치지 않고, 개발자의 워크플로까지 통합 자동화할 수 있는 강력한 기능을 제공합니다. 그 핵심 도구 중 하나가 바로 Hooks 기능입니다.
이번 글에서는 Claude Code의 Hooks가 무엇인지, 그리고 실제 현업에서 어떻게 활용할 수 있는지 구체적인 사례와 함께 정리해보았습니다.
https://docs.anthropic.com/en/docs/claude-code/hooks
🧩 Hooks란 무엇인가?
Claude Code의 Hooks는 특정 이벤트 시점에 자동으로 셸 명령어를 실행하도록 설정하는 기능입니다. 마치 Git의 pre-commit 훅처럼, Claude의 동작 흐름 속에서 “이때 이 명령도 자동으로 실행해줘!”라고 지시할 수 있는 자동화 지점입니다.
🧭 Hooks가 동작하는 시점 (이벤트 종류)
| 이벤트 이름 | 언제 실행되는가 |
|---|---|
PreToolUse | Claude가 툴(예: Bash, Python 등)을 실행하기 직전 |
PostToolUse | 툴 실행 후 정상 종료 시점 |
Notification | 사용자 입력이나 Claude의 응답 도중 알림이 발생할 때 |
Stop | Claude의 응답이 끝났을 때 |
💡 실제 사용 예시
✅ 1. 자동 코드 포맷팅
목적: Claude가 코드를 고친 후 black, prettier 같은 포맷터를 자동 실행
Hook: PostToolUse
black $CLAUDE_FILE_PATHS
이렇게 설정하면, 사람 손 거치지 않아도 항상 일관된 코드 스타일이 유지됩니다.
✅ 2. 민감한 파일 차단
목적: Claude가 .env, .pem 등 민감한 파일을 건드리지 못하게 차단
Hook: PreToolUse
if [[ "$CLAUDE_FILE_PATHS" == *.env* ]]; then
echo "민감 파일 접근 차단됨" >&2
exit 2
fi
exit 2는 Claude에게 “이거 실행 못 해!”라고 차단 신호를 줍니다.
✅ 3. 실행 기록 남기기 (감사 로그)
목적: Claude가 어떤 셸 명령어를 실행했는지 로그로 남기기
Hook: PreToolUse
echo "$(date): $CLAUDE_TOOL_INPUT" >> ~/.claude-command-log.txt
이렇게 하면 추후 문제가 생겼을 때도 원인을 쉽게 파악할 수 있어요.
✅ 4. Claude 작업 종료 후 알림
목적: Claude가 작업을 마친 후 알림으로 알려주기
Hook: Stop
afplay /System/Library/Sounds/Ping.aiff
또는 ntfy 같은 외부 알림 툴과도 연동할 수 있습니다.
✅ 5. 자동 커밋 & 버전 관리
목적: Claude가 코드 작업을 끝낸 후 자동으로 Git에 커밋
Hook: Stop
git add .
git commit -m "Claude가 수정한 코드"
작업 흐름에 따라 Git 또는 Jujutsu(jj) 등을 사용할 수 있습니다.
🛠 설정 방법 간단 요약
- 프로젝트 또는 사용자 루트에
~/.claude/settings.json생성 - 아래와 같은 구조로 훅 작성
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "echo 실행 전: $CLAUDE_TOOL_INPUT"
}
]
}
]
}
}
🔐 주의: 훅은 로컬에서 실제로 명령을 실행하므로 악성 코드나 잘못된 명령은 시스템에 영향을 줄 수 있습니다. 신중히 사용해야 합니다.
✅ 요약
Claude Code의 Hooks 기능은 단순한 AI 코딩을 넘어, 개발자의 작업 흐름을 자동화하는 트리거 시스템입니다. 이를 잘 활용하면:
- AI가 작업할 때마다 자동으로 포맷, 커밋, 로깅, 알림 등을 처리할 수 있고
- 실수로 민감한 파일을 수정하는 것을 방지하며
- 반복적인 작업을 자동화하여 생산성과 안정성을 함께 높일 수 있습니다.
🔚 마무리
Claude Code를 단순한 AI 코딩 도우미가 아닌, 개발 파이프라인의 자동화 파트너로 만들고 싶다면 Hooks를 적극 활용해보세요. 다음 글에서는 실제 설정 예제 모음과 함께, 나만의 훅 설정 템플릿을 공유할 예정입니다.
궁금한 점 있으시면 댓글이나 메일로 언제든지 문의 주세요 😊
