로드 중
로드 중

훅

CLAUDE.md 파일에 Claude에게 무언가를 하라고 적어두는 방식에는 문제가 있습니다. 그것은 요청이지 보장이 아니라는 점입니다. "항상 편집 후 포맷팅하라"고 써두면 Claude는 대체로 그 말을 따릅니다. 대체로요. 하지만 여러분이 지켜보고 있지 않은 긴 실행 과정에서는 "대체로"만으로는 충분하지 않습니다. 훅은 이 문제를 해결합니다. 훅은 루프 내의 고정된 시점에서 실행되는 결정론적 코드이므로, 동작을 바라는 대신 보장할 수 있습니다. "Claude는 대체로 따른다"는 규칙을 "Claude는 건너뛸 수 없다"로 바꿔주는 것입니다.

이것이 전체 요지입니다. 이제 실제로 어떻게 작동하는지 살펴보겠습니다.

훅 이벤트

Claude Code는 세션이 진행되는 동안 약 30개의 훅 이벤트를 발생시킵니다. 이 모든 것을 알아야 할 필요는 없으며, 훅 레퍼런스에 모든 항목이 나열되어 있습니다. 반복해서 자주 사용하게 되는 소수의 훅이 있으며, 이는 여러분이 개입하고 싶을 만한 에이전틱 루프 상의 지점들과 맞아떨어집니다.

이들이 루프 안에서 어떻게 위치하는지 살펴보겠습니다. 세션이 시작되고, 프롬프트가 들어오고, 도구가 호출되고, 결국 턴이 끝납니다. 이 각각의 순간마다 코드를 걸어둘 수 있는 훅이 존재합니다.

알아둘 만한 것들은 다음과 같습니다:

  • PreToolUse는 도구 호출 전에 발생합니다. 이것이 여러분의 강제 실행 기본 장치입니다. 어떤 일이 일어나기 전에 멈출 수 있는 유일한 훅입니다.
  • PostToolUse는 성공적인 도구 호출 후에 발생합니다. 보통 자동 포맷팅이나 자동 린트가 여기에 들어갑니다.
  • Stop은 Claude가 턴을 끝내려고 할 때 발생합니다. 어떤 조건이 충족되지 않았다면 "아니, 아직 끝나지 않았다"고 거부할 수 있습니다. 서브 에이전트가 끝날 때를 위한 대응 이벤트인 SubagentStop도 있습니다.
  • PreCompact와 PostCompact는 압축(compaction) 전후에 발생합니다.
  • InstructionsLoaded는 CLAUDE.md나 규칙 파일이 로드될 때 발생합니다. 실제로 컨텍스트에 무엇이 들어갔는지 감사하기에 편리합니다.
  • SessionStart는 시작 시점에 발생하며 환경을 준비합니다. 새로 시작할 때만 적용하고 싶다면 startup 소스를 사용하세요.

사람들이 흔히 헷갈리는 부분이 있습니다. 압축 후 컨텍스트를 다시 주입하려면 PostCompact를 사용하지 마세요. compact 매처와 함께 SessionStart를 사용하세요. 그 출력이 실제로 대화로 다시 들어가는 것은 바로 이 훅입니다.

PreToolUse: JSON으로 결정 반환하기

PreToolUse가 진정한 힘을 발휘하는 곳입니다. 도구 호출이 실행되기 전에 막을 수 있기 때문입니다. Claude에게 응답하는 방법은 JSON을 출력하고 0으로 종료하는 것입니다. 핵심 필드는 permissionDecision이며, 다음 세 가지 값 중 하나를 가집니다:

  • allow — 호출을 통과시킵니다
  • deny — 호출을 중단시킵니다
  • ask — 사용자에게 판단을 넘깁니다

기술적으로는 네 번째 값인 defer도 있지만, 이는 호출 프로세스가 도구를 일시 중지했다가 나중에 다시 재개하는 비대화형 -p 실행에만 적용됩니다. 이 값을 쓸 일은 거의 없을 것입니다.

형태는 다음과 같습니다:

json
{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Don't push to main. Open a pull request instead."
  }
}

호출을 차단하는 대신, 다시 작성할 수도 있습니다. updatedInput과 함께 allow 또는 ask를 반환하세요. ask를 사용하면 다시 작성된 호출을 확인하고 승인할 수 있습니다. allow를 사용하면 프롬프트 없이 바로 실행됩니다:

json
{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "ask",
    "updatedInput": {
      "command": "..."
    }
  }
}

이것이 bash 명령에서 비밀 정보를 지우고도 여전히 실행되도록 하는 방법입니다. 한 가지 주의할 점은, updatedInput이 입력 객체 전체를 교체한다는 것입니다. 따라서 변경하지 않는 필드도 다시 넣어 주어야 하며, 그렇지 않으면 해당 필드를 잃게 됩니다.

JSON을 반환하지 않는 훅을 위한 종료 코드

모든 훅이 JSON으로 말할 필요는 없습니다. 더 단순한 훅의 경우 종료 코드로 충분합니다. 중요한 숫자는 세 가지입니다.

  • 0은 성공입니다. 표준 출력이 JSON이면 Claude가 이를 파싱합니다. 대부분의 이벤트에서는 일반 텍스트가 무시되지만, SessionStart, UserPromptSubmit, UserPromptExpansion에서는 일반 텍스트가 컨텍스트에 추가됩니다. 이것이 바로 상태 보존 훅을 작동시키는 메커니즘입니다.
  • 2는 차단 오류입니다. 표준 에러가 컨텍스트로 Claude에게 다시 전달됩니다. 거의 모든 곳에서 이것이 차단용 종료 코드입니다.
  • 그 밖의 값은 차단되지 않습니다. 표준 에러는 기록되고, Claude는 계속 진행합니다.

사람들을 헷갈리게 만드는 것은 종료 코드 1입니다. 오류처럼 느껴지지만, 실제로는 차단하지 않습니다. Claude는 어쨌든 해당 명령을 실행합니다. 따라서 무언가를 멈추려는 의도라면 1이 아니라 2로 종료해야 합니다.

몇 가지 더 까다로운 점이 있습니다. 종료 코드 2는 Stop조차 차단할 수 있으며, 이것이 Claude에게 아직 끝나지 않았다고 알리는 방법입니다. 하지만 PostToolUse는 도구가 이미 실행된 후에 발생하므로, 거기서 차단하는 것은 호출을 막기에는 이미 늦었지만, 여전히 텍스트를 Claude에게 다시 전달할 수는 있습니다. 그리고 Notification과 SessionStart처럼 차단을 아예 무시하는 이벤트도 몇 가지 있습니다. SessionStart는 표준 에러를 여러분에게만 보여주고, Notification은 이를 무시하며, 둘 다 어쨌든 계속 진행합니다.

실제 가드레일: 차단 대신 삭제하기

실용적인 사례로 이를 정리해 보겠습니다. Bash 도구에 PreToolUse 가드레일을 적용하고 싶다고 해 봅시다. 설정 파일에 훅을 등록합니다. 이것을 .claude/settings.json에 넣고 커밋하면, 팀과 공유할 수 있습니다:

json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/redact-secrets.sh",
            "args": []
          }
        ]
      }
    ]
  }
}

matcher는 감시할 도구를 지정하며, 훅의 선택적 if 필드를 사용하면 "if": "Bash(curl *)"처럼 특정 명령으로 좁힐 수 있습니다. /hooks를 실행해서 훅이 등록되었는지 확인하세요.

가장 자명한 방법은 deny를 반환해 위험한 호출을 막는 것입니다. 그것도 좋습니다. 하지만 덜 알려져 있으면서 더 흥미로운 방법은 updatedInput을 반환해 호출을 다시 작성하는 것입니다. 이것이 단순히 거부하는 대신, 명령에서 비밀 정보를 제거하고도 여전히 실행되도록 하는 방법입니다.

실제로 어떤 모습인지 살펴보겠습니다. Claude가 실제 비밀 정보처럼 보이는 값을 포함한 명령을 실행하라는 요청을 받습니다. 훅이 이를 가로채서 sk_live_ 패턴을 발견하고, 명령이 실행되기 전에 이를 플레이스홀더로 바꿔치기합니다.

스크립트는 다음과 같으며, .claude/hooks/redact-secrets.sh입니다. jq가 필요하며, chmod +x로 실행 권한을 부여해야 합니다:

bash
#!/bin/bash
# 명령이 실행되기 전에 실제 키처럼 보이는 값을 대체합니다.
jq 'if (.tool_input.command // "" | test("sk_live_\\w+")) then {
  hookSpecificOutput: {
    hookEventName: "PreToolUse",
    permissionDecision: "ask",
    permissionDecisionReason: "Replaced a live key with a placeholder",
    updatedInput: (.tool_input | .command |= gsub("sk_live_\\w+"; "REDACTED"))
  }
} else empty end'

이 훅은 ask를 반환하므로, 다시 작성된 명령을 승인하게 됩니다. allow를 반환하면 패턴이 일치하는 모든 명령에 대해 이 프롬프트를 건너뛰게 됩니다. 승인하고 나면 비밀 정보 없이 명령이 실행됩니다. 이것이 차단과 삭제의 차이이며, 훅이 매번 확실하게 강제할 수 있는 종류의 일입니다.

압축 과정에서 상태 보존하기

설정해 둘 만한 패턴이 하나 더 있습니다. Claude가 긴 대화를 압축할 때, 많은 세부 내용이 사라집니다. compact 매처가 달린 SessionStart 훅은 압축 직후에 실행됩니다. 이 훅이 작업 중이던 파일에 대한 간단한 요약을 출력하도록 해 보세요. 그 요약은 다시 컨텍스트로 들어가므로, Claude는 처음부터 다시 시작하는 대신 중단했던 지점에서 이어갈 수 있습니다. 다음 예시는 커밋되지 않은 변경 사항을 나열합니다:

json
{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "compact",
        "hooks": [{ "type": "command", "command": "git status --short" }]
      }
    ]
  }
}

마무리

훅은 Claude가 대체로 따르는 규칙을 항상 따르는 규칙으로 바꿔줍니다. 자동 포맷팅을 넘어서, PreToolUse로 도구를 보호하고, Stop으로 턴을 통제하며, 압축 과정에서 상태를 보존하세요. 설정에는 약간의 초기 노력이 필요하지만, 여러분이 지켜보고 있지 않던 실행 중 무언가를 처음으로 잡아낼 때 그 투자는 충분히 보상받습니다.