Source: https://aiprimetech.io/ko/claude-code/hooks/

[홈](/ko/) › [Claude Code](/ko/claude-code/) › 훅

[개요](/ko/claude-code/)[설치](/ko/claude-code/install/)[CLI 참조](/ko/claude-code/cli/)[요금 및 한도](/ko/claude-code/pricing/)[Agent SDK](/ko/claude-code/sdk/)[스킬 및 플러그인](/ko/claude-code/skills/)[GitHub](/ko/claude-code/github/)[웹, 데스크톱 및 IDE](/ko/claude-code/web-and-desktop/)[모델](/ko/claude-code/models/)[오류](/ko/claude-code/errors/)[오픈 소스인가요?](/ko/claude-code/open-source/)[튜토리얼](/ko/claude-code/tutorial/)[학생용 안내](/ko/claude-code/for-students/)[QA 자동화](/ko/claude-code/qa-automation/)[Cursor와 비교](/ko/claude-code/vs-cursor/)[Codex 및 OpenCode와 비교](/ko/claude-code/vs-codex/)[하위 에이전트](/ko/claude-code/subagents/)[훅](/ko/claude-code/hooks/)[MCP](/ko/claude-code/mcp/)[생태계](/ko/claude-code/ecosystem/)[VS Code](/ko/claude-code/vscode/)[OpenRouter](/ko/claude-code/openrouter/)[요청 속도 제한](/ko/claude-code/rate-limits/)[중국어 가이드](/claude-code/zh/)

최종 업데이트: 2026년 10월 11일

# Claude Code 훅: 에이전트 동작에 대한 결정론적 제어

훅은 Claude Code가 실행 루프의 정해진 시점에 실행하는 셸 명령입니다. 도구 호출 전후, 프롬프트를 제출할 때, 작업을 마칠 때 실행됩니다. 모델이 따를 수도, 따르지 않을 수도 있는 CLAUDE.md의 지침과 달리 훅은 항상 실행됩니다. 훅을 사용하면 반드시 지켜지는 규칙을 만들 수 있습니다.

## TLDR
- 설정 위치: .claude/settings.json (프로젝트) 또는 ~/.claude/settings.json (사용자), 또는 다음으로 설정: /hooks.
- 이벤트: PreToolUse, PostToolUse, UserPromptSubmit, Notification, Stop, SubagentStop, PreCompact, SessionStart.
- 훅은 stdin으로 JSON(도구 이름, 입력, 세션)을 받습니다. 종료 코드 0은 허용하고, 종료 코드 2는 차단하며 stderr를 Claude에 전달합니다.
- 대표적인 용도: 편집할 때마다 서식 적용, 위험한 명령 차단, 종료 전 테스트 요구, 데스크톱 알림.

## 훅의 구성 

```
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "npx prettier --write \"$(jq -r .tool_input.file_path)\"" }
        ]
      }
    ]
  }
}
```

세 가지 부분으로 구성됩니다. 이벤트, 매처(도구 이벤트에서는 도구 이름에 적용하는 정규식이며, 생략하면 모든 항목과 일치), 하나 이상의 명령입니다. 명령은 이벤트를 설명하는 JSON 객체를 stdin으로 받습니다. 도구 이벤트에서는 여기에 다음이 포함됩니다: tool_name 및 tool_input. 위 예제는 이를 통해 방금 편집한 파일을 찾습니다. 다음 위치에 넣으면 .claude/settings.json 저장소와 공유할 수 있으며, ~/.claude/settings.json 에 넣으면 개인용으로 사용할 수 있습니다. 또는 다음을 실행하여 /hooks Claude Code가 작성하도록 하세요. 

## 이벤트 
- PreToolUse — 도구 실행 전입니다. 다음 작업을 할 수 있는 유일한 이벤트입니다: 차단: 종료 코드 2은 호출을 취소하며, Claude는 stderr를 차단 사유로 읽습니다.
- PostToolUse — 도구가 성공한 후입니다. 편집된 파일에 포매터, 린터, 타입 검사를 실행합니다.
- UserPromptSubmit — 프롬프트를 보낼 때입니다. 컨텍스트를 주입하거나 프롬프트를 거부할 수 있습니다.
- Stop / SubagentStop — 에이전트(또는 하위 에이전트)가 작업을 마치려 할 때입니다. 여기서 종료 코드 2은 "아직 완료되지 않음"을 뜻합니다. 대표적인 용도는 테스트가 실패하는 동안 종료를 거부하는 것입니다.
- PreCompact — 다음 작업 전입니다: /compact. 전체 대화 기록에서 필요한 내용을 저장하세요.
- SessionStart — 세션이 시작되거나 재개될 때입니다. 환경을 불러오고 알림 메시지를 출력합니다.
- Notification — Claude Code가 사용자의 주의를 필요로 할 때입니다(권한 요청, 유휴 상태). 데스크톱 또는 Slack 알림에 연결하세요. 

## 위험한 명령 차단 

```
#!/usr/bin/env bash
# .claude/hooks/guard.sh  -- PreToolUse, matcher: Bash
cmd=$(jq -r '.tool_input.command')
if echo "$cmd" | grep -Eq 'rm -rf|git push --force|DROP TABLE|--no-verify'; then
  echo "blocked by guard.sh: $cmd" >&2
  exit 2
fi
exit 0
```

종료 코드 2은 정해진 동작 규약입니다. 도구 호출은 실행되지 않으며, 훅이 stderr에 출력한 내용은 Claude가 보는 설명이 됩니다. 따라서 같은 작업을 재시도하는 대신 다른 접근 방식을 선택할 수 있습니다. 그 외의 모든 비정상 종료 코드는 기록되지만 실행을 차단하지 않습니다. 

## "테스트가 통과할 때까지 종료하지 마세요" 

```
#!/usr/bin/env bash
# Stop hook: refuse to finish while the suite is red
if ! npm test --silent >/tmp/claude-test.log 2>&1; then
  echo "Tests are failing; fix them before finishing:" >&2
  tail -n 40 /tmp/claude-test.log >&2
  exit 2
fi
```

헤드리스 실행에서는 다음 항목의 --max-turns 상한도 함께 설정하여, 정말로 수정할 수 없는 오류 때문에 무한 반복에 빠지지 않도록 하세요. 

## 훅, CLAUDE.md, 권한 비교 

CLAUDE.md는 모델이 읽는 지침이며, /permissions 은 모델이 묻지 않고 수행할 수 있는 작업의 목록입니다. 훅은 이와 관계없이 실행되는 코드입니다. 스타일과 컨텍스트에는 CLAUDE.md를, 허용할지 물어볼지를 구분하는 기준에는 권한을, 서식 적용·시크릿 검사·테스트 통과 조건·감사 로그처럼 매번 반드시 충족되어야 하는 사항에는 훅을 사용하세요. 이들은 함께 적용됩니다. 권한이 다음의 실행을 허용해도 Bash(git *) , PreToolUse 훅은 여전히 다음을 차단합니다: git push --force. 

## 훅과 게이트웨이 

훅은 로컬에서 실행되며 API에 전혀 접근하지 않으므로, Claude Code가 다음을 가리키도록 설정해도 달라지는 것은 없습니다: ANTHROPIC_BASE_URL=https://aiprimetech.io. 유용한 조합 중 하나는 다음과 같습니다: Stop 훅에서 자체 로그를 바탕으로 다음과 같은 /cost형식의 사용량을 출력하면, 사용량 기반 크레딧을 사용하는 팀은 각 세션이 끝날 때 비용을 확인할 수 있습니다.

## 먼저 무료로 사용해 보세요

신규 계정에는 $5의 무료 API 크레딧이 제공됩니다 사용할 코드: CLAUDECODE — Sonnet으로 저녁 한나절 Claude Code를 사용하기에 충분합니다. 이후에는 액면가의 7.69231배에 해당하는 크레딧이 제공됩니다.

```
export ANTHROPIC_BASE_URL=https://aiprimetech.io
export ANTHROPIC_API_KEY=your_key
```

[코드 CLAUDECODE로 계정 만들기](/register?promo=CLAUDECODE)

## 자주 묻는 질문

Claude Code 훅이란 무엇인가요?

Claude Code가 실행 루프의 이벤트 시점에 자동으로 실행하는 셸 명령입니다. 도구 호출 전후, 프롬프트 제출 시, 종료 시 실행됩니다. CLAUDE.md의 지침과 달리 결정론적으로 동작합니다.훅으로 명령을 차단하려면 어떻게 하나요?

매처가 Bash인 PreToolUse 훅에서 stdin의 tool_input.command를 검사한 뒤 코드 2으로 종료하세요. stderr 텍스트가 Claude에 차단 사유로 표시됩니다.훅은 어디에 설정하나요?

프로젝트의 .claude/settings.json(공유용) 또는 ~/.claude/settings.json(개인용)의 hooks 키 아래에 설정합니다. /hooks로 대화형 편집을 할 수 있습니다.

## 게이트웨이에서 Claude Code 실행하기

동일한 모델, 환경 변수 두 개, 액면가의 7.69231배에 해당하는 크레딧 또는 정액 무제한 요금제를 이용하세요. 신규 계정: 코드 CLAUDECODE로 $5의 무료 API 크레딧을 받으세요.[API 키 발급받기](/register?promo=CLAUDECODE) [무제한 요금제 보기](/ko/plans/)

AI Prime Tech는 독립 API 게이트웨이이며 Anthropic과 제휴 관계가 없고, Anthropic의 보증이나 후원을 받지 않습니다. “Claude”와 “Claude Code”는 Anthropic의 상표입니다. 여기에 설명된 Claude Code 기능은 작성 당시 Anthropic의 공개 문서를 기준으로 하며 자주 변경됩니다. 이 페이지의 가격과 모델 목록은 이 게이트웨이의 실시간 설정에서 가져옵니다.

## 더 많은 Claude Code 가이드

[Claude Code: 완벽 가이드](/ko/claude-code/)[Claude Code 설치 방법](/ko/claude-code/install/)[Claude Code CLI 문서: 명령어와 플래그](/ko/claude-code/cli/)[Claude Code 요금 및 한도 설명](/ko/claude-code/pricing/)[Claude Code SDK, 이제 Claude Agent SDK로](/ko/claude-code/sdk/)[Claude Code 스킬과 플러그인](/ko/claude-code/skills/)[GitHub에서 Claude Code 사용하기: App, Action 및 @claude](/ko/claude-code/github/)[Claude Code에 웹 인터페이스가 있나요? 웹, 데스크톱 및 IDE 설명](/ko/claude-code/web-and-desktop/)[Claude Code가 사용하는 모델과 변경 방법](/ko/claude-code/models/)[Claude Code 오류와 해결 방법](/ko/claude-code/errors/)[Claude Code는 오픈 소스인가요?](/ko/claude-code/open-source/)[Claude Code 튜토리얼: 첫 실전 세션](/ko/claude-code/tutorial/)[학생을 위한 Claude: Claude Code, API 및 교육 분야에서 실제로 제공되는 혜택](/ko/claude-code/for-students/)[QA 자동화에 Claude Code를 사용하는 방법](/ko/claude-code/qa-automation/)[Claude Code와 Cursor 비교: 어떤 도구를 언제 선택하고, 둘 다 어떻게 사용할까](/ko/claude-code/vs-cursor/)[Claude Code vs Codex vs OpenCode: 터미널 에이전트 비교](/ko/claude-code/vs-codex/)[Claude Code 하위 에이전트: 작동 방식, 정의 방법, 에이전트 팀](/ko/claude-code/subagents/)[Claude Code MCP: 서버 연결, 범위, 원격 MCP와 실제 예제](/ko/claude-code/mcp/)[Claude Code 생태계: 라우터, 프레임워크, 플러그인과 이를 모아 둔 목록](/ko/claude-code/ecosystem/)[VS Code에서 Claude Code 사용하기: 확장 프로그램, 터미널 사용 방식, 오류](/ko/claude-code/vscode/)[Claude Code에서 OpenRouter를 사용하는 방법과 사용하지 않는 편이 나은 경우](/ko/claude-code/openrouter/)[Claude 요청 한도 오류: "API 오류: 요청 한도 도달"의 의미와 해결 방법](/ko/claude-code/rate-limits/)[Claude Code 사용법: 설치부터 일상적인 사용까지](/claude-code/zh/)