Claude Code Hooks 완전 가이드 — AI로 개발 워크플로우를 자동화하는 방법

이미 Claude Code로 프로젝트를 개발하고 계시다면, 이런 생각을 해보셨을 겁니다. AI가 특정 동작을 실행할 때 자동으로 무언가를 할 수 있지 않을까? 예를 들어, 코드를 작성한 후 자동으로 포맷팅하거나, 위험한 명령어를 실행하기 전에 차단한다거나요.

정답은 바로 Hooks입니다.

Hooks는 Claude Code의 .claude/settings.json에 숨겨져 있는 강력한 기능으로, AI의 핵심 동작 시점(도구 실행 전, 도구 실행 후, 대화 종료 전)에 사용자 정의 스크립트를 삽입하여 자동화된 품질 게이트, 보안 검사, 학습 회고까지 구현할 수 있습니다.

이 글에서는 Hooks의 기본 개념부터 설정 방법, 그리고 실제 사용 가능한 세 가지 예제까지 안내합니다.

Hooks란 무엇인가요?

Claude Code의 Hooks는 세 가지로 나뉩니다.

1. PreToolUse — 도구 실행 전 트리거

Claude Code가 도구(Read, Bash, Write, Edit 등)를 호출하기 전에 실행됩니다.

주요 용도:

  • 위험한 명령어 차단(rm -rf, 파괴적인 git 작업)
  • 권한 확인
  • 필수 파일 검증

2. PostToolUse — 도구 실행 후 트리거

도구가 실행 완료된 후에 실행됩니다. 이 시점에서 도구의 출력 결과를 확인할 수 있습니다.

주요 용도:

  • 코드 포맷팅(black, prettier)
  • 문법 검사
  • 자동화 테스트
  • 배포 후 헬스 체크

3. Stop — 대화 종료 전 트리거

사용자가 exit를 입력하거나 Claude Code가 대화 종료를 결정할 때 트리거됩니다.

주요 용도:

  • Session 종료 전 학습 요약
  • 비용 추적 통계
  • 미완료 의사결정 알림

왜 Hooks가 필요한가요?

Hooks가 가장 큰 가치를 발휘하는 세 가지 시나리오를 소개합니다.

품질 게이트(Quality Gate)

“Commit 전에 매번 자동으로 코드 품질을 검사한다” — 과거에는 CI/CD pipeline이 필요했지만, 이제는 Hook 하나로 가능합니다.

보안 검사

Claude Code는 강력하지만, 위험한 명령어를 실행할 수도 있습니다. PreToolUse Hook을 사용하면 rm -rf 실행 전에 확인 팝업을 띄우거나, DROP TABLE을 직접 차단할 수 있습니다.

자동화 기록 및 학습

매번 Session이 끝날 때 자동으로 비용 통계와 학습 요약을 실행하면, AI 협업을 기억이 있는 시스템으로 만들 수 있습니다.

설정 방법

프로젝트 또는 전역의 .claude/settings.json에 hooks 필드를 추가합니다.

1
2
3
4
5
6
7

{
  "hooks": {
    "PreToolUse": [...],
    "PostToolUse": [...],
    "Stop": [...]
  }
}

각 Hook은 다음 요소로 구성됩니다.

필드설명
matcher어떤 도구에서 트리거할지 지정. 예: Bash, `Edit
hooks[].type현재 command만 지원
hooks[].command실행할 명령어. $TOOL_INPUT 등의 환경 변수 사용 가능
hooks[].statusMessage실행 시 Claude Code에 표시되는 안내 텍스트(선택)
hooks[].timeout타임아웃 초(선택, 기본값 30초)

실제 예제

예제 1: PostToolUse — Python 파일 작성 후 자동 Black 포맷팅

Edit 또는 Write로 .py 파일을 수정한 후 자동으로 black 포맷팅을 실행합니다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

"PostToolUse": [
  {
    "matcher": "Edit|Write",
    "hooks": [
      {
        "type": "command",
        "command": "bash /path/to/hooks/auto-format.sh \"$TOOL_INPUT\"",
        "statusMessage": "Black 포맷팅 중..."
      }
    ]
  }
]

1
2
3
4
5
6

#!/bin/bash
# auto-format.sh
FILE="$1"
if [[ "$FILE" == *.py ]]; then
    black "$FILE" 2>/dev/null && echo "✓ Black 포맷팅 완료: $FILE"
fi

예제 2: PreToolUse — Bash 명령어 보안 차단

Bash 명령어를 실행하기 전에 위험한 작업인지 확인합니다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

"PreToolUse": [
  {
    "matcher": "Bash",
    "hooks": [
      {
        "type": "command",
        "command": "bash /path/to/hooks/pre-bash-guard.sh \"$TOOL_INPUT\"",
        "statusMessage": "보안 검사 중..."
      }
    ]
  }
]

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

#!/bin/bash
# pre-bash-guard.sh
# 주의: 이 스크립트는 예제이며, 실제 사용 전 필요에 맞게 수정하세요
CMD="$1"
DANGEROUS_PATTERNS=(
    "rm -rf /"
    "DROP TABLE"
    "git reset --hard"
    "mkfs"
    "dd if=/dev/zero"
)

# case 문을 사용한 부분 문자열 매칭(권장 방식)
blocked=0
for pattern in "${DANGEROUS_PATTERNS[@]}"; do
    case "$CMD" in
        *"$pattern"*)
            blocked=1
            break
            ;;
    esac
done

if [[ $blocked -eq 1 ]]; then
    echo "⚠️  위험한 명령어가 차단되었습니다: $CMD"
    echo "안전이 확인되면 수동으로 실행하거나 settings.json의 Hooks를 수정하세요."
    exit 1
fi

예제 3: Stop — Session 종료 전 자동 학습

대화가 끝나기 전에 이번 Session의 학습 요약과 비용 통계를 자동 생성합니다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

"Stop": [
  {
    "matcher": "*",
    "hooks": [
      {
        "type": "command",
        "command": "node /path/to/hooks/session-summary.js",
        "statusMessage": "Session 요약 생성 중..."
      }
    ]
  }
]

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

// session-summary.js
const fs = require("fs");
const date = new Date().toISOString().slice(0, 10);

const summary = `
=== Session 회고 (${date}) ===

이번 Session에서 완료한 내용:
- [여기에 Claude가 자동으로 채움]

다음에 개선할 점:
- [위와 동일]

소요 시간: Agent Cost Guardian의 예산 기록을 확인하세요
`;

console.log(summary);

고급 활용법

1. Matcher 와일드카드

Matcher설명
*모든 도구
BashBash만
`EditWrite`
`ReadGlob

2. statusMessage — 친절한 안내

1

"statusMessage": "Python 문법 검사 중..."

실행 시 Claude Code 인터페이스에 이 텍스트가 표시되어, 현재 무엇이 진행 중인지 알 수 있습니다.

3. timeout — 무한 대기 방지

1

"timeout": 30

기본값은 30초입니다. 포맷팅 도구나 네트워크 작업에는 timeout을 설정하여 무한 대기를 방지하는 것이 좋습니다.

4. 여러 Hook 연결

동일한 트리거 포인트에 여러 Hook을 연결할 수 있습니다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

"PostToolUse": [
  {
    "matcher": "Edit|Write",
    "hooks": [
      { "type": "command", "command": "black \"$TOOL_INPUT\"" },
      { "type": "command", "command": "pylint \"$TOOL_INPUT\"" },
      { "type": "command", "command": "pytest -q \"$TOOL_INPUT\"" }
    ]
  }
]

마치며

Hooks는 Claude Code에서 가장 과소평가된 기능 중 하나입니다. Hooks를 통해 AI는 “수동적으로 질문에 답하는 도구"에서 “개발 워크플로우에 능동적으로 참여하는 자동화 파트너"로 변모합니다.

간단한 코드 포맷팅부터 복잡한 보안 게이트와 학습 시스템까지, Hooks의 가능성은 여러분의 개발 워크플로우가 무엇을 필요로 하느냐에 달려 있습니다.

다음 글 예고: Claude Code에서 MCP(Model Context Protocol)를 결합하여 더욱 강력한 AI 워크플로우를 구축하는 방법을 다룰 예정입니다. 기대해 주세요.

참고 자료

AI 지휘관 핸드북 — 비개발자를 위한 OpenClaw AI 팀 구축 가이드
$14.90 · 8개 챕터 + 6종 템플릿
자세히 보기 →