Claude Code 훅: 도구 호출 앞뒤에 규칙 걸기

훅이란

훅(hook) 은 Claude Code가 일하는 특정 시점에 자동으로 실행되는 사용자 명령이다. CLAUDE.md에 「수정 후엔 포맷터를 돌려라」라고 적는 것은 부탁이라 모델이 잊을 수 있다. 훅은 모델의 판단과 무관하게 항상 실행된다. 반드시 지켜야 하는 규칙은 훅으로, 판단이 필요한 지침은 CLAUDE.md로 나눈다.

주요 이벤트

이 밖에도 도구 묶음이 끝난 뒤(PostToolBatch), 프롬프트 확장(UserPromptExpansion), 응답 실패(StopFailure), 작업 디렉터리 변경(CwdChanged), 파일 변경 감시(FileChanged), 워크트리 생성·삭제(WorktreeCreate·WorktreeRemove), 권한 거부(PermissionDenied), 작업 생성(TaskCreated), MCP 입력 요청(Elicitation) 같은 이벤트가 있다(v2.1.322 기준 30개가 넘는다). 핸들러는 셸 명령 말고도 HTTP 요청과 MCP 도구 호출이 될 수 있다. 전체 목록은 공식 문서에 있다.

설정

훅은 설정 파일의 hooks 아래에 이벤트 → matcher 묶음 → 실행할 핸들러 세 단계로 적는다. 직접 편집하거나 /hooks 명령으로 추가한다.

• matcher: 도구 이벤트에서는 도구 이름을 거른다. Read|Grep처럼 |로 여러 개, mcp__playwright__.*처럼 정규식, *나 생략이면 전부다.
• 핸들러 종류: 셸 명령(command)이 기본이다. JSON을 URL로 보내는 http, MCP 도구를 부르는 mcp_tool, 모델에게 한 번 판단을 맡기는 prompt도 있다.
• 경로는 ${CLAUDE_PROJECT_DIR}로 프로젝트 기준 절대 경로를 쓰고, 인자는 args로 넘기면 따옴표·공백 문제가 없다.

입력과 종료 코드

훅 명령은 표준 입력으로 JSON을 받는다. PreToolUse라면 어떤 도구를 어떤 인자로 부르려는지가 들어 있다.

{
  "session_id": "2d6a1e4d-6...",
  "transcript_path": "/Users/sg/...",
  "hook_event_name": "PreToolUse",
  "tool_name": "Read",
  "tool_input": { "file_path": "/code/queries/.env" }
}

더 세밀하게 제어하려면 종료 코드 0과 함께 JSON을 출력한다. 예를 들어 PreToolUse에서 hookSpecificOutput.permissionDecision을 "deny"로 주면 이유와 함께 막고, additionalContext로 Claude에게 참고 정보를 더할 수 있다.

예제: .env 파일 읽기 막기

Claude가 .env를 읽지 못하게 하려면 PreToolUse에서 Read와 Grep을 감시한다. 개인용이라면 .claude/settings.local.json에 둔다.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Read|Grep",
        "hooks": [
          { "type": "command", "command": "node \"${CLAUDE_PROJECT_DIR}/hooks/read_hook.js\"" }
        ]
      }
    ]
  }
}

// hooks/read_hook.js
async function main() {
  const chunks = [];
  for await (const chunk of process.stdin) chunks.push(chunk);
  const toolArgs = JSON.parse(Buffer.concat(chunks).toString());
 
  // Claude가 읽으려는 경로
  const readPath = toolArgs.tool_input?.file_path || toolArgs.tool_input?.path || "";
 
  if (readPath.includes(".env")) {
    console.error("You cannot read the .env file");
    process.exit(2); // 막고, stderr를 이유로 전달
  }
}
main();

단순한 경로 차단은 훅 대신 권한 규칙(permissions.deny에 Read(./.env))으로도 걸 수 있다. 공식 문서도 확실한 허용·차단은 권한 체계에 맡기고, 훅은 판단 로직이 필요한 곳에 쓰라고 권한다.

유용한 훅

훅이라는 기능 자체가 「권한 요청이 떴는데 자리를 비워서 몰랐다, Slack으로 알려 달라」 같은 요청에 통합 기능을 하나씩 만드는 대신 열어 둔 확장점이다.

예: 큰 파일 읽기를 싼 모델로 돌려 토큰 줄이기

파일을 통째로 읽거나 테스트·설정·타입 스텁 같은 정형 코드를 쓰는 일은 토큰은 많이 들지만 판단은 적게 든다. 이런 I/O성 작업을 저비용 모델에 넘기고 메인 모델은 추론에만 쓰면 토큰이 크게 준다. Spotify 사내 실험에서는 큰 파일 읽기를 위임해 읽기 토큰을 평균 약 90% 줄였다.

• CLAUDE.md 규칙만으로는 지켜지지 않는다. 「큰 파일은 위임하라」는 지시는 권고라서 모델이 자주 건너뛴다. 훅이 막아야 스킬을 무시해도 비싼 읽기가 일어나지 않는다. 훅을 플러그인으로 묶으면 프로젝트마다 규칙을 복사하지 않아도 된다.
• 편집과 추론은 위임하지 않는다. 요약에는 정확한 줄 번호가 없으니 고칠 부분은 메인 모델이 직접 읽는다. 저비용 모델은 미묘한 동시성 버그 같은 것을 놓치므로 디버깅, 설계 판단, 안전에 중요한 코드는 메인 모델이 맡는다.
• 작은 파일은 직접 읽는 편이 빠르다. 위임 한 번에 10~30초가 걸리므로 임계값 아래는 그냥 읽게 둔다.

주의점

보안

훅은 내 사용자 권한 그대로 실행된다. 남이 만든 저장소의 프로젝트 훅은 실행 전에 내용을 확인한다.

• 입력 JSON을 믿지 말고 검증한다.
• 셸 변수는 항상 따옴표로 감싼다($VAR가 아니라 "$VAR").
• 경로에 ..가 있는지 확인해 경로 순회를 막는다.
• 스크립트는 절대 경로로 지정한다. 경로 가로채기·바이너리 심기 공격을 줄인다.
• .env, .git/, 키 파일 같은 민감한 파일은 건너뛴다.
• 훅이 시간 초과되면 기본적으로 작업이 그대로 진행된다(fail-open). 막는 용도라면 onFailure: "block"을 준다.

절대 경로와 공유의 충돌

절대 경로는 머신마다 달라 설정 파일을 공유하기 어렵다. ${CLAUDE_PROJECT_DIR} 변수로 프로젝트 기준 절대 경로를 만들면 같은 설정을 팀이 그대로 쓴다. 과거에는 자리표시자를 넣은 예제 설정을 커밋하고 초기화 스크립트로 머신별 경로를 채워 넣었다.

입력 형식 확인하기

표준 입력의 모양은 이벤트마다, tool_input은 도구마다 다르다. 훅을 짜기 전에 실제 입력을 파일로 떨궈 본다.

"PostToolUse": [
  { "matcher": "*", "hooks": [ { "type": "command", "command": "jq . > post-log.json" } ] }
]

정리

• 훅은 모델에게 부탁하는 대신 시스템이 항상 실행하는 규칙이다.
• PreToolUse는 막을 수 있고, PostToolUse는 결과를 보고 피드백을 준다.
• 표준 입력으로 JSON을 받고, 종료 코드 2와 stderr로 막고 이유를 전한다.
• 타입 검사·포맷터·민감 파일 차단처럼 확인 가능한 규칙에 쓴다. 단순 차단은 권한 규칙으로도 된다.
• CLAUDE.md의 권고를 강제 규칙으로 바꿀 때도 훅을 쓴다. 큰 파일 읽기를 막고 저비용 모델로 돌리면 토큰이 크게 준다.
• 훅은 내 권한으로 돈다. 입력 검증, 절대 경로, 따옴표를 지킨다.

관련 노트: Claude Code 활용 가이드, Claude Code 설정과 권한 규칙, Claude Code 실전 팁, AI 코딩 실무 가드레일, 프롬프트에서 하네스로, 내 일을 줄이는 하네스 만들기