Claude Code 훅(Hooks) 고도화 — 실행 시간 측정·노력 감지·CI 자동 리뷰까지

훅(Hook)은 Claude Code에서 가장 조용하게, 하지만 가장 강력하게 성장하고 있는 기능이다.

훅은 Claude Code가 어떤 도구를 실행하기 전/후에 사용자가 정의한 쉘 명령어를 자동으로 실행하는 구조다. 코드를 저장할 때마다 자동으로 린터를 돌리거나, 파일을 수정할 때 로그를 기록하거나, 특정 조건에서 알림을 보내는 것이 모두 훅으로 가능하다.

2026년 5월 Claude Code가 업데이트하면서 이 훅 시스템에 세 가지 중요한 기능이 추가됐다.

훅이란 무엇인가 — 30초 이해

PostToolUse 출력 교체 — 어떤 도구든 가로챌 수 있다

이전에는 MCP 도구에 한해서만 hookSpecificOutput.updatedToolOutput을 통해 도구의 출력 결과를 훅이 교체할 수 있었다. 이번 업데이트로 모든 도구에서 가능해졌다.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 sanitize_output.py",
            "hookSpecificOutput": {
              "updatedToolOutput": true
            }
          }
        ]
      }
    ]
  }
}

민감한 정보(API 키, 비밀번호)를 자동으로 마스킹하거나, 오류 메시지를 사람이 읽기 좋은 형태로 변환하는 데 쓸 수 있다.

effort.level — 노력 레벨을 훅이 읽는다

훅 내부에서 두 가지 방법으로 현재 노력 레벨을 읽을 수 있다.

• 훅 입력 JSON: effort.level 필드
• 환경 변수: $CLAUDE_EFFORT

#!/bin/bash
if [ "$CLAUDE_EFFORT" = "high" ] || [ "$CLAUDE_EFFORT" = "xhigh" ]; then
  npm run test:full
else
  npm run test:smoke
fi

duration_ms — 도구 실행 시간 측정

PostToolUse와 PostToolUseFailure 훅 입력에 duration_ms 필드가 추가됐다. 순수한 도구 실행 시간(밀리초)만 측정된다.

#!/bin/bash
DURATION=$1
if [ "$DURATION" -gt 5000 ]; then
  echo "[SLOW] $(date): ${DURATION}ms - $TOOL_NAME" >> slow-tools.log
fi

claude ultrareview — CI에서 코드 리뷰 자동화

기존의 /ultrareview는 대화식으로만 실행할 수 있었다. 이제는 비대화형 방식으로 CI/CD 파이프라인에서 직접 호출할 수 있다.

claude ultrareview src/
claude ultrareview src/ --json
claude ultrareview --diff origin/main...HEAD

종료 코드: 0 (완료) / 1 (실패)

auto mode 하드 거부 규칙

하드 거부 규칙으로 지정한 동작은 allow 예외와 관계없이 무조건 차단된다.

활용 팁

1. duration_ms로 느린 작업부터 파악하라 2. effort.level을 활용해 리소스를 아껴라 3. PostToolUse 출력 교체는 보안 레이어로 쓰라 4. claude ultrareview를 PR 체크리스트 첫 번째로

출처 (Sources)

• Anthropic, "Claude Code Changelog — May 2026": https://code.claude.com/docs/en/changelog
• Releasebot, "Claude Code Updates by Anthropic – May 2026": https://releasebot.io/updates/anthropic/claude-code
• Simon Willison, "Live blog: Code w/ Claude 2026": https://simonwillison.net/2026/May/6/code-w-claude-2026/
• ClaudeFast, "Claude Code Changelog: All Release Notes (2026)": https://claudefa.st/blog/guide/changelog