훅스

Claude Code의 전체 라이프사이클을 위한 이벤트 기반 자동화

훅스란?

훅은 Claude Code의 특정 이벤트에 응답하여 실행되는 스크립트 또는 프롬프트입니다. 네 가지 유형을 지원합니다: command(셸 스크립트), HTTP(웹훅 호출), prompt(LLM 기반 결정), agent(서브에이전트 검증). 정책 적용, 워크플로우 자동화, 외부 도구 통합에 사용하세요.

이벤트 기반

20개 이상의 라이프사이클 이벤트에 자동 응답

네 가지 훅 유형

각기 다른 필요에 맞는 Command, HTTP, Prompt, Agent 훅

정책 적용

팀 표준, 보안 정책, 코드 품질 규칙 적용

외부 통합

웹훅 호출, 스크립트 실행, 외부 서비스 연결

사용 가능한 훅 이벤트 (20개 이상)

PreToolUse

Claude가 도구를 사용하기 전에 실행됩니다. 도구 사용을 검증, 수정, 또는 차단합니다.

활용 사례: 보안 검증, 파일 보호

PostToolUse

도구가 성공적으로 완료된 후 실행됩니다. 결과를 처리하고 알림을 트리거합니다.

활용 사례: 자동 포맷팅, 로깅, 메트릭

UserPromptSubmit

사용자가 프롬프트를 제출할 때 실행됩니다. 프롬프트를 수정, 보강, 또는 가로챕니다.

활용 사례: 컨텍스트 주입, 프롬프트 향상

Notification

Claude가 알림을 보낼 때 실행됩니다. 알림 동작을 커스터마이즈합니다.

활용 사례: 커스텀 알림, 팀 알림

SessionStart

Claude 세션이 시작될 때 실행됩니다. 리소스를 초기화하고, 환경을 확인하고, 컨텍스트를 로드합니다.

활용 사례: 환경 설정, 의존성 확인

SessionEnd

세션이 종료될 때 실행됩니다. 리소스를 정리하고, 상태를 저장하고, 보고서를 생성합니다.

활용 사례: 정리, 분석, 세션 요약
NEW

Setup

--init, --init-only, 또는 --maintenance 플래그로 트리거됩니다. 리포지토리 설정과 유지 보수용.

활용 사례: 환경 설정, 의존성 확인, 프로젝트 초기화
NEW

SubagentStop

서브에이전트가 완료될 때 실행됩니다. 결과를 처리하고, 작업을 연결하고, 알림을 보냅니다.

활용 사례: 결과 처리, 작업 체이닝
NEW

SubagentStart

서브에이전트가 시작하려 할 때 실행됩니다. 모니터링, 컨텍스트 주입, 또는 차단.

활용 사례: 서브에이전트 모니터링, 컨텍스트 주입
NEW

PermissionRequest

권한이 요청될 때 실행됩니다. 자동 승인, 거부, 또는 요청을 로깅합니다.

활용 사례: 자동 승인 정책, 감사 로깅
NEW

PreCompact

컨텍스트 압축 전에 실행됩니다. 압축 전에 중요한 정보를 저장합니다.

활용 사례: 컨텍스트 보존, 중요 데이터 백업
NEW FEATURE

프롬프트 기반 훅

훅에서 LLM 기반 의사 결정을 사용하세요. 코드를 작성하는 대신 원하는 것을 자연어로 설명합니다. LLM이 조건을 평가하고 구조화된 결정을 반환합니다.

.claude/settings.json
{
  "hooks": {
    "PreToolUse": [
      {
        "type": "prompt",
        "matcher": { "tool": "Write" },
        "prompt": "Review this file write operation. Check if it follows 
                   our coding standards. Respond with 'allow' or 'deny' 
                   and explain why."
      }
    ]
  }
}

사용 시점

  • +코드로 작성하기 어려운 복잡한 결정 로직
  • +코드 리뷰 및 품질 검사
  • +컨텍스트 인식 검증

응답 형식

{
  "decision": "allow" | "deny" | "skip",
  "reason": "Optional explanation",
  "modifiedInput": { /* optional */ }
}

실전 예제

편집 후 코드 자동 포맷팅

Claude가 파일을 편집한 후 자동으로 Prettier를 실행

hooks/post-tool-use.js
// Auto-format files after Edit tool
export async function postToolUse({ tool, result }) {
  if (tool.name === 'Edit' && result.success) {
    const { execSync } = require('child_process');
    try {
      execSync(`prettier --write "${tool.params.file_path}"`);
      console.log('✓ Formatted', tool.params.file_path);
    } catch (error) {
      console.error('Format failed:', error.message);
    }
  }
}

민감한 파일 보호

Claude가 중요한 설정 파일을 편집하지 못하도록 방지

hooks/pre-tool-use.js
// Protect sensitive files
export async function preToolUse({ tool }) {
  const protectedFiles = [
    '.env',
    'credentials.json',
    'package-lock.json'
  ];

  if (['Edit', 'Write'].includes(tool.name)) {
    const filePath = tool.params.file_path;
    if (protectedFiles.some(f => filePath.includes(f))) {
      return {
        allow: false,
        reason: `Cannot modify protected file: ${filePath}`
      };
    }
  }

  return { allow: true };
}

HTTP 훅으로 Slack 알림 전송

배포가 발생할 때 웹훅을 호출

hooks/post-tool-use.js
// Notify team on deployment
export async function postToolUse({ tool, result }) {
  if (tool.name === 'Bash' &&
      tool.params.command.includes('deploy')) {
    const webhook = process.env.SLACK_WEBHOOK;
    await fetch(webhook, {
      method: 'POST',
      body: JSON.stringify({
        text: `🚀 Deployment completed!
Success: ${result.success}
Command: ${tool.params.command}`
      })
    });
  }
}

보안 고려사항

훅은 시스템에서 코드를 실행합니다. 다음 보안 모범 사례를 따르세요:

⚠

훅 파일에 시크릿을 저장하지 마세요 — 환경 변수를 사용하세요

⚠

외부 명령을 실행하기 전에 모든 입력을 검증하세요

⚠

외부 소스의 훅을 사용하기 전에 검토하세요

⚠

에러를 우아하게 처리하기 위해 try-catch 블록을 사용하세요

모범 사례

1

훅을 단순하게 유지

각 훅은 한 가지 일을 잘 수행해야 합니다. 복잡한 로직은 Claude를 느리게 만들 수 있습니다.

2

에러를 우아하게 처리

항상 try-catch 블록을 사용하고 의미 있는 에러 메시지를 제공하세요.

3

비동기 훅 사용

훅은 외부 API 호출 및 장시간 실행 작업을 위한 비동기 실행을 지원합니다.

4

훅 테스트

/hooks 명령어로 훅을 인터랙티브하게 탐색하고 테스트하세요.

워크플로우를 자동화할 준비가 되셨나요?

표준을 적용하고, 작업을 자동화하고, 외부 도구를 통합하는 훅을 만들기 시작하세요.

시작하기플러그인