Claudxk 가이드 - AI 코딩 어시스턴트 시작하기

Hooks (이벤트 훅)

Claude가 뭔가 할 때마다 자동으로 추가 작업을 실행시킬 수 있어요.

Hooks란?

Hooks는 Claude가 뭔가를 할 때 자동으로 추가 작업을 실행시키는 기능이에요. 예를 들어 파일을 저장할 때마다 자동으로 코드 정리를 하거나, 저장 전에 검사를 하는 식으로 쓸 수 있어요.

자동 실행

따로 시키지 않아도 알아서 동작해요.

조건 지정

특정 동작(파일 저장, 명령어 실행 등)에만 적용할 수 있어요.

품질 보호

코드 검사, 보안 확인 등을 자동으로 해줘요.

간단한 설정

설정 파일 하나만 수정하면 돼요.

이벤트 종류

Hooks는 아래와 같은 상황에서 동작해요. 상황마다 실행되는 타이밍이 달라요.

이벤트	실행 시점	주요 용도
`SessionStart`	세션 시작/재개 시	초기 컨텍스트 주입
`UserPromptSubmit`	프롬프트 제출 직후	입력 검증, 변환
`PreToolUse`	도구 실행 직전	코드 검사, 차단
`PostToolUse`	도구 실행 직후	코드 정리, 기록
`Notification`	알림 발생 시	커스텀 알림
`Stop`	Claude 응답 완료 시	결과 정리, 검증
`SubagentStart/Stop`	서브에이전트 시작/종료	서브에이전트 모니터링
`PreCompact`	컨텍스트 압축 전	압축 전 정보 저장
`ConfigChange`	설정 파일 변경 시	변경 감사 로그
`SessionEnd`	세션 종료 시	정리, 보고

팁: 가장 많이 쓰이는 건 PreToolUse(작업 전)와 PostToolUse(작업 후)예요. 파일 저장 전에 검사하고, 저장 후에 정리하는 식으로 많이 써요.

설정 위치

Hooks는 settings.json 파일에 적어요. 내 컴퓨터 전체용과 프로젝트용 두 곳이 있어요.

구분	경로	범위
개인 설정	`~/.claude/settings.json`	내 컴퓨터 전체
프로젝트 설정	`.claude/settings.json`	해당 프로젝트만

Hook 타입

Hook은 4가지 타입을 지원해요. command 외에도 LLM 기반 훅을 쓸 수 있어요.

타입	동작	용도
`command`	셸 명령어 실행	포맷팅, 파일 보호, 알림
`http`	HTTP POST 요청	외부 서비스 연동, 웹훅
`prompt`	LLM 단일 판단 (Haiku)	작업 완료 여부 판단
`agent`	LLM + 도구 사용	테스트 실행 후 검증

팁: prompt와 agent 타입은 규칙 기반 판단이 어려운 경우에 써요. 예: "모든 작업이 완료됐는지 확인" 같은 판단이 필요할 때.

Hook 구조

settings.json 파일 안에 아래처럼 적어요.matcher는 "어떤 동작일 때", command는 "뭘 실행할지"를 뜻해요.

settings.json 기본 구조

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "echo '파일 저장 전 실행됩니다'"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "echo '파일 저장 후 실행됩니다'"
          }
        ]
      }
    ]
  }
}

필드	설명
`matcher`	어떤 동작에 반응할지 (예: `Write`=파일 저장, `Bash`=명령어 실행)
`hooks`	실행할 명령 배열
`type`	항상 `"command"`
`command`	실행할 명령어 (터미널에서 실행되는 명령)

실전 예시

예시 1: 커밋 전 린트 검사

Bash에서 git commit 명령이 실행되기 전에 ESLint로 코드를 검사합니다.

.claude/settings.json

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "if echo '$TOOL_INPUT' | grep -q 'git commit'; then npx eslint . --max-warnings 0; fi"
          }
        ]
      }
    ]
  }
}

검사에 실패하면 작업이 자동으로 중단돼요. 실수를 미리 막아주는 거예요.

예시 2: 파일 저장 후 자동 포맷팅

Claude가 파일을 작성한 후 Prettier로 자동 포맷팅합니다.

.claude/settings.json

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write '$TOOL_INPUT_FILE_PATH'"
          }
        ]
      }
    ]
  }
}

$TOOL_INPUT_FILE_PATH는 저장된 파일 경로로 자동 치환됩니다.

예시 3: 커스텀 알림 소리

Claude의 응답이 완료되면 알림 소리를 재생합니다.

~/.claude/settings.json

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "afplay /System/Library/Sounds/Glass.aiff"
          }
        ]
      }
    ]
  }
}

macOS 기본 사운드를 사용합니다. matcher를 비워두면 모든 알림에 반응합니다.

주의사항

시간 제한

훅 명령은 60초 안에 끝나야 해요. 너무 오래 걸리는 작업은 피하세요.

보안

프로젝트 폴더의 설정은 팀원도 볼 수 있어요. 비밀 정보가 포함된 명령은 개인 설정에 넣으세요.

문제 해결

훅이 안 되면 claude --debug로 실행해서 어디서 문제가 생기는지 확인해보세요.