Claude Code Hooks로 AI 개발 자동화하기

Claude Code Hooks는 AI 에이전트의 동작을 자동으로 제어하는 시스템이다. CLAUDE.md가 "권고"라면 Hooks는 "강제"다. CLAUDE.md는 Claude가 80% 정도 따르지만, Hooks는 100% 실행된다.

사전 지식: Claude Code 기본 사용법과 MCP 개념은 이전 글을 참고한다.

 

1. Hooks란 무엇인가

Hooks는 Claude Code 라이프사이클의 특정 시점에 자동으로 실행되는 셸 명령어다.

구분	CLAUDE.md	Hooks
실행 보장	약 80% (권고)	100% (강제)
형태	마크다운 텍스트	셸 스크립트, HTTP, 프롬프트
용도	코딩 스타일, 규칙	포맷팅, 보안, 자동화
설정 위치	CLAUDE.md 파일	settings.json

핵심: 포맷팅, 린팅, 보안 검증처럼 반드시 실행되어야 하는 것은 Hooks로 만든다.

 

2. Hook 이벤트 종류

Claude Code는 12개 이상의 라이프사이클 이벤트를 제공한다.

세션 이벤트

이벤트	시점	용도
SessionStart	세션 시작/재개 시	환경 변수 설정, 컨텍스트 로드
SessionEnd	세션 종료 시	로그 저장, 정리 작업

도구 이벤트

이벤트	시점	용도
PreToolUse	도구 실행 전	차단, 입력 수정, 권한 제어
PostToolUse	도구 실행 후	자동 포맷팅, 결과 가공
PostToolUseFailure	도구 실패 후	에러 컨텍스트 추가

에이전트 이벤트

이벤트	시점	용도
UserPromptSubmit	프롬프트 제출 직후	입력 검증, 컨텍스트 주입
Stop	Claude 응답 완료 시	품질 검증, 추가 작업 지시
PreCompact	컨텍스트 압축 전	핸드오버 정보 저장

 

3. 설정 구조

Hooks는 settings.json에 설정한다. 3개 범위가 있다.

범위	파일 경로	용도
전역	~/.claude/settings.json	모든 프로젝트 공통
프로젝트	.claude/settings.json	팀 공유
프로젝트 로컬	.claude/settings.local.json	개인 설정

기본 구조:

{
  "hooks": {
    "이벤트명": [
      {
        "matcher": "매칭 패턴",
        "hooks": [
          {
            "type": "command",
            "command": "실행할 명령어",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

 

4. 실전 예제: 파일 저장 후 자동 포맷팅

Claude가 파일을 수정할 때마다 포맷터를 자동 실행하는 Hook이다.

#!/bin/bash
# .claude/hooks/format.sh

INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path')

case "$FILE_PATH" in
  *.ts|*.tsx|*.js|*.jsx)
    npx prettier --write "$FILE_PATH" 2>/dev/null
    ;;
  *.py)
    python -m black "$FILE_PATH" 2>/dev/null
    ;;
esac

핵심: Hook 스크립트는 JSON을 stdin으로 받는다. jq로 필요한 필드를 추출한다.

 

5. 실전 예제: 위험한 명령어 차단

.env 파일이나 프로덕션 설정을 실수로 수정하지 못하게 차단한다.

#!/bin/bash
# .claude/hooks/block-sensitive.sh

INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path')

BLOCKED=(".env" ".env.local" "credentials.json")

for pattern in "${BLOCKED[@]}"; do
  if [[ "$FILE_PATH" == *"$pattern"* ]]; then
    echo "보안 파일 수정 차단: $FILE_PATH" >&2
    exit 2
  fi
done
exit 0

Exit 코드 규칙

Exit 코드	의미	동작
0	성공 (허용)	도구 실행 진행
2	차단	도구 실행 중단, stderr가 Claude에게 전달
그 외	비차단 에러	로그에만 기록

 

6. 세션 시작 시 컨텍스트 자동 로드

세션이 시작될 때 프로젝트 상태를 Claude에게 자동 전달한다.

#!/bin/bash
# .claude/hooks/load-context.sh

BRANCH=$(git branch --show-current 2>/dev/null)
COMMITS=$(git log --oneline -3 2>/dev/null)

echo "{\"hookSpecificOutput\":{\"hookEventName\":\"SessionStart\",\"additionalContext\":\"Branch: $BRANCH | Commits: $COMMITS\"}}"

additionalContext에 넣은 텍스트가 Claude의 컨텍스트에 자동 추가된다.

 

7. 테스트 자동 실행

Claude가 코드를 수정하면 관련 테스트를 자동 실행한다.

#!/bin/bash
# .claude/hooks/auto-test.sh

INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path')

if [[ "$FILE_PATH" == *.test.* ]]; then
  npx vitest run "$FILE_PATH" 2>&1
  exit 0
fi

TEST="${FILE_PATH%.ts}.test.ts"
if [ -f "$TEST" ]; then
  npx vitest run "$TEST" 2>&1
fi
exit 0

 

8. Stop Hook으로 품질 검증

Claude가 작업을 마치려 할 때 타입 체크를 실행한다.

#!/bin/bash
# .claude/hooks/quality-check.sh

CHANGED=$(git diff --name-only 2>/dev/null)
[ -z "$CHANGED" ] && exit 0

if echo "$CHANGED" | grep -q '\.ts$'; then
  ERRORS=$(npx tsc --noEmit 2>&1)
  if [ $? -ne 0 ]; then
    echo "TypeScript 타입 에러:" >&2
    echo "$ERRORS" >&2
    exit 2
  fi
fi
exit 0

Stop 이벤트에서 exit 2를 반환하면 Claude가 멈추지 않고 계속 작업한다.

 

9. Matcher 패턴

패턴	의미	예시
"Write"	Write 도구만	파일 생성 시
"Write|Edit"	Write 또는 Edit	파일 수정 시
"Bash"	Bash 도구만	셸 명령어 실행 시
"mcp__.*"	모든 MCP 도구	MCP 도구 실행 시
"*" 또는 생략	모든 도구	항상 실행

부수 효과가 있는 도구(Write, Edit, Bash)에만 Hook을 거는 것이 성능상 올바르다.

 

10. 나만의 자동화 조합

{
  "hooks": {
    "SessionStart": [{ "matcher": "startup", "hooks": [
      { "type": "command", "command": ".claude/hooks/load-context.sh" }
    ]}],
    "PreToolUse": [{ "matcher": "Write|Edit", "hooks": [
      { "type": "command", "command": ".claude/hooks/block-sensitive.sh" }
    ]}],
    "PostToolUse": [{ "matcher": "Write|Edit", "hooks": [
      { "type": "command", "command": ".claude/hooks/format.sh" },
      { "type": "command", "command": ".claude/hooks/auto-test.sh", "timeout": 60 }
    ]}],
    "Stop": [{ "hooks": [
      { "type": "command", "command": ".claude/hooks/quality-check.sh" }
    ]}]
  }
}

이 조합으로:

• 세션 시작 시 프로젝트 상태 자동 로드
• 파일 수정 전 보안 파일 차단
• 파일 수정 후 자동 포맷팅 + 테스트
• 작업 완료 시 타입 체크 + 품질 검증

 

정리

• Hooks는 Claude Code 라이프사이클에 자동 실행되는 셸 명령어다
• CLAUDE.md가 80% 권고라면 Hooks는 100% 강제 실행이다
• PreToolUse로 위험한 작업을 차단하고, PostToolUse로 자동 포맷팅을 건다
• Stop Hook으로 품질 검증을 자동화할 수 있다
• Exit 코드 2는 차단을 의미하며, stderr 메시지가 Claude에게 전달된다
• Matcher는 정규식이므로 "Write|Edit"처럼 파이프로 지정한다
• 성능을 위해 부수 효과가 있는 도구에만 Hook을 건다

 

관련 링크

• MCP 개념과 설정 가이드: https://leesmemo.tistory.com/69
• TypeScript MCP 서버 npm 배포: https://leesmemo.tistory.com/71

참고 자료

• Claude Code Hooks 공식 문서: https://code.claude.com/docs/en/hooks
• Claude Code Hooks 설정법: https://claude.com/blog/how-to-configure-hooks
• Hooks 마스터 예제: https://github.com/disler/claude-code-hooks-mastery