Claude Code가 이제 훅(hooks)을 지원함

13 hours ago 2

Claude Code에 사용자 정의 훅 기능이 도입. LLM의 선택에 의존하지 않고, 앱의 행동을 더욱 정확하고 반복적으로 제어할 수 있음
알림 커스터마이징, 코드 자동 포맷팅, 명령 로그 추적과 같은 다양한 자동화가 가능
명령어 실행 전/후, 알림 발생, 응답 완료 시점 등에서 동작하며, 설정 파일을 통해 프로젝트·사용자·엔터프라이즈 레벨로 관리할 수 있음
설정 파일 구조와 매처(matcher) 방식을 통해, 특정 도구 호출 시점에 특정 훅만 실행할 수 있음
입력은 JSON 포맷으로 전달되고, 출력은 exit code 또는 JSON으로 결과·피드백을 제어함
훅은 셸 명령어를 사용자의 전체 권한으로 자동 실행하므로, 보안 및 안전에 대한 주의 필요함

소개

Claude Code의 훅(hook)은 코드 실행 라이프사이클 각 단계에서 자동으로 실행되는 사용자 지정 쉘 명령어
이를 통해 LLM이 선택적으로 실행하는 것 대신 매번 일관된 자동화가 가능해짐
주요 활용 예시
- 알림: 입력 대기 시 사용자에게 맞춤형 알림 제공
- 자동 포맷팅: 파일 편집 후 prettier 또는 gofmt 자동 실행
- 로깅: 실행된 명령을 기록하고 집계하여 추적이나 디버깅에 활용
- 피드백: 코드베이스 규칙에 맞지 않는 코드 생성 시 자동 피드백 제공
- 커스텀 권한: 민감 디렉터리나 프로덕션 파일에 대한 변경 차단
프롬프트가 아닌 시스템 코드로 동작하므로, 매번 확정적으로 실행됨 → 자동화의 신뢰성 증가
훅은 사용자 전체 권한으로 셸 명령을 직접 실행하므로, 안전성 검증 필요함.

구성 예제

예: Claude가 Bash 명령 실행 전마다 로그를 남기도록 후크 등록
1. /hooks 명령어로 후크 설정 메뉴 진입, PreToolUse 이벤트 선택
2. Bash 매처 추가 (Bash 명령에만 적용)
3. 후크 커맨드 등록 및 저장 (User settings 위치 선택 시 전체 프로젝트에 적용)
4. /hooks로 설정 확인 또는 ~/.claude/settings.json에서 파일 직접 확인 가능

설정 구조

후크는 매처(matcher) 기준으로 그룹화하며, 매처별로 여러 후크를 배열로 가질 수 있음
- 예: 단일 문자열(정확 매칭), 정규식, 비워두면 모든 이벤트에 적용
설정 파일 종류
- ~/.claude/settings.json: 사용자 전체 설정
- .claude/settings.json: 프로젝트 설정
- .claude/settings.local.json: 로컬(비공유) 설정
- 엔터프라이즈 정책 설정

주요 후크 이벤트

PreToolUse: 툴 호출 전 실행, 필요시 실행 차단 가능 (주요 매처: Bash, Write, Edit, Grep 등)
PostToolUse: 툴 실행 직후, 동일 매처 지원
Notification: 알림 전송 시 실행
Stop: 응답 완료 후 실행

매처 예시

Task: 에이전트 작업
Bash: 셸 명령
Glob: 파일 패턴 매칭
Grep: 내용 검색
Read: 파일 읽기
Edit, MultiEdit: 파일 수정
Write: 파일 작성
WebFetch, WebSearch: 웹 작업

입력 및 출력 형식

입력: stdin으로 JSON 전달 (세션 정보, 이벤트별 데이터 포함)
- 예: PreToolUse에는 tool_input 포함, PostToolUse에는 tool_response 추가
출력:
- exit code 0: 정상 실행, stdout은 유저에게 표시
- exit code 2: 차단, stderr가 Claude에게 피드백으로 전달 (PreToolUse에서는 툴 실행 차단)
- 기타 코드: 오류, stderr만 유저에게 표시
- 고급 제어: stdout에 JSON 반환 시, "continue" false나 "decision": "block" 등 세부 흐름 제어 가능

MCP 도구와 통합

Model Context Protocol(MCP) 기반 툴도 지원하며, 특수 네이밍 패턴(mcp____)을 통해 선택적으로 타깃팅 가능

보안 권고사항

후크는 시스템 임의 명령 실행의 위험이 있으므로, 입력값 검증, 경로 체크, 민감 파일 제외, 절대 경로 사용 등 안전 규칙 필수
설정 변경 시 즉시 반영되지 않으며, 세션 시작 시 스냅샷을 사용하고 외부 변경 시 경고 표시

실행 환경 및 디버깅

각 후크는 최대 60초 제한, 병렬 실행, 현재 작업 디렉토리·환경에서 동작
/hooks에서 설정 확인, 명령 직접 테스트, exit code·출력 체크 등으로 디버깅 가능
실행 과정과 결과는 transcript 모드(Ctrl-R)에서 확인

Read Entire Article