셸 명령어를 등록하여 Claude Code의 동작을 커스터마이징하고 확장하세요.
소개
Claude Code hooks는 Claude Code의 라이프사이클의 다양한 지점에서 실행되는 사용자 정의 셸 명령어입니다. Hooks는 Claude Code의 동작에 대한 결정론적 제어를 제공하여, LLM이 선택적으로 실행하는 것에 의존하기보다는 특정 작업이 항상 발생하도록 보장합니다.
사용 사례 예시:
- 알림: Claude Code가 입력이나 실행 권한을 기다릴 때 알림을 받는 방법을 커스터마이징
- 자동 포맷팅: 모든 파일 편집 후 .ts 파일에
prettier
, .go 파일에gofmt
등을 실행 - 로깅: 컴플라이언스나 디버깅을 위해 실행된 모든 명령어를 추적하고 계산
- 피드백: Claude Code가 코드베이스 규칙을 따르지 않는 코드를 생성할 때 자동화된 피드백 제공
- 커스텀 권한: 프로덕션 파일이나 민감한 디렉토리의 수정을 차단
이러한 규칙을 프롬프트 지시사항이 아닌 hooks로 인코딩함으로써, 제안을 매번 실행될 것으로 예상되는 앱 수준 코드로 전환할 수 있습니다.
⚠️ 경고: Hooks는 확인 없이 전체 사용자 권한으로 셸 명령어를 실행합니다. hooks가 안전하고 보안성이 있는지 확인하는 것은 사용자의 책임입니다. Anthropic은 hook 사용으로 인한 데이터 손실이나 시스템 손상에 대해 책임지지 않습니다. 보안 고려사항을 검토하세요.
빠른 시작
이 빠른 시작에서는 Claude Code가 실행하는 셸 명령어를 로깅하는 hook을 추가하겠습니다.
필수 조건: 명령줄에서 JSON 처리를 위해 jq
를 설치하세요.
1단계: hooks 구성 열기
/hooks
슬래시 명령어를 실행하고 PreToolUse
hook 이벤트를 선택합니다.
PreToolUse
hooks는 도구 호출 전에 실행되며, Claude에게 다르게 수행할 작업에 대한 피드백을 제공하면서 도구 호출을 차단할 수 있습니다.
2단계: 매처(matcher) 추가
+ Add new matcher…
를 선택하여 Bash 도구 호출에서만 hook을 실행하도록 합니다.
매처에 Bash
를 입력합니다.
3단계: hook 추가
+ Add new hook…
을 선택하고 다음 명령어를 입력합니다:
jq -r '"\(.tool_input.command) - \(.tool_input.description // "No description")"' >> ~/.claude/bash-command-log.txt
4단계: 구성 저장
저장 위치로 User settings
를 선택합니다. 홈 디렉토리에 로깅하므로 이 hook은 현재 프로젝트뿐만 아니라 모든 프로젝트에 적용됩니다.
그런 다음 REPL로 돌아갈 때까지 Esc를 누릅니다. hook이 이제 등록되었습니다!
5단계: hook 확인
/hooks
를 다시 실행하거나 ~/.claude/settings.json
을 확인하여 구성을 확인합니다:
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "jq -r '\"\\(.tool_input.command) - \\(.tool_input.description // \"No description\")\"' >> ~/.claude/bash-command-log.txt"
}
]
}
]
}
구성
Claude Code hooks는 설정 파일에서 구성됩니다:
~/.claude/settings.json
- 사용자 설정.claude/settings.json
- 프로젝트 설정.claude/settings.local.json
- 로컬 프로젝트 설정 (커밋되지 않음)- 엔터프라이즈 관리 정책 설정
구조
Hooks는 매처별로 구성되며, 각 매처는 여러 hooks를 가질 수 있습니다:
{
"hooks": {
"EventName": [
{
"matcher": "ToolPattern",
"hooks": [
{
"type": "command",
"command": "your-command-here"
}
]
}
]
}
}
- matcher: 도구 이름과 매칭할 패턴 (
PreToolUse
와PostToolUse
에만 적용)- 단순 문자열은 정확히 매칭:
Write
는 Write 도구만 매칭 - 정규식 지원:
Edit|Write
또는Notebook.*
- 생략하거나 빈 문자열이면 모든 매칭 이벤트에서 hooks 실행
- 단순 문자열은 정확히 매칭:
- hooks: 패턴이 매칭될 때 실행할 명령어 배열
type
: 현재"command"
만 지원command
: 실행할 bash 명령어
Hook 이벤트
PreToolUse
Claude가 도구 매개변수를 생성한 후, 도구 호출을 처리하기 전에 실행됩니다.
일반적인 매처들:
Task
- 에이전트 작업Bash
- 셸 명령어Glob
- 파일 패턴 매칭Grep
- 컨텐츠 검색Read
- 파일 읽기Edit
,MultiEdit
- 파일 편집Write
- 파일 쓰기WebFetch
,WebSearch
- 웹 작업
PostToolUse
도구가 성공적으로 완료된 직후에 실행됩니다.
PreToolUse와 동일한 매처 값을 인식합니다.
Notification
Claude Code가 알림을 보낼 때 실행됩니다.
Stop
Claude Code가 응답을 완료했을 때 실행됩니다.
Hook 입력
Hooks는 세션 정보와 이벤트별 데이터를 포함하는 JSON 데이터를 stdin을 통해 받습니다:
{
// 공통 필드
session_id: string
transcript_path: string // 대화 JSON 경로
// 이벤트별 필드
...
}
PreToolUse 입력
tool_input
의 정확한 스키마는 도구에 따라 다릅니다.
{
"session_id": "abc123",
"transcript_path": "~/.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
"tool_name": "Write",
"tool_input": {
"file_path": "/path/to/file.txt",
"content": "file content"
}
}
PostToolUse 입력
tool_input
과 tool_response
의 정확한 스키마는 도구에 따라 다릅니다.
{
"session_id": "abc123",
"transcript_path": "~/.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
"tool_name": "Write",
"tool_input": {
"file_path": "/path/to/file.txt",
"content": "file content"
},
"tool_response": {
"filePath": "/path/to/file.txt",
"success": true
}
}
Notification 입력
{
"session_id": "abc123",
"transcript_path": "~/.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
"message": "Task completed successfully",
"title": "Claude Code"
}
Stop 입력
stop_hook_active
는 Claude Code가 이미 stop hook의 결과로 계속 진행 중일 때 true입니다. Claude Code가 무한히 실행되는 것을 방지하기 위해 이 값을 확인하거나 transcript를 처리하세요.
{
"session_id": "abc123",
"transcript_path": "~/.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
"stop_hook_active": true
}
Hook 출력
Hooks가 Claude Code로 출력을 반환하는 두 가지 방법이 있습니다. 출력은 차단 여부와 Claude와 사용자에게 표시되어야 하는 피드백을 전달합니다.
간단함: 종료 코드
Hooks는 종료 코드, stdout, stderr을 통해 상태를 전달합니다:
- 종료 코드 0: 성공.
stdout
은 transcript 모드(CTRL-R)에서 사용자에게 표시됩니다. - 종료 코드 2: 차단 오류.
stderr
은 Claude가 자동으로 처리하도록 피드백됩니다. 아래 hook 이벤트별 동작을 참조하세요. - 기타 종료 코드: 비차단 오류.
stderr
은 사용자에게 표시되고 실행이 계속됩니다.
종료 코드 2 동작
Hook 이벤트 | 동작 |
---|---|
PreToolUse | 도구 호출을 차단하고 stderr 을 Claude에게 전달 |
PostToolUse | Claude에게 stderr 을 보여주고 자동으로 계속 진행 |
Stop | Claude가 중지하는 것을 차단하고 stderr 을 피드백으로 제공 |
Notification | stderr 을 로그에 기록 |
고급: JSON 출력
더 정교한 제어를 위해 hooks는 JSON을 stdout에 출력할 수 있습니다.
JSON 출력은 간단한 종료 코드보다 우선합니다. 종료 코드 2는 모든 "decision": "block"
출력보다 우선합니다.
공통 JSON 필드
모든 JSON 출력은 선택적으로 Claude Code의 계속 여부를 제어할 수 있습니다:
{
"continue": true | false,
"stopReason": "Human-readable explanation"
}
continue: false
는 Claude Code가 다음 사용자 입력을 기다리도록 합니다. continue: true
는 Claude가 계속 진행하도록 합니다.
stopReason
은 사용자에게 표시되는 이유와 함께 continue
를 동반하며, Claude에게는 표시되지 않습니다.
PreToolUse 결정 제어
PreToolUse
hooks는 도구 호출이 진행될지 제어할 수 있습니다.
- "approve"는 권한 시스템을 우회합니다.
reason
은 사용자에게 표시되지만 Claude에게는 표시되지 않습니다. - "block"은 도구 호출이 실행되는 것을 방지합니다.
reason
은 Claude에게 표시됩니다. undefined
는 기존 권한 흐름으로 이어집니다.reason
은 무시됩니다.
{
"decision": "approve" | "block" | undefined,
"reason": "결정에 대한 설명"
}
PostToolUse 결정 제어
PostToolUse
hooks는 도구 호출이 진행될지 제어할 수 있습니다.
- "block"은 자동으로 Claude에게
reason
으로 프롬프트합니다. undefined
는 아무것도 하지 않습니다.reason
은 무시됩니다.
{
"decision": "block" | undefined,
"reason": "결정에 대한 설명"
}
Stop 결정 제어
Stop
hooks는 Claude가 계속해야 하는지 제어할 수 있습니다.
- "block"은 Claude가 중지하는 것을 방지합니다. Claude가 어떻게 진행해야 하는지 알 수 있도록
reason
을 채워야 합니다. undefined
는 Claude가 중지하도록 허용합니다.reason
은 무시됩니다.
{
"decision": "block" | undefined,
"reason": "Claude가 중지에서 차단될 때 제공되어야 함"
}
JSON 출력 예제: Bash 명령어 편집
#!/usr/bin/env python3
import json
import re
import sys
# 검증 규칙을 (정규식 패턴, 메시지) 튜플의 리스트로 정의
VALIDATION_RULES = [
(
r"\bgrep\b(?!.*\|)",
"더 나은 성능과 기능을 위해 'grep' 대신 'rg' (ripgrep)를 사용하세요",
),
(
r"\bfind\s+\S+\s+-name\b",
"더 나은 성능을 위해 'find -name' 대신 'rg --files | rg pattern' 또는 'rg --files -g pattern'을 사용하세요",
),
]
def validate_command(command: str) -> list[str]:
issues = []
for pattern, message in VALIDATION_RULES:
if re.search(pattern, command):
issues.append(message)
return issues
try:
input_data = json.load(sys.stdin)
except json.JSONDecodeError as e:
print(f"오류: 유효하지 않은 JSON 입력: {e}", file=sys.stderr)
sys.exit(1)
tool_name = input_data.get("tool_name", "")
tool_input = input_data.get("tool_input", {})
command = tool_input.get("command", "")
if tool_name != "Bash" or not command:
sys.exit(1)
# 명령어 검증
issues = validate_command(command)
if issues:
for message in issues:
print(f"• {message}", file=sys.stderr)
# 종료 코드 2는 도구 호출을 차단하고 stderr을 Claude에게 표시
sys.exit(2)
MCP 도구와 함께 작업하기
Claude Code hooks는 Model Context Protocol (MCP) 도구와 원활하게 작동합니다. MCP 서버가 도구를 제공할 때, hooks에서 매칭할 수 있는 특별한 네이밍 패턴으로 나타납니다.
MCP 도구 네이밍
MCP 도구는 mcp__<server>__<tool>
패턴을 따릅니다. 예를 들어:
mcp__memory__create_entities
- Memory 서버의 create entities 도구mcp__filesystem__read_file
- Filesystem 서버의 read file 도구mcp__github__search_repositories
- GitHub 서버의 search 도구
MCP 도구용 Hooks 구성
특정 MCP 도구나 전체 MCP 서버를 대상으로 할 수 있습니다:
{
"hooks": {
"PreToolUse": [
{
"matcher": "mcp__memory__.*",
"hooks": [
{
"type": "command",
"command": "echo 'Memory operation initiated' >> ~/mcp-operations.log"
}
]
},
{
"matcher": "mcp__.*__write.*",
"hooks": [
{
"type": "command",
"command": "/home/user/scripts/validate-mcp-write.py"
}
]
}
]
}
}
예제
코드 포맷팅
파일 수정 후 자동으로 코드 포맷팅:
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit|MultiEdit",
"hooks": [
{
"type": "command",
"command": "/home/user/scripts/format-code.sh"
}
]
}
]
}
}
알림
Claude Code가 권한을 요청하거나 프롬프트 입력이 유휴 상태가 될 때 전송되는 알림을 커스터마이징:
{
"hooks": {
"Notification": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "python3 ~/my_custom_notifier.py"
}
]
}
]
}
}
보안 고려사항
면책사항
자신의 위험 부담으로 사용: Claude Code hooks는 시스템에서 임의의 셸 명령어를 자동으로 실행합니다. hooks를 사용함으로써 다음을 인정합니다:
- 구성하는 명령어에 대해 전적으로 책임집니다
- Hooks는 사용자 계정이 액세스할 수 있는 모든 파일을 수정, 삭제 또는 액세스할 수 있습니다
- 악의적이거나 잘못 작성된 hooks는 데이터 손실이나 시스템 손상을 일으킬 수 있습니다
- Anthropic은 어떠한 보증도 제공하지 않으며 hook 사용으로 인한 손해에 대해 책임을 지지 않습니다
- 프로덕션 사용 전에 안전한 환경에서 hooks를 철저히 테스트해야 합니다
구성에 추가하기 전에 항상 hook 명령어를 검토하고 이해하세요.
보안 모범 사례
더 안전한 hooks 작성을 위한 주요 관행들:
- 입력 검증 및 정제 - 입력 데이터를 맹목적으로 신뢰하지 마세요
- 항상 셸 변수를 인용 -
$VAR
가 아닌"$VAR"
사용 - 경로 탐색 차단 - 파일 경로에서
..
확인 - 절대 경로 사용 - 스크립트에 전체 경로 지정
- 민감한 파일 건너뛰기 -
.env
,.git/
, 키 등 피하기
구성 안전성
설정 파일의 hooks에 대한 직접 편집은 즉시 적용되지 않습니다. Claude Code는:
- 시작 시 hooks의 스냅샷을 캡처
- 세션 전체에서 이 스냅샷을 사용
- hooks가 외부에서 수정되면 경고
- 변경 사항이 적용되려면
/hooks
메뉴에서 검토 필요
이는 악의적인 hook 수정이 현재 세션에 영향을 미치는 것을 방지합니다.
Hook 실행 세부사항
- 타임아웃: 60초 실행 제한
- 병렬화: 모든 매칭 hooks가 병렬로 실행
- 환경: Claude Code의 환경과 함께 현재 디렉토리에서 실행
- 입력: stdin을 통한 JSON
- 출력:
- PreToolUse/PostToolUse/Stop: transcript에 진행 상황 표시 (Ctrl-R)
- Notification: 디버그에만 로그 (
--debug
)
디버깅
Hooks 문제 해결을 위해:
/hooks
메뉴가 구성을 표시하는지 확인- 설정 파일이 유효한 JSON인지 확인
- 명령어를 수동으로 테스트
- 종료 코드 확인
- stdout 및 stderr 형식 기대치 검토
- 적절한 인용 이스케이프 확인
진행 메시지가 transcript 모드(Ctrl-R)에 나타나며 다음을 보여줍니다:
- 실행 중인 hook
- 실행되는 명령어
- 성공/실패 상태
- 출력 또는 오류 메시지
관련 링크
태그: #claude-code #hooks #automation #customization #shell-commands #mcp #security