Hooks로 트리거형 자동화 만들기

AI 가드레일 설계 - Hooks로 위험 명령어 차단과 자동 품질 검증

Hooks란 무엇인가

Hooks는 Claude Code 내부에서 "무언가가 일어났을 때" 자동으로 스크립트를 실행하는 구조다. git의 pre-commit 훅이나 Webpack 플러그인과 같은 발상이다.

예를 들어, "Claude Code가 Bash 명령어를 실행하려 했을 때", "Claude Code가 파일을 쓴 직후", "Claude Code가 오류를 감지했을 때" 지정한 스크립트가 자동으로 실행된다.

Claude Code 작업 흐름 (Hooks 포함)

사용자: '이 버그를 고쳐줘'
│
▼
Claude Code: 파일 분석
│
▼
Claude Code: Write 툴로 파일을 수정하려 한다
│
├──▶ [PreToolUse Hook] 쓰기 전 체크 ← 여기서 개입할 수 있다
│
▼
Claude Code: 파일을 수정한다
│
├──▶ [PostToolUse Hook] 쓰기 후 lint 실행 ← 여기서도 개입할 수 있다
│
▼
Claude Code: Bash 툴로 git commit을 실행하려 한다
│
├──▶ [PreToolUse Hook] 커밋 전 테스트 실행 ← 여기서도
│
▼
완료

Hooks가 없다면, 이 모든 체크를 수동으로 요청해야 한다. "lint 돌리고 나서 수정해줘", "테스트 실행하고 나서 커밋해줘"라고 매번 말해야 한다. Hooks가 있으면, 말하지 않아도 자동으로 실행된다.

Hooks의 3가지 타입

Claude Code의 Hooks에는 3가지 타입이 있다.

PreToolUse — 툴 실행 '전'에 실행된다

Claude Code가 툴 (Bash, Write, Edit 등)을 사용하려는 직전에 실행된다. 반환값으로 툴 실행을 차단할 수 있다는 것이 가장 큰 특징이다.

용도: 가드레일, 안전성 체크, 입력 유효성 검사

PostToolUse — 툴 실행 '후'에 실행된다

Claude Code가 툴을 사용한 직후에 실행된다. 툴 실행 결과를 받아 후처리를 수행한다.

용도: lint, 테스트, 로그 기록, 알림

Notification — 알림 이벤트 시에 실행된다

Claude Code가 무언가를 사용자에게 알리는 타이밍에 실행된다. 오류나 경고 감지에 사용한다.

용도: 오류 알림, 진행 상황 보고, 경보

설정 파일 구조

Hooks는 .claude/settings.local.json에 정의한다.

{
"hooks": {
"PreToolUse": [
{
// matcher: 어떤 툴 실행 시 훅을 발동할지
// "Bash" 라면 Bash 툴 실행 시에만 발동
"matcher": "Bash",

// hook: 실행할 명령어
// 표준 입력에 툴의 입력 파라미터가 JSON 형식으로 전달된다
"hook": "bash .claude/hooks/pre-bash-safety.sh"
}
],
"PostToolUse": [
{
// matcher 는 정규 표현식도 사용 가능
// "Write|Edit" 라면 Write 또는 Edit 툴 실행 후 발동
"matcher": "Write|Edit",
"hook": "bash .claude/hooks/post-write-lint.sh"
}
],
"Notification": [
{
// Notification 에는 matcher 가 불필요
// 모든 알림 이벤트에서 발동한다
"hook": "bash .claude/hooks/on-notification.sh"
}
]
}
}

matcher 지정 방법

Hook 스크립트로의 입력

Hook 스크립트에는 표준 입력(stdin)으로 JSON 형식의 데이터가 전달된다.

// PreToolUse 의 경우: 툴에 전달하려는 파라미터
{
"tool_name": "Bash",
"tool_input": {
"command": "rm -rf /important-data"
}
}

// PostToolUse 의 경우: 툴의 실행 결과도 포함된다
{
"tool_name": "Write",
"tool_input": {
"file_path": "/path/to/file.ts",
"content": "..."
},
"tool_result": "File written successfully"
}

Hook 스크립트의 반환값

PreToolUse 훅은 종료 코드로 툴 실행 허가 여부를 제어할 수 있다.