Claude Code의 사용자 정의 훅 기능 – 자동화의 정밀 제어를 실현하다

일관된 자동화가 필요한 이유

코드 기반 업무 자동화는 반복 업무를 줄이고 생산성을 높이는 데 필수적인 수단이다. 하지만 LLM 기반 도구는 때때로 실행이 불확실하거나 예측 불가능한 방식으로 동작한다. 이를 해결하고자 Claude Code는 '사용자 정의 훅(Hook)' 기능을 도입했다. 이 기능은 사용자가 특정 조건과 시점에서 실행할 명령어를 정의함으로써, 보다 정교하고 신뢰성 있는 자동화를 구성할 수 있게 한다.

이 글에서는 Claude Code의 훅 기능이 어떤 구조로 설계되어 있으며, 어떤 방식으로 작동하고, 실제 개발 환경에서 어떻게 활용할 수 있는지를 심층적으로 설명한다.

반응형

훅(Hook)의 개념과 작동 방식

Claude Code의 훅은 코드 실행 흐름의 특정 이벤트 지점에서 자동으로 작동하는 사용자 정의 셸 명령어다. 사용자는 명령 실행 전, 실행 후, 알림 발생 시, 응답 완료 시점 등 다양한 단계에서 원하는 명령을 설정할 수 있다.

이 기능은 프롬프트나 명령어 기반이 아닌 시스템 코드 수준에서 동작하므로, 매번 일관된 방식으로 자동화가 실행된다는 점이 가장 큰 특징이다. 이는 자동화의 반복성과 신뢰성을 확보하는 데 핵심적인 역할을 한다.

주요 후크 이벤트

Claude는 코드 실행 흐름 중 여러 이벤트 포인트를 제공하며, 각 포인트마다 특정 매처(Matcher)를 설정해 특정 조건에 맞는 후크만 작동하게 할 수 있다.

• PreToolUse: 도구 실행 직전에 동작. 작업 차단도 가능하다.
• PostToolUse: 도구 실행 직후에 후처리용으로 사용.
• Notification: 알림이 발생하기 직전에 작동.
• Stop: 응답 완료 시점에서 정리 작업을 수행할 때 사용.

매처 시스템

훅은 이벤트와 함께 ‘매처(Matcher)’ 조건을 설정할 수 있다. 매처는 어떤 종류의 명령어 또는 작업이 실행될 때 후크가 작동할지를 결정한다.

• Task: Claude의 에이전트 작업 전반
• Bash: 셸 명령 실행 시
• Glob: 특정 파일 패턴과 매칭되는 작업
• Grep: 특정 텍스트 검색 작업
• Read / Edit / Write: 파일 읽기, 편집, 쓰기 작업
• WebFetch / WebSearch: 웹에서 데이터를 가져오거나 검색할 때

매처는 문자열, 정규식 등으로 설정 가능하며, 비워 둘 경우 모든 작업에 적용된다.

활용 예시 및 주요 기능

1. 작업 전 알림 전송

입력 대기 상태에서 사용자에게 커스터마이징된 알림을 보냄으로써 대기 시간을 줄이고 사용성을 개선할 수 있다.

2. 코드 포맷 자동화

파일 편집 직후 prettier, gofmt 등 포맷터를 자동 실행해 코드 스타일을 유지할 수 있다. 이는 협업에서 특히 유용하며 코드 리뷰 효율을 높인다.

3. 명령어 실행 로깅

모든 Bash 명령 실행 시 로그를 남겨 개발 및 운영 환경에서의 변경사항 추적, 문제 진단, 사용자 행동 분석에 활용할 수 있다.

4. 자동 피드백

LLM이 잘못된 규칙을 따르는 코드를 생성할 경우 자동으로 경고하거나, 코드 생성을 차단하는 등의 피드백 루틴을 구성할 수 있다.

5. 민감 디렉터리 보호

운영 환경의 핵심 디렉터리에 대한 접근 또는 변경 시도를 자동 감지하고 차단함으로써 보안과 안전성을 확보할 수 있다.

구성 방법 및 설정 예제

설정 파일 구성

Claude의 훅 설정은 JSON 형식의 파일로 관리되며, 아래와 같은 계층 구조를 가진다.

• ~/.claude/settings.json: 사용자 전역 설정
• .claude/settings.json: 프로젝트별 설정
• .claude/settings.local.json: 로컬 전용 설정 (공유되지 않음)

설정 예시: Bash 명령 실행 전 로깅

1. /hooks 명령으로 설정 메뉴 진입
2. PreToolUse 이벤트 선택
3. 매처로 Bash 선택
4. 로그 기록용 커맨드 작성
5. 적용 범위 지정 및 저장

해당 설정은 매번 Bash 명령이 실행되기 전, 지정한 로그 저장 명령이 작동하도록 구성된다.

입출력 포맷 및 후크 제어 방식

입력 구조

후크 명령어는 stdin으로 JSON 입력을 받는다. 이 입력은 세션 정보와 함께 실행 중인 이벤트에 맞는 데이터를 포함한다.

• PreToolUse에는 tool_input
• PostToolUse에는 tool_response

출력 구조

• exit code 0: 정상 실행. stdout 내용은 사용자에게 표시
• exit code 2: 명령 실행 차단. stderr는 Claude에게 피드백으로 전달
• 기타 코드: 오류. stderr만 사용자에게 표시

특정 조건에 따라 흐름을 중단하거나 다음 단계를 막을 수 있으며, JSON 형태로 continue: false, decision: block 등 세밀한 흐름 제어도 가능하다.

보안 고려사항

훅 기능은 매우 강력하지만, 동시에 보안 위험을 수반한다. 후크는 사용자 전체 권한으로 셸 명령어를 실행하므로 다음과 같은 보안 가이드라인을 반드시 따라야 한다.

• 입력값 검증
• 민감 디렉터리 접근 제한
• 외부 명령어 실행 시 절대 경로 사용
• 경로 탐색 오류 방지
• 설정 변경 시 경고 및 로그 기록

또한 훅은 세션 시작 시 스냅샷 기준으로 동작하므로 외부에서 설정이 변경된 경우 이를 즉시 반영하지는 않으며, 경고 메시지가 표시된다.

728x90

Claude Code의 사용자 정의 훅 기능은 단순한 자동화 수단을 넘어, 개발자의 작업 흐름을 정밀하게 제어하고 각 단계에서 명확한 동작을 보장하는 고급 기능이다.
특정 조건 하에 자동 포맷팅, 실행 기록, 보안 차단, 사용자 알림, 피드백 전달 등 다양한 기능을 정확하게 구현할 수 있으며, 이는 협업 환경에서 더욱 강력한 통제력을 제공한다.

Claude Code를 활용한 개발 자동화 환경에서 '예측 가능하고 일관된 동작'이 중요하다면, 이 훅 기능은 업무 효율과 시스템 신뢰성을 모두 향상시키는 결정적인 도구가 될 수 있다.

https://docs.anthropic.com/en/docs/claude-code/hooks

Hooks - Anthropic