Claude Code Hooks 완전 정복: 자동 포맷팅, 자동 테스트 설정법

Hooks란?

Claude Code Hooks를 사용하면 특정 작업 전후에 사용자 정의 명령어를 자동으로 실행할 수 있습니다. 파일 저장 후 자동 포맷팅, 코드 변경 후 자동 테스트 실행 등 다양한 자동화가 가능합니다.

Hooks는 .claude/settings.json에 정의하며, Claude Code가 특정 작업을 수행할 때 셸 명령어가 실행됩니다.

Hook 유형

Claude Code는 다음 이벤트 시점에서 Hooks를 지원합니다:

Hook 이벤트	실행 시점
PreToolUse	도구 실행 전
PostToolUse	도구 실행 후
Notification	알림 발송 시
Stop	Claude Code가 응답을 완료했을 때

기본 설정

Hooks는 .claude/settings.json의 hooks 필드에 정의합니다:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "npx prettier --write \"$CLAUDE_FILE_PATH\""
      }
    ]
  }
}

설정 구조

• matcher: Hook을 트리거할 도구 이름과 매칭되는 정규식 패턴
• command: 실행할 셸 명령어

활용 사례 1: 자동 포맷팅

파일 편집 후 자동으로 Prettier를 실행합니다:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "npx prettier --write \"$CLAUDE_FILE_PATH\""
      }
    ]
  }
}

이렇게 설정하면 Claude Code가 파일을 생성하거나 편집할 때마다 Prettier가 자동으로 포맷팅합니다. 수동 작업 없이 팀의 코딩 스타일을 일관되게 유지할 수 있습니다.

활용 사례 2: 자동 린팅

ESLint 자동 수정을 연동하는 방법입니다:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "npx eslint --fix \"$CLAUDE_FILE_PATH\" 2>/dev/null || true"
      }
    ]
  }
}

끝에 붙은 || true는 린트 에러로 인해 Hook이 실패하는 것을 방지하여 Claude Code가 계속 작업할 수 있게 합니다.

활용 사례 3: 변경 시 자동 테스트

파일 편집 후 관련 테스트를 자동으로 실행하고 결과를 피드백합니다:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "npx vitest related \"$CLAUDE_FILE_PATH\" --run 2>&1 | tail -20"
      }
    ]
  }
}

Vitest의 related 옵션은 변경된 파일과 관련된 테스트만 실행하므로 전체 테스트 스위트보다 훨씬 빠른 피드백을 받을 수 있습니다.

활용 사례 4: 자동 타입 체크

파일 변경 후 TypeScript 타입 검사를 실행합니다:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "npx tsc --noEmit 2>&1 | head -30"
      }
    ]
  }
}

활용 사례 5: 위험한 명령어 차단

위험한 명령어의 실행을 방지하는 PreToolUse Hook입니다:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "command": "if echo \"$CLAUDE_TOOL_INPUT\" | grep -qE 'rm -rf|drop table|git push.*force'; then echo 'BLOCKED: Dangerous command detected' >&2; exit 1; fi"
      }
    ]
  }
}

Hook이 종료 코드 1로 끝나면 Claude Code는 해당 도구 실행을 건너뜁니다.

활용 사례 6: 완료 알림

Claude Code가 작업을 완료했을 때 알림을 보냅니다:

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "command": "notify-send 'Claude Code' 'Task completed' 2>/dev/null; echo 'Done'"
      }
    ]
  }
}

macOS에서는 다음과 같이 사용할 수 있습니다:

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "command": "osascript -e 'display notification \"Task completed\" with title \"Claude Code\"'"
      }
    ]
  }
}

여러 Hooks 조합하기

실제 프로젝트에서는 여러 Hooks를 조합하는 것이 가장 효과적입니다:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "command": "if echo \"$CLAUDE_TOOL_INPUT\" | grep -qE 'rm -rf /'; then exit 1; fi"
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "npx prettier --write \"$CLAUDE_FILE_PATH\" 2>/dev/null || true"
      },
      {
        "matcher": "Write|Edit",
        "command": "npx eslint --fix \"$CLAUDE_FILE_PATH\" 2>/dev/null || true"
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "command": "echo '✓ Task completed'"
      }
    ]
  }
}

Hooks 작성 팁

1. 실행 시간을 짧게 유지하세요

Hooks는 동기적으로 실행되므로 무거운 작업은 Claude Code의 응답 속도를 저하시킵니다. related 옵션으로 테스트 범위를 좁히고, head나 tail로 출력을 제한하세요.

2. 에러를 우아하게 처리하세요

에러로 종료되는 Hook은 Claude Code의 워크플로를 중단시킬 수 있습니다. || true와 2>/dev/null을 활용하여 안전하게 처리하세요.

3. 환경 변수를 활용하세요

Hooks에서 사용할 수 있는 환경 변수를 적극 활용하세요. $CLAUDE_FILE_PATH로 현재 작업 중인 파일의 경로를 가져올 수 있습니다.

결론

Hooks를 활용하면 Claude Code의 워크플로를 원하는 대로 커스터마이징할 수 있습니다. 특히 자동 포맷팅과 자동 테스트의 조합은 코드 품질 유지에 매우 효과적입니다. Prettier 자동 포맷팅부터 시작해서 점진적으로 확장해 나가세요.