이 글은 JudyAI Lab의 AI 엔지니어링 시리즈 중 하나입니다 — 100편 이상 발행된 가이드, 60개국 5,000명 이상의 주간 독자가 읽는 콘텐츠로, AI 에이전트·트레이딩 시스템·콘텐츠 파이프라인의 실전 운영에 초점을 둡니다.

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

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

정답은 바로 Hooks입니다.

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

2026년 11월 업데이트: 공식 문서(Hooks reference)에 따르면 이 글을 쓴 뒤 Hooks가 크게 확장되었습니다. 아래 사항은 원문과 다르며 이쪽이 우선합니다.

  1. 이벤트는 3가지가 아니라 33가지입니다. SessionStart, UserPromptSubmit, PermissionRequest, PostToolUseFailure, SubagentStop, PreCompact, SessionEnd 등이 있고, 이 글은 자주 쓰는 PreToolUse / PostToolUse / Stop만 다룹니다.
  2. type은 command만이 아니라 command, http, mcp_tool, prompt, agent를 지원합니다(agent는 실험적 기능으로 표시).
  3. Hook 입력은 JSON이며 command 타입에서는 stdin으로 전달됩니다. 문서화된 $TOOL_INPUT 환경 변수는 없으므로 아래 예제를 stdin 읽기 방식으로 바꿨습니다.
  4. 동작을 차단하려면 반드시 exit 2여야 합니다(stderr 내용이 Claude에게 전달됨). exit 1은 비차단 오류라 동작이 그대로 실행됩니다.
  5. command 타입의 기본 타임아웃은 600초입니다(prompt 30초, agent 60초).
  6. Stop은 Claude가 응답을 마칠 때 트리거되며, 세션 종료 시에는 SessionEnd가 트리거됩니다.

이 글에서는 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가 대화 종료를 결정할 때 트리거된다고 썼으나, 현재 공식 문서 기준으로 Stop은 Claude가 응답을 마칠 때 트리거되고 세션 종료는 SessionEnd 이벤트가 담당합니다.

주요 용도:

  • 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[].typecommand, http, mcp_tool, prompt, agent
hooks[].command실행할 명령어. 입력 JSON은 stdin으로 전달
hooks[].statusMessage실행 시 Claude Code에 표시되는 안내 텍스트(선택)
hooks[].timeout타임아웃 초(선택, command 타입 기본값 600초)

실제 예제

예제 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",
        "statusMessage": "Black 포맷팅 중..."
      }
    ]
  }
]
1
2
3
4
5
6
#!/bin/bash
# auto-format.sh (입력 JSON은 stdin으로 전달, jq 필요)
FILE=$(jq -r '.tool_input.file_path // empty')
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",
        "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
29
#!/bin/bash
# pre-bash-guard.sh
# 주의: 이 스크립트는 예제이며, 실제 사용 전 필요에 맞게 수정하세요
# 입력 JSON은 stdin으로 전달, jq 필요
CMD=$(jq -r '.tool_input.command // empty')
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" >&2
    echo "안전이 확인되면 수동으로 실행하거나 settings.json의 Hooks를 수정하세요." >&2
    exit 2  # 차단하려면 반드시 exit 2. 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

command 타입의 기본값은 600초입니다(원문의 30초는 더 이상 맞지 않음). 포맷팅 도구나 네트워크 작업에는 더 짧은 timeout을 명시하는 것이 좋습니다.

4. 여러 Hook 연결

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
"PostToolUse": [
  {
    "matcher": "Edit|Write",
    "hooks": [
      { "type": "command", "command": "bash /path/to/hooks/run-black.sh" },
      { "type": "command", "command": "bash /path/to/hooks/run-pylint.sh" },
      { "type": "command", "command": "bash /path/to/hooks/run-pytest.sh" }
    ]
  }
]

마치며

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

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

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


참고 자료

핵심 수치

  • 3 個 Hooks 유형 (PreToolUse, PostToolUse, Stop)
  • command 타입 기본 timeout 600초 (2026년 11월 공식 문서 기준)
  • 60 個 국가 독자 분포