Claude Code Hooks 사용법: 코드 작업 자동화하는 방법

Claude Code Hooks는 Claude가 도구를 실행하기 전, 파일을 수정한 뒤, 권한을 요청하거나 작업을 마칠 때 지정한 검사를 자동으로 실행하는 기능입니다. 코드 포맷, 린트, 보호 파일 차단과 알림처럼 매번 반드시 같은 방식으로 처리해야 하는 작업에 적합합니다. 다만 Hook은 사용자의 셸 권한으로 명령을 실행하므로 편리함보다 실행 범위와 실패 동작을 먼저 설계해야 합니다.

Claude Code Hooks란 무엇인가

Hook은 Claude Code의 생명주기에서 정해진 이벤트가 발생하면 사용자 정의 handler를 호출하는 자동화 장치입니다. “필요하면 포맷해줘”라는 프롬프트는 모델의 판단에 의존하지만, PostToolUse Hook은 조건이 맞는 도구 호출이 끝날 때마다 실행됩니다. 반복 실행이 중요한 포맷·검사·감사 기록에는 Hook이 더 예측 가능합니다.

Anthropic 공식 문서 기준 handler는 셸 명령인 command 외에도 HTTP 엔드포인트, 연결된 MCP 도구, 단일 모델 판단인 prompt, 도구를 사용하는 agent 유형을 지원합니다. agent Hook은 실험적 기능이므로 운영 자동화는 단순한 command Hook부터 검증하는 편이 안전합니다.

Hooks와 CLAUDE.md·Skills의 차이

규칙을 설명하려면 CLAUDE.md, 전문적인 작업 순서를 재사용하려면 Claude Skills, 실행 시점을 강제하려면 Hook을 선택하세요. Hook을 보안 경계 하나로만 사용하지 말고 권한 설정과 저장소 보호 규칙을 함께 적용해야 합니다.

가장 많이 쓰는 Hook 이벤트

이벤트 목록과 지원 입력은 업데이트될 수 있습니다. 이름을 기억해서 설정하기보다 공식 Hooks reference와 현재 Claude Code의 /hooks 화면을 함께 확인하세요.

Hook 설정 위치와 적용 범위

팀 전체가 같은 포맷과 검사를 써야 한다면 프로젝트 설정에 두고 코드 리뷰를 받으세요. 개인 알림과 로컬 전용 경로는 사용자 설정이나 local 설정에 두는 편이 적절합니다. 비밀값은 어느 설정 파일에도 직접 적지 말고 승인된 시크릿 관리 방식을 사용해야 합니다.

Hook 설정의 3단계 구조

1. 이벤트: 언제 실행할지 정합니다.
2. matcher 그룹: 어떤 도구나 조건에 반응할지 좁힙니다.
3. handler: 실제 command, HTTP, MCP, prompt 또는 agent 작업을 정의합니다.

matcher가 너무 넓으면 모든 도구 호출에서 무거운 검사가 반복됩니다. 예를 들어 파일 작성 뒤에만 실행하려면 Edit|Write처럼 대상 도구를 제한합니다. 도구의 정확한 이름은 Claude Code Tools reference에서 확인할 수 있습니다.

가장 단순한 PostToolUse Hook 만들기

다음 예시는 Claude가 파일을 작성하거나 수정한 뒤 프로젝트의 포맷 검사를 실행합니다. 프로젝트에 실제로 존재하는 스크립트 이름으로 바꾼 뒤 적용하세요.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "pnpm run format:check",
            "timeout": 60
          }
        ]
      }
    ]
  }
}

포맷 검사를 저장소 전체에 매번 실행하면 대형 프로젝트에서 느려질 수 있습니다. 처음에는 검사 전용 명령으로 동작을 확인하고, 필요하면 Hook의 표준 입력에서 수정된 파일 경로를 안전하게 읽는 프로젝트 스크립트로 최적화하세요. 경로를 그대로 셸 문자열에 이어 붙이면 공백과 특수문자 때문에 오류나 명령 삽입 위험이 생길 수 있습니다.

PreToolUse로 보호 파일 수정 막기

PreToolUse는 도구가 실행되기 전에 입력을 확인할 수 있어 배포 설정, 마이그레이션과 비밀 파일 보호에 사용할 수 있습니다. 복잡한 검증 로직은 JSON 안의 긴 한 줄 명령보다 저장소에서 리뷰할 수 있는 별도 스크립트로 관리하세요.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/guard-protected-files.sh",
            "args": [],
            "timeout": 10
          }
        ]
      }
    ]
  }
}

스크립트는 표준 입력으로 전달된 JSON에서 파일 경로를 읽고, 프로젝트 루트 기준으로 정규화한 뒤 허용 범위를 판정해야 합니다. 심볼릭 링크, 대소문자와 상위 경로 이동도 고려하세요. 단순 문자열 포함 검사만으로 보안 통제를 완성했다고 판단하면 안 됩니다.

알림 Hook으로 승인 대기 놓치지 않기

Notification Hook은 Claude Code가 권한이나 추가 입력을 기다리는 시점에 알림을 보낼 때 유용합니다. macOS의 osascript, Linux의 데스크톱 알림 도구, Windows PowerShell처럼 운영체제마다 명령이 다르므로 팀 공용 설정에 특정 운영체제 명령을 바로 넣지 마세요.

알림에는 소스코드, 프롬프트 전문, 토큰이나 고객 정보를 포함하지 않는 것이 좋습니다. 외부 웹훅을 쓴다면 허용된 목적지, 인증 방식, 재시도와 로그 보존 정책을 먼저 확인하세요.

Stop Hook으로 완료 조건 확인하기

작업이 끝나기 전에 테스트나 산출물 존재를 확인하려면 Stop Hook을 사용할 수 있습니다. 단순 파일·명령 판정은 command Hook이 적합하고, 상태를 읽고 판단해야 한다면 prompt 또는 실험적인 agent Hook을 고려할 수 있습니다.

Stop Hook이 계속 실패하면 Claude가 종료를 반복해서 시도할 수 있습니다. 검사에 명확한 성공 조건, 제한 시간과 탈출 조건을 두고 사용자 취소를 막지 않도록 설계하세요. 전체 테스트가 긴 저장소라면 매 종료마다 모두 실행하기보다 변경 범위 검사와 CI를 나누는 편이 현실적입니다.

command·prompt·agent·HTTP·MCP 선택법

입력 JSON과 종료 코드 이해하기

command Hook은 이벤트 정보를 표준 입력의 JSON으로 받고 종료 코드, 표준 출력과 표준 오류로 결과를 전달합니다. 공식 reference에 따르면 종료 코드만 사용하는 방식과 종료 코드 0에서 구조화 JSON을 출력하는 방식을 섞지 않는 것이 중요합니다. 종료 코드 2를 쓰면 JSON 출력은 무시됩니다.

구조화 JSON을 반환할 때 표준 출력에는 JSON 객체만 있어야 합니다. 셸 초기화 파일이나 검사 도구가 안내 문구를 출력하면 파싱 오류가 날 수 있으므로 진단 메시지는 표준 오류 또는 별도 로그로 분리하세요. Hook 출력은 Claude의 문맥에 들어갈 수 있으므로 비밀값과 불필요한 대용량 로그도 제거해야 합니다.

/hooks에서 설정 확인하기

1. Claude Code에서 /hooks를 입력합니다.
2. 설정한 이벤트 옆의 Hook 개수를 확인합니다.
3. 항목을 열어 matcher, handler 유형과 출처 파일을 확인합니다.
4. 읽기 전용 테스트 프로젝트에서 대상 이벤트를 한 번 발생시킵니다.
5. 예상 명령이 한 번만 실행되는지와 실패 메시지를 기록합니다.

/hooks 화면은 현재 설정을 확인하는 읽기 전용 브라우저입니다. 추가·수정·삭제는 설정 JSON을 편집하거나 Claude에게 설정 변경을 요청해야 합니다. 변경 후 목록에 보이지 않으면 JSON 문법과 파일 위치부터 확인하세요.

Hook이 실행되지 않을 때 확인할 것

보안 사고를 줄이는 체크리스트

• 저장소의 Hook 설정과 스크립트를 일반 코드처럼 리뷰합니다.
• 외부 프로젝트를 열기 전에 .claude/settings.json과 실행 스크립트를 확인합니다.
• 사용자 입력과 파일 경로를 셸 명령에 직접 연결하지 않습니다.
• 비밀값은 설정과 출력에 기록하지 않고 최소 권한으로 전달합니다.
• 네트워크 전송 Hook은 목적지 허용 목록, 인증과 보존 정책을 적용합니다.
• 삭제, 배포와 운영 데이터 변경은 Hook만 믿지 않고 별도 권한과 사람 승인을 둡니다.
• 검사 실패 시 무조건 통과시키지 말고 사용자에게 원인과 다음 행동을 보여줍니다.
• disableAllHooks가 조직 관리형 Hook까지 해제한다고 가정하지 않습니다.

Anthropic 권한 문서상 PreToolUse Hook의 허용 결과가 기존 deny·ask 권한 규칙을 우회하지는 않습니다. 반대로 차단 Hook은 allow 규칙보다 먼저 작업을 막을 수 있습니다. 두 체계를 따로 검토해야 예상치 못한 허용과 영구 차단을 줄일 수 있습니다.

팀에 도입하는 5단계

1. 반복 비용이 크고 판정이 명확한 작업 하나를 고릅니다.
2. 개인 local 설정에서 읽기·검사 전용 Hook으로 시작합니다.
3. 정상 파일, 보호 파일, 공백이 있는 경로와 실패 명령을 시험합니다.
4. 실행 시간, 오탐, 누락과 개발자가 우회한 횟수를 기록합니다.
5. 효과가 확인된 설정과 스크립트만 프로젝트 설정으로 옮겨 리뷰합니다.

Hooks 자동화 품질을 측정하는 방법

“자동화했으니 좋아졌다”는 평가보다 실제 오류를 얼마나 일찍 발견했고 개발 시간을 얼마나 방해했는지 함께 측정해야 합니다. 이 글에서는 특정 절감률이나 성능 수치를 직접 측정하지 않았으므로 팀 환경에서 자체 기록을 남겨 판단하세요.

직접 검증 기록표

Hook은 설정 화면보다 실제 이벤트에서 검증해야 합니다. 다음 항목을 한 줄씩 기록하면 matcher 오류와 과도한 자동화를 구분하기 쉽습니다.

편집부 결론

Claude Code Hooks는 포맷, 검사, 보호 파일 차단과 알림을 모델의 선택이 아니라 정해진 시점에 실행하도록 만드는 기능입니다. 처음에는 PostToolUse의 가벼운 검사 하나로 시작하고 /hooks에서 실제 로드 위치와 matcher를 확인하세요. 운영 데이터와 배포를 다루는 자동화는 최소 권한, 별도 승인, 시간 제한과 실패 복구 절차를 함께 설계해야 합니다.

이 글은 2026년 9월 6일 Anthropic 공식 문서를 분석해 작성했으며 특정 조직 저장소에서 Hooks의 장기 효과를 직접 측정한 후기는 아닙니다. Claude Code의 이벤트와 handler 유형은 변경될 수 있으므로 적용 직전 공식 reference와 현재 버전을 확인하세요.

공식 문서와 함께 읽을 글

Claude Code Hooks 시작 가이드 확인하기

Hooks 이벤트·입출력 공식 레퍼런스 보기

Claude Code 권한과 Hook 우선순위 확인하기

Claude Code Hooks와 MCP를 연동해 외부 도구 검사하기

Agent Teams의 Task 완료 조건을 Hook으로 검증하기

CLAUDE.md 지침과 강제 실행 Hook 구분하기

Hooks·Skills·MCP를 Claude Code Plugin으로 통합하기

Claude Code Skills로 반복 프롬프트 만들기

Claude Code MCP 외부 도구 호출 연결하기

Claude Code Subagent로 개발 작업 병렬 처리하기

Claude Skills로 반복 업무 절차 만들기

Codex와 Claude Code 개발 흐름 비교하기

Codex AGENTS.md 프로젝트 규칙과 비교하기

AI 코드리뷰 결과를 검증하고 PR에 적용하기

자주 묻는 질문

Claude Code Hooks는 무엇을 자동화할 수 있나요?

파일 수정 후 포맷·린트, 도구 실행 전 위험 작업 차단, 권한 요청 알림, 세션 시작 문맥 준비와 작업 종료 전 완료 조건 확인 등을 자동화할 수 있습니다.

Claude Code Hook은 어디에 설정하나요?

모든 프로젝트에 적용하려면 ~/.claude/settings.json, 팀과 공유할 프로젝트 설정은 .claude/settings.json, 개인 프로젝트 설정은 .claude/settings.local.json에 정의합니다.

파일 수정 후 자동 포맷에는 어떤 이벤트를 쓰나요?

PostToolUse 이벤트에 Edit|Write matcher를 적용할 수 있습니다. 저장소 전체 검사 비용이 크면 수정된 파일만 안전하게 처리하는 별도 스크립트를 사용하세요.

위험한 명령을 실행 전에 막을 수 있나요?

PreToolUse Hook에서 도구 입력을 검사해 차단할 수 있습니다. Hook 하나만 보안 경계로 믿지 말고 deny 권한, 브랜치 보호와 사람 승인을 함께 사용해야 합니다.

설정한 Hook은 어떻게 확인하나요?

Claude Code에서 /hooks를 열면 이벤트별 개수, matcher, handler 유형, 출처 파일과 명령을 확인할 수 있습니다. 이 화면은 읽기 전용입니다.

Hook과 Claude Skills는 무엇이 다른가요?

Skills는 Claude가 업무에 맞춰 불러오는 재사용 절차이고, Hooks는 특정 생명주기 이벤트에서 자동 실행되는 handler입니다. 작업 지식은 Skill, 반드시 실행할 기계적 검사는 Hook에 두는 방식이 적합합니다.

Claude Code Hooks가 실행되지 않는 이유는 무엇인가요?

설정 파일 위치, JSON 문법, 이벤트 이름, matcher와 실제 도구 이름, PATH와 스크립트 실행 권한을 확인하세요. /hooks에 표시되는 Source가 예상 위치와 같은지도 봐야 합니다.

외부 프로젝트의 Hook을 그대로 실행해도 안전한가요?

안전하다고 가정하면 안 됩니다. Hook은 사용자 권한으로 명령을 실행할 수 있으므로 설정, 스크립트, 네트워크 목적지와 비밀정보 접근을 먼저 검토하고 격리된 환경에서 시험하세요.