SSD Nodes Learn Hosting plans →
가이드 Matt Connor작성자 Matt Connor

Claude Code 훅 설정 방법 및 동작 원리 완벽 정리

Claude Code 훅의 실행 원리와 설정 위치를 상세히 설명합니다. 모델의 동의 없이 실행되는 훅의 특성, PreToolUse 이벤트에서 exit 2를 사용하여 도구 호출을 강제로 취소하는 방법, 그리고 보안상 주의해야 할 점을 버전 2.1.296 기준으로 정리했습니다.

Claude Code 훅이란 무엇인가

Claude Code 훅은 Claude Code가 자체 수명 주기의 특정 시점에 스스로 실행하는 셸 명령입니다. 이것이 훅과 규칙 파일의 근본적인 차이점입니다. CLAUDE.md의 지침은 조언이며, 모델은 이를 문맥 내의 다른 모든 정보와 비교하여 판단합니다. 반면 훅은 코드이며, 모델의 동의 여부와 관계없이 실행됩니다. 에이전트가 두 번이나 지시한 포맷터를 계속 건너뛴다면, 더 강력한 지침이 필요한 것이 아니라 훅이 필요한 것입니다.

이 메커니즘은 단순합니다. 설정 파일의 이벤트 이름 아래에 명령을 등록하면 됩니다. 해당 이벤트가 발생하면 Claude Code는 명령을 실행하고 이벤트 데이터를 JSON(JavaScript object notation) 형식으로 표준 입력(stdin)에 기록합니다. 명령은 이 데이터를 읽어 작업을 수행하고 종료 상태를 반환합니다. PreToolUse 훅에서 종료 코드 2를 반환하면 도구 호출이 실행되기 전에 취소되며, 스크립트가 표준 오류(stderr)에 기록한 내용은 모델에게 거부 사유로 전달됩니다. 단, 훅이 차단 결정을 포함한 JSON을 출력하는 경우에는 해당 사유가 우선합니다.

여기에 언급된 이벤트 이름과 필드 이름은 2026년 11월 12일 기준으로 확인된 Claude Code 훅 참조 문서를 따릅니다. 이 인터페이스는 빠르게 변경되므로, 본 게시물을 포함한 블로그 글의 JSON을 복사하기 전에 반드시 현재 버전의 참조 문서를 확인하십시오. 본인의 설정은 claude --version로 출력할 수 있습니다.

훅 설정이 위치하는 곳

훅은 설정 파일 내의 JSON 블록입니다. 훅은 6개의 위치에 저장될 수 있으며, 파일의 범위가 곧 훅의 범위가 됩니다.

  • ~/.claude/settings.json: 사용자의 머신에 있는 모든 프로젝트에 적용되며, 다른 사용자에게는 영향을 주지 않습니다.
  • .claude/settings.json: 하나의 프로젝트에 적용되며, 저장소에 커밋되므로 해당 저장소를 복제하는 모든 사용자에게 훅이 적용됩니다.
  • .claude/settings.local.json: 하나의 프로젝트에 적용되며, 사용자의 머신에서만 유효합니다.
  • 관리형 정책 설정: 조직 전체에 적용되며, 관리자가 설정합니다.
  • hooks/hooks.json: 플러그인 내부에 위치하며, 해당 플러그인이 활성화되어 있는 동안 유지됩니다.
  • 스킬 또는 서브 에이전트의 프론트매터: 스킬의 훅은 해당 스킬이 호출된 이후 세션이 유지되는 동안 활성화되며, 서브 에이전트의 훅은 해당 서브 에이전트가 실행되는 동안 활성화됩니다.

이 파일들로부터 가져온 훅 항목들은 서로를 덮어쓰지 않고 병합됩니다. 프로젝트 설정 파일은 사용자 설정 파일에 있는 훅을 대체하는 것이 아니라 추가하므로, 하나의 이벤트에 여러 파일에서 가져온 여러 훅이 포함될 수 있습니다. "disableAllHooks": true 설정을 사용하면 훅을 끌 수 있지만, 한 가지 예외가 있습니다. 관리형 정책 설정에서 가져온 훅은 해당 설정이 관리형 설정 내에서 적용되지 않는 한 계속 실행됩니다.

세션 내에서 /hooks를 실행하면 현재 등록된 모든 훅을 이벤트별로 그룹화하여 나열할 수 있으며, 각 훅의 소스 파일과 매처를 확인할 수 있습니다. 이 메뉴는 읽기 전용이므로, 훅을 변경하려면 설정 파일을 직접 수정해야 합니다. 파일 감시자(file watcher)는 일반적으로 재시작 없이도 수정 사항을 즉시 반영합니다.

Claude Code 훅 이벤트의 종류

훅 참조 문서에는 SessionStart부터 SessionEnd까지 총 33개의 이벤트가 나열되어 있으며, 여기에는 압축(compaction), 하위 에이전트, 작업 트리, 설정 파일 관련 이벤트가 포함됩니다. 서버 작업에서는 이 중 일부를 사용합니다.

  • PreToolUse: EndConversation을 제외하고 도구 호출이 실행되기 전에 발생합니다. 이 이벤트는 차단(block)이 가능합니다.
  • PostToolUse: EndConversation을 제외하고 도구 호출이 성공한 후에 발생합니다. 실패 시에는 PostToolUseFailure이 발생하므로, 모든 결과를 확인해야 하는 훅은 두 이벤트 모두를 사용해야 합니다.
  • PermissionRequest: 도구 호출에 권한 결정이 필요할 때, 즉 승인 프롬프트가 나타나는 시점에 발생합니다.
  • UserPromptSubmit: 사용자가 프롬프트를 제출하고 Claude가 이를 처리하기 전에 발생합니다. 성공한 훅에서 출력한 일반 텍스트(stdout)는 모델의 컨텍스트에 추가됩니다.
  • SessionStart 및 SessionEnd: 세션의 각 시작과 종료 시점에 발생합니다. SessionStart은 압축 작업 후에도 발생하며, 이때 매처(matcher) 값은 compact입니다.
  • Stop: Claude가 응답을 완료했을 때 발생합니다. 이는 작업 단위가 아닌 턴(turn)당 한 번 발생합니다.

매처를 지원하는 이벤트의 경우, 그룹은 matcher를 포함하여 어떤 경우에 훅을 실행할지 결정할 수 있습니다. 도구 이벤트에서는 도구 이름으로 필터링하므로, "Edit|Write"은 파일 편집 시에만 발생하고 다른 경우에는 발생하지 않습니다. 매처는 대소문자를 구분합니다. 매처가 비어 있으면 모든 경우에 실행됩니다. MCP(Model Context Protocol) 서버에서 제공하는 도구는 mcp__<server>__<tool>로 명명되므로, "mcp__github__.*"라는 매처를 사용하면 특정 서버의 도구만 포착하고 나머지는 무시할 수 있습니다.

Stop 훅을 작성할 때 주의해야 할 함정이 있습니다. 차단 기능을 가진 Stop 훅은 모델을 다시 작업 상태로 돌려보내는데, 기본적으로 Claude Code는 8번 연속으로 작업을 이어갈 경우 다음 차단 시도를 무시합니다. 이 횟수는 Claude가 도구를 호출할 때마다 초기화됩니다. 훅 입력에서 stop_hook_active 필드를 확인하여 값이 true일 때 0으로 종료하십시오. 그렇지 않으면 훅이 계속해서 Claude를 작업 상태로 되돌려 보낼 수 있습니다.

훅이 stdin으로 수신하는 데이터

Claude가 npm test를 실행하려고 할 때, Bash의 PreToolUse 훅은 stdin을 통해 다음 데이터를 읽습니다.

{
  "session_id": "abc123",
  "cwd": "/home/deploy/myproject",
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm test"
  }
}

일반적인 입력 필드에는 session_id, cwd, transcript_path, hook_event_name이 포함됩니다. permission_mode는 모든 이벤트에서 전송되지는 않습니다. 도구 이벤트에는 tool_name, tool_input, tool_use_id가 추가됩니다. 다른 이벤트들은 각자의 필드를 가집니다. UserPromptSubmit은 prompt 텍스트를 가져오며, SessionStart는 startup, resume, clear, compact 또는 fork 중 하나의 source을 가져옵니다.

jq는 셸 스크립트 내부에서 이 데이터를 읽는 일반적인 방법이지만, 최소 사양의 서버 이미지에는 포함되어 있지 않습니다. Ubuntu 및 Debian에서는 sudo apt install -y jq을 사용하여 먼저 설치하십시오.

종료 상태가 실행 중인 도구 호출에 미치는 영향

결과는 세 가지입니다.

  • 종료 상태 0은 성공을 의미하며, 차단이나 거부를 포함한 모든 유효한 JSON 결정 필드가 적용됩니다. PreToolUse에서 결정 없이 종료 상태 0을 반환하는 것은 승인을 의미하지 않으며, 일반적인 권한 흐름이 계속 실행됩니다. UserPromptSubmit, UserPromptExpansion, SessionStart 및 PostModelSwitch에서는 일반 텍스트 stdout이 모델의 컨텍스트에 추가됩니다. 다른 대부분의 이벤트에서 stdout은 디버그 로그로만 전송됩니다.
  • 종료 상태 2는 PreToolUse를 포함하여 차단 가능한 이벤트에서 작업을 차단하며, JSON 출력에 차단 결정이 포함되어 있지 않은 경우 stderr가 차단 메시지로 사용됩니다(JSON 결정이 있는 경우 해당 이유가 우선합니다). 메시지를 확인하는 주체는 이벤트에 따라 다릅니다. PreToolUse 및 Stop에서 모델은 이를 차단 사유로 인식합니다. UserPromptSubmit 및 PreModelSwitch에서는 사용자에게 표시되며 모델의 컨텍스트에는 추가되지 않습니다. 차단할 수 없는 PostToolUse 및 PostToolUseFailure에서는 차단이 무시되지만, stderr는 피드백으로 모델에 전달됩니다. 차단할 수 없는 다른 대부분의 이벤트에서 stderr는 사용자에게만 표시되거나 무시됩니다. Stop, SubagentStop, TaskCompleted 및 플러그인의 UserPromptSubmit 훅에서 stdout이 비어 있고 stderr에 파일 누락 오류가 있는 경우, 종료 상태 2는 차단하지 않는 오류로 처리됩니다.
  • 그 외의 종료 코드와 일반 텍스트 또는 빈 stdout은 일반적으로 차단하지 않는 오류입니다. 트랜스크립트에는 Failed with non-blocking status code: 텍스트 뒤에 stderr의 첫 번째 줄을 포함하는 훅 오류 알림이 표시됩니다. 훅 실패가 작업을 차단하지 않는 한, PreToolUse과 같은 이벤트에서는 유효한 JSON이 여전히 결과를 결정할 수 있습니다. WorktreeCreate는 0이 아닌 모든 종료 상태에서 실패하며, WorktreeRemove은 작업 후에도 디렉터리가 존재할 경우 0이 아닌 종료 상태에서 실패합니다.

차단이나 조용한 처리를 넘어선 동작을 원한다면, 종료 상태 0을 반환하고 JSON 객체를 stdout으로 출력하십시오. PreToolUse 훅은 permissionDecision를 사용하여 결정합니다:

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Database drops go through a migration, not through the agent."
  }
}

"allow"은 권한 규칙 및 도구의 승인 요구 사항이 허용하는 경우 대화형 프롬프트를 건너뛰고, "deny"은 호출을 취소하고 그 이유를 모델에 전송하며, "ask"은 확인을 요청합니다. 훅당 하나의 방식을 선택하십시오. 종료 상태 2와 JSON 결정을 stdout에 함께 사용하면 JSON에 "allow"라고 명시되어 있더라도 차단 상태가 유지됩니다.

여러 훅이 하나의 이벤트와 일치하면 병렬로 실행되며, 프롬프트 및 에이전트 훅은 한 번에 12개까지만 실행되도록 제한됩니다. 한 훅에서 발생한 deny은 다른 훅을 중단시키지 않으므로, 가드레일 훅이 동일한 호출을 거부하더라도 로깅 훅은 로그를 기록합니다. PreToolUse의 경우, Claude Code는 응답을 병합하여 거부, 보류, 질문, 허용 순으로 가장 제한적인 결과를 유지합니다.

예제 1: 파괴적인 명령어가 실행되기 전에 차단하기

이 내용을 프로젝트의 .claude/hooks/block-destructive.sh로 저장합니다:

#!/bin/bash
# Deny a Bash tool call whose command matches a banned pattern.
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

for pattern in 'rm -rf /' 'mkfs' 'dd if=' 'DROP TABLE'; do
  if printf '%s' "$COMMAND" | grep -qiF -- "$pattern"; then
    echo "Blocked by policy: the command matches '$pattern'. A human runs this one." >&2
    exit 2
  fi
done

exit 0

실행 권한을 부여한 뒤, .claude/settings.json의 PreToolUse에 등록합니다:

chmod +x .claude/hooks/block-destructive.sh
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-destructive.sh",
            "timeout": 10,
            "statusMessage": "Checking the command against policy"
          }
        ]
      }
    ]
  }
}

스크립트를 신뢰하기 전에 직접 테스트하십시오. onFailure가 설정되지 않은 상태에서 자체 입력값으로 인해 충돌하는 훅은 일반적으로 차단 없이 통과(fail open)하기 때문입니다. Git Bash가 없는 Windows 환경에서는 셸 형식의 PreToolUse 또는 PermissionRequest 명령어 훅이 실패할 경우 도구 호출 자체를 차단할 수 있습니다:

echo '{"tool_name":"Bash","tool_input":{"command":"rm -rf /var/lib/postgresql"}}' \
  | .claude/hooks/block-destructive.sh
echo $?

stderr에 Blocked by policy: 줄이 출력되고 종료 코드가 2로 나타나야 합니다. ls -la과 같은 무해한 명령어를 입력하면 아무런 출력 없이 종료 코드 0이 반환되어야 합니다. 세션 내에서 거부된 호출은 귀하가 작성한 이유와 함께 기록에 나타나며, 모델은 해당 메시지를 읽고 대응 방식을 조정합니다.

이 작업을 수행할 가치가 있는 이유는 한 가지 특성 때문입니다. PreToolUse 훅은 모든 권한 모드에서 권한 모드 검사보다 먼저 실행되므로, bypassPermissions 상태에서도 거부 설정이 유지됩니다. 이것이 바로 Claude Code 자동 모드 및 권한 설정과 함께 훅을 사용할 때 유용한 이유입니다. 자동 모드에서는 프롬프트가 제한되더라도 훅은 여전히 작동하기 때문입니다.

이 기능의 한계를 명확히 인지하십시오. 명령어 문자열에 대한 패턴 매칭은 에이전트의 부주의를 방지하는 안전장치일 뿐, 에이전트의 교묘한 우회 시도를 막는 경계선은 아닙니다. 동일한 명령어도 grep가 인식하지 못하는 형태로 작성될 수 있기 때문입니다. 엄격한 규칙은 권한 시스템과 프로세스가 실행되는 계정 수준에서 적용해야 합니다.

예제 2: 편집할 때마다 포맷팅 및 린트 수행

PostToolUse와 Edit|Write 매처를 사용하면 해당 파일 편집 도구가 성공적으로 실행된 후 이 작업이 수행됩니다. 이 내용을 .claude/hooks/after-edit.sh로 저장하십시오:

#!/bin/bash
# Format the edited file, then report lint failures back to the model.
INPUT=$(cat)
FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
[ -z "$FILE" ] && exit 0

case "$FILE" in
  *.py)
    ruff format "$FILE" >/dev/null 2>&1
    if ! ruff check "$FILE" >&2; then
      exit 2
    fi
    ;;
  *.sh)
    if ! shellcheck "$FILE" >&2; then
      exit 2
    fi
    ;;
esac

exit 0
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/after-edit.sh",
            "timeout": 60
          }
        ]
      }
    ]
  }
}

Claude에게 Python 파일에 들여쓰기가 잘못된 함수를 추가하도록 요청한 뒤 파일을 열어보십시오. 파일이 자동으로 포맷팅되어 있을 것입니다. 훅이 성공적으로 실행되었음을 확인하는 방법입니다. 훅이 성공하면 대화창에 아무런 메시지도 표시되지 않기 때문입니다.

여기서 exit 2는 아무것도 되돌리지 않습니다. PostToolUse은 도구가 이미 실행된 후에 작동하므로, 어떤 경우든 편집 내용은 디스크에 저장됩니다. exit 2를 사용하는 이유는 ruff check 출력이 피드백 형태로 모델에 전달되도록 하기 위함입니다. 이를 통해 모델은 다음 단계로 넘어가지 않고 방금 발생시킨 오류를 스스로 수정하게 됩니다. 이것이 커밋 시점에 발견하는 린트 실패와 에이전트가 동일한 턴 내에서 복구하는 린트 실패의 차이점입니다.

여기서 두 가지 매처 제한 사항을 고려해야 합니다. Edit|Write은 셸 명령으로 변경된 파일은 감지하지 못하며, Claude는 Bash을 통해 파일을 자주 작성하므로 이 간극은 실질적인 문제가 될 수 있습니다. 호출별로 커버리지를 확보하려면 Bash도 매칭하고 스크립트가 git status --porcelain을 사용하여 변경된 파일 목록을 나열하도록 하십시오. 턴당 한 번씩 커버리지를 확보하려면 스캔 작업을 Stop 훅에 배치하십시오.

예제 3: 감사(audit)를 위해 모든 도구 호출 기록하기

PostToolUse의 빈 매처(matcher)는 EndConversation을 제외한 모든 성공적인 도구 호출 시 실행됩니다. 기록을 홈 디렉터리의 파일이 아닌 시스템 저널로 전송한다고 해서 에이전트의 셸이 접근하지 못하게 되는 것은 아닙니다. 접근 권한은 해당 계정의 권한 설정에 따라 결정됩니다. 사용자는 자신의 개인 저널을 읽을 수 있으며, root와 systemd-journal, adm 또는 wheel 그룹의 구성원은 모든 저널 파일을 읽을 수 있습니다.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "jq -c '{time: now|todate, session: .session_id, cwd: .cwd, tool: .tool_name, input: .tool_input}' | logger -t claude-code -p local0.info"
          }
        ]
      }
    ]
  }
}

journalctl -t claude-code -o cat | tail -n 5을 사용하여 기록을 확인하십시오. 기록을 읽을 권한이 있다면 EndConversation를 제외한 성공적인 도구 호출마다 JSON 한 줄이 출력되며, 가장 최근 기록이 마지막에 표시됩니다. 아무것도 나타나지 않으면 저널 접근 권한과 훅(hook)이 정상적으로 실행되었는지 확인하십시오. 아래의 문제 해결 섹션에서 훅 관련 내용을 다룹니다.

실패한 호출을 캡처하려면 PostToolUseFailure 아래에 동일한 블록을 추가하십시오. PostToolUse는 성공 시에만 실행되며, 보통 실패한 명령어가 더 중요한 정보를 담고 있기 때문입니다. 홈 디렉터리의 파일에 내용을 추가하는 대신 logger를 사용하는 이유는 소유권 때문입니다. 훅은 에이전트 셸과 동일한 사용자의 권한으로 실행되므로, 해당 사용자가 내용을 추가할 수 있는 파일이라면 언제든 내용을 삭제(truncate)할 수도 있습니다. 저널은 systemd-journald에 의해 기록되지만, 삭제로부터 보호하는 것은 여전히 에이전트 계정의 권한 설정에 달려 있습니다.

훅이 실행될 수 있는 시간

차트Default hook timeout in seconds, by hook type and event
이 차트의 데이터
[
  {
    "label": "command, http or mcp_tool hook",
    "default_timeout_seconds": 600
  },
  {
    "label": "agent hook",
    "default_timeout_seconds": 60
  },
  {
    "label": "prompt hook",
    "default_timeout_seconds": 30
  },
  {
    "label": "command, http or mcp_tool on UserPromptSubmit, PreModelSwitch or PostModelSwitch",
    "default_timeout_seconds": 30
  },
  {
    "label": "command, http or mcp_tool on MessageDisplay",
    "default_timeout_seconds": 10
  },
  {
    "label": "any hook on SessionEnd",
    "default_timeout_seconds": 1.5
  }
]

명령어 훅은 기본적으로 600초, 즉 10분의 실행 시간을 가집니다. 일부 이벤트는 이 시간을 대폭 단축합니다. SessionEnd 훅은 모든 훅이 1.5초의 예산을 공유하므로 세션 종료 시 정리 작업은 신속하게 이루어져야 합니다. 다만 설정 파일에서 훅의 timeout 값을 더 길게 지정하면 공유 예산도 최대 60초까지 그에 맞춰 늘어납니다.

타임아웃에 도달한 동기식 명령어, HTTP 또는 MCP 도구 훅은 취소되며 일반적으로 아무런 결정도 내리지 않습니다. PreModelSwitch의 경우 타임아웃은 전환을 차단합니다. PreToolUse 가드레일의 경우, 타임아웃이 발생하면 일반적으로 도구 호출이 정상적인 권한 흐름으로 계속 진행됩니다. 단, onFailure이 설정되지 않은 경우 앞서 언급한 Windows 예외 사항이 적용됩니다. 이러한 이유로 가드레일 스크립트는 작게 유지하십시오. 2.1.295 릴리스부터는 "onFailure": "block"를 사용하여 command 또는 http 훅의 기본 동작을 반전시킬 수 있습니다. 이를 설정하면 타임아웃, 충돌 또는 예상치 못한 종료 코드가 발생할 때 차단 처리가 됩니다. 다만 이 설정은 Stop, SubagentStop, TaskCompleted, TeammateIdle 또는 백그라운드 명령어 훅에는 영향을 주지 않습니다. 로그 전송과 같이 사용자가 기다릴 필요가 없는 느린 작업의 경우, "async": true를 설정하면 훅이 도구 호출을 지연시키지 않고 백그라운드에서 실행됩니다.

훅, 규칙 파일, 스킬 및 MCP 서버

네 가지 요소는 모두 에이전트의 동작을 변경하기 때문에 서로 혼동하기 쉽습니다. 이 중 오직 하나만이 제안 수준을 넘어 강제성을 가집니다.

규칙 파일(CLAUDE.md 또는 .claude/rules/ 하위의 파일)은 모델의 컨텍스트로 로드되는 텍스트입니다. 이는 동작의 방향을 설정하지만 아무것도 강제하지 않습니다. 긴 대화, 방대한 diff, 새로운 사용자 요청이 이어지는 상황에서 규칙 파일의 한 줄은 무시될 수 있습니다. 이것이 바로 에이전트가 작성된 지침을 무시하는 현상 뒤에 숨겨진 일반적인 메커니즘입니다.

스킬은 모델이 관련성이 있다고 판단할 때 로드하는 지침과 스크립트의 폴더입니다. 이 판단 과정이 스킬의 핵심이자 한계이기도 합니다. 여전히 결정은 모델이 내리기 때문입니다. 작동하는 가장 작은 변경 사항을 유도하는 Ponytail과 같은 스킬에서 이 양면성을 확인할 수 있습니다. 이는 훅으로는 불가능한 방식으로 전체 작업에 접근하는 방식을 형성하며, 모델이 로드하기로 선택한 경우에만 작동합니다.

MCP(Model Context Protocol) 서버는 모델이 호출할 수 있는 새로운 도구를 제공합니다. 이는 에이전트가 접근할 수 있는 범위를 넓혀줍니다. 하지만 에이전트가 무언가를 강제로 수행하게 만들지는 않으며, 별도의 프로세스로 직접 운영해야 합니다. 이는 그 자체로 하나의 작업입니다. VPS에서 MCP 서버 실행하기를 참조하십시오.

훅은 이 네 가지 중 모델의 선택 없이 실행되는 유일한 요소입니다. 선호 사항을 설정하려면 규칙 파일을 사용하고, 모델이 적용할 때 따라야 할 절차는 스킬을 사용하십시오. 매번 반드시 발생해야 하는 단계나 절대 발생해서는 안 되는 작업에는 훅을 사용하십시오. 스킬이 규칙 파일보다 나은 경우를 포함한 더 자세한 비교는 스킬, MCP 및 규칙 파일 비교에서 확인할 수 있습니다.

플러그인은 다섯 번째 메커니즘이라기보다 패키징 방식에 가깝습니다. 훅과 스킬을 하나의 설치 가능한 단위로 묶어주며, 팀이 동일한 가드레일을 모든 머신에 배포하는 방식입니다. Claude Code 플러그인 작동 방식을 참조하십시오.

공유 VPS에서의 보안 결정

훅은 에이전트가 트리거하는 코드이며, Claude Code를 시작한 사용자의 권한으로 실행됩니다. 따라서 해당 사용자의 파일 권한과 환경을 그대로 상속받습니다. 노트북 환경에서는 워크플로의 문제이지만, 에이전트가 무인으로 실행되는 VPS에서는 네 가지 실질적인 보안 문제가 발생합니다.

저장소 내의 훅은 본인이 작성하지 않은 코드입니다. .claude/settings.json는 커밋되는 대상이므로, 저장소를 복제하고 그 안에서 세션을 시작하면 저장소에 포함된 훅이 등록될 수 있습니다. 대화형 세션에서 Claude Code는 해당 폴더에 대한 작업 공간 신뢰 대화 상자를 통해 프로젝트 훅을 제어합니다. 즉, 신뢰를 수락하는 순간 훅을 실행하기로 결정하는 것입니다. 먼저 hooks 블록을 읽어보십시오. 무인 에이전트가 주로 실행되는 claude -p 또는 SDK 세션은 대화 상자를 표시하지 않고 폴더를 신뢰하는 것으로 간주하므로, 저장소의 훅이 확인 없이 실행됩니다. 스크립트를 작성하기 전에 .claude/ 파일을 검토하거나 --settings '{"disableAllHooks": true}' 옵션을 사용하여 실행하십시오.

훅은 전체 도구 입력을 볼 수 있습니다. tool_input을 기록하는 감사 훅은 모든 명령의 인자를 로그에 기록하며, 여기에는 명령줄에 포함된 모든 토큰이 포함될 수 있습니다. 따라서 해당 로그는 비밀 정보와 동일한 수준의 보호가 필요하며, 이는 AI 에이전트가 비밀 정보에 접근하지 못하게 하는 방법이라는 더 넓은 문제의 일부입니다.

훅은 모델의 문맥에 내용을 기록할 수 있습니다. 성공적인 SessionStart 또는 UserPromptSubmit 훅의 일반 텍스트 표준 출력(stdout)은 대화 내용에 추가됩니다. 외부 이슈 트래커나 로그 파일에서 텍스트를 파이프라인으로 가져오는 훅은, 마치 사용자가 직접 입력한 것처럼 신뢰할 수 없는 텍스트를 모델에게 전달하는 행위입니다. 동일한 VPS의 다른 Claude Code 세션에서 메모를 전달하는 훅도 마찬가지이며, 에이전트의 출력물은 이슈 트래커의 내용보다 더 신뢰할 근거가 없습니다. 해당 표준 출력을 출력물이 아닌 입력물로 취급하십시오.

권한이 실질적인 통제 수단입니다. 에이전트는 필요한 sudo 규칙만 가진 전용 비권한 사용자로 실행하십시오. PreToolUse 거부 설정을 사용하는 것이 좋으나, 이는 설계상 최선의 노력(best effort)일 뿐입니다. 참조 문서에서도 if 필터에 대해 동일하게 설명하며, 강력한 거부가 필요할 때는 시스템 수준의 권한 설정을 사용하라고 권고합니다. 압박이 가해질 때 버틸 수 있는 것은 권한 규칙과 프로세스가 실행되는 계정입니다.

모든 권한 모드에서 유지되는 속성이 하나 있습니다. PreToolUse 훅은 모든 권한 모드에서 권한 모드 검사보다 먼저 실행되므로, deny를 반환하는 훅은 bypassPermissions 상태에서도 도구를 차단합니다. 훅은 권한 규칙이 허용하는 범위를 좁힐 수는 있지만, 넓힐 수는 없습니다. 예외는 모드(mod)입니다. 관리되는 설정이 없고 managed-mcp.json 파일이 없으며, /login을 통해 팀 또는 엔터프라이즈 플랜에 로그인하지 않은 세션에서는 tool.check를 처리하는 설치된 모드가 PreToolUse 훅이 차단한 호출을 승인할 수 있습니다. 관리되는 설정, managed-mcp.json 파일, 또는 세션 자격 증명으로 팀이나 엔터프라이즈 /login를 사용하는 경우, PreToolUse 훅이 차단한 호출은 훅의 출처와 관계없이 기본적으로 차단 상태를 유지합니다. API 키나 장기 지속형 CLAUDE_CODE_OAUTH_TOKEN로 실행되는 세션은(많은 서버가 이 방식을 사용합니다) 로그인이 저장되어 있더라도 로그인하지 않은 것으로 간주됩니다. 서버에 모드를 설치하기 전에 Claude Code 모드가 변경할 수 있는 범위를 확인하십시오.

왜 훅이 실행되지 않습니까?

다음 순서대로 문제를 해결하십시오. 각 단계는 실제로 나타나는 증상을 기준으로 합니다.

  • /hooks를 실행하여 예상한 이벤트 아래에 훅이 나타나는지 확인하십시오. 메뉴에 훅이 보이지 않는다면 설정 파일에 JSON 문법 오류가 있을 가능성이 큽니다. JSON은 후행 쉼표나 주석을 허용하지 않으며, 파일이 위에서 언급한 6개 위치 중 하나에 있어야 합니다.
  • 매처(matcher)와 도구 이름을 정확히 비교하십시오. 매처는 대소문자를 구분하므로 "bash"은 Bash 도구와 일치하지 않습니다.
  • 위의 예제 1과 같이 샘플 입력을 사용하여 스크립트를 직접 실행해 보십시오. 예상치 못한 종료 코드가 반환된다면 스크립트의 버그입니다. 스크립트의 표준 출력(stdout)도 확인하십시오. 유효한 JSON이라도 PreToolUse과 같은 이벤트에 대해 결정을 내릴 수 있기 때문입니다.
  • jq: command not found라는 알림이 표시된다면 해당 머신에 jq이 없는 것입니다. 본인의 스크립트에서 command not found 오류가 발생한다면 경로를 찾지 못한 것이므로 ${CLAUDE_PROJECT_DIR}를 사용하거나 절대 경로를 지정하십시오. 스크립트가 전혀 실행되지 않는다면 실행 권한이 없을 가능성이 높습니다.
  • 훅이 유효한 JSON을 출력하는데 아무 일도 일어나지 않는 경우입니다. macOS와 Linux에서 셸 형식의 훅은 비대화형 셸의 sh -c을 통해 실행되지만, 일부 설정에서는 ~/.bashrc를 가리키는 BASH_ENV와 같이 프로필을 소싱(source)하기도 합니다. 만약 해당 프로필이 배너를 출력하면 그 배너가 JSON 앞에 추가됩니다. 표준 출력이 {으로 시작하지 않게 되므로, Claude Code는 전체 내용을 일반 텍스트로 읽고 결정을 무시합니다. 훅이 0을 반환하며 종료되었기 때문에 기록에는 오류가 남지 않습니다. 대부분의 이벤트에서 해당 텍스트는 디버그 로그에만 기록되지만, UserPromptSubmit, UserPromptExpansion, SessionStart, PostModelSwitch 이벤트에서는 배너를 포함한 전체 내용이 모델의 컨텍스트에 추가됩니다. 프로필 내의 모든 echo은 대화형 셸에서만 실행되도록 감싸십시오.
  • 여전히 해결되지 않는다면 claude --debug-file /tmp/claude.log로 세션을 시작하고 두 번째 터미널에서 tail -f /tmp/claude.log을 실행하십시오. 디버그 로그에는 어떤 훅이 일치했는지, 각 훅이 어떤 종료 코드를 반환했는지, 그리고 표준 출력과 표준 에러로 무엇을 출력했는지가 모두 기록됩니다.

FAQ

Claude Code 훅과 CLAUDE.md 지침의 차이점은 무엇입니까?

CLAUDE.md 지침은 모델의 컨텍스트에 포함된 텍스트이므로 대화 내용 및 현재 요청과 주의력을 두고 경쟁하며, 모델이 이를 다른 요소와 비교하여 가중치를 둘 수 있습니다. 반면 훅은 Claude Code가 수명 주기의 특정 시점에 실행하는 셸 명령이므로, 모델의 판단과 관계없이 이벤트가 발생할 때마다 실행됩니다. 선호 사항을 설정할 때는 지침을 사용하고, 반드시 수행해야 하는 단계나 절대 일어나지 않아야 하는 작업에는 훅을 사용하십시오.

Claude Code가 특정 셸 명령을 실행하지 못하게 하려면 어떻게 해야 합니까?

.tool_input.command에서 명령을 읽고, stderr에 이유를 출력한 뒤 2를 반환하는 Bash 매처(matcher)와 함께 PreToolUse 훅을 등록하십시오. Claude Code는 해당 호출을 취소하고 모델에게 이유를 표시합니다. 이 과정은 권한 모드 확인 이전에 발생하므로 bypassPermissions 모드에서도 거부 설정이 유지됩니다. 명령 문자열에 대한 패턴 매칭은 보안 경계라기보다는 가드레일에 가깝습니다. 동일한 명령이라도 패턴이 놓칠 수 있는 형태로 작성될 수 있으므로, 권한 규칙 및 권한이 제한된 계정을 함께 사용하여 보완하십시오.

훅이 올바른 JSON을 출력하는데 아무 일도 일어나지 않습니다. 왜 그렇습니까?

셸 프로필에서 JSON 앞에 출력되는 텍스트가 있는지 확인하십시오. macOS 및 Linux에서 args 필드가 없는 훅은 sh -c을 통해 실행됩니다. ~/.bashrc를 가리키는 BASH_ENV과 같이 프로필을 소싱하는 설정에서는, 배너를 출력하는 프로필이 JSON보다 앞서 stdout에 내용을 기록합니다. 이로 인해 출력이 {으로 시작하지 않게 되어 Claude Code는 전체 내용을 일반 텍스트로 간주하고 결정을 무시합니다. 훅이 0을 반환하며 종료되었기 때문에 기록상에는 오류가 나타나지 않습니다. 프로필의 모든 echo는 대화형 셸 테스트로 보호하고, claude --debug-file /tmp/claude.log의 디버그 로그를 읽어 수정 사항을 확인하십시오.

공유 서버에서 Claude Code 훅을 실행해도 안전합니까?

훅은 Claude Code를 시작한 사용자의 권한으로 실행되며 해당 사용자의 파일 권한을 따르므로, 해당 계정이 할 수 있는 모든 작업을 수행할 수 있습니다. 두 가지 습관으로 대부분의 위험을 방지할 수 있습니다. 첫째, 에이전트를 제한적인 sudo 정책을 가진 전용 비권한 계정으로 실행하십시오. 둘째, 저장소의 작업 공간 신뢰 대화 상자를 수락하거나 그 안에서 claude -p을 실행하기 전에 해당 저장소의 hooks 블록을 읽어보십시오. 프로젝트 훅은 .claude/settings.json 내부에 포함되어 제공되며, -p 모드에서는 해당 대화 상자가 표시되지 않기 때문입니다. 훅을 비활성화하려면 설정 파일에서 "disableAllHooks": true을 설정하십시오. 단, 관리 수준에서 해당 설정이 필요한 관리형 훅은 예외입니다. false의 프로젝트 설정은 true의 사용자 설정을 재정의할 수 있습니다.

이 글이 도움이 되었나요?