claudekit / guides / hooks-automation
[ Guide · Advanced · 12분 ]

Hook으로 자동화 워크플로 만들기

published · updated

Claude Code의 Hook으로 자동화 워크플로를 구성하는 방법을 정리합니다. 어떤 이벤트에 걸 수 있고, 어디에 설정하며, 동작하지 않을 때 어떻게 디버깅할지 안내합니다.

Hook이 가능하게 하는 것

Hook은 코드를 수정하지 않고 Claude Code의 동작에 자동화 레이어를 덧붙이는 방법입니다. 대표적인 활용:

  • 파일 저장 후 자동 포매팅
  • 위험한 명령 차단 (rm -rf, git push --force)
  • 응답이 끝날 때마다 안내 메시지 표시
  • 컴팩션 전 중요 정보 보존
  • LLM에게 “이 변경 안전한가?” 물어보고 차단

설정 위치

파일범위
~/.claude/settings.json사용자 전체
.claude/settings.json프로젝트 (git 커밋)
.claude/settings.local.json개인 로컬 (gitignore)

기본 구조

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_response.filePath // .tool_input.file_path' | { read -r f; prettier --write \"$f\"; } 2>/dev/null || true"
          }
        ]
      }
    ]
  }
}

자주 쓰는 이벤트

이벤트시점사용 사례
PreToolUse도구 실행 전위험 명령 차단, 권한 검증
PostToolUse도구 실행 성공 후자동 포매팅, 테스트 자동 실행
PostToolUseFailure도구 실패 후에러 로깅, 알림
PermissionRequest권한 확인이 필요할 때승인 여부 자동 판단
UserPromptSubmit사용자 입력 시프롬프트 분석, 컨텍스트 주입
StopClaude가 응답을 마칠 때(매 턴)작업 완료 여부 점검, 안내 메시지
PreCompact컴팩션 직전중요 정보 별도 저장
SessionStart세션 시작 또는 재개환경 점검, 초기 메시지
SessionEnd세션 종료정리 작업 (출력 메시지는 표시되지 않음)

이 밖에도 SubagentStart, SubagentStop, StopFailure, FileChanged, PreModelSwitch 등 많은 이벤트가 있습니다. 전체 목록은 Hooks reference에서 확인할 수 있습니다.

다섯 가지 훅 타입

1. command — 셸 명령 실행

{
  "type": "command",
  "command": "jq -r '.tool_input.command' >> ~/.claude/bash-log.txt"
}

stdin으로 이벤트 JSON을 받습니다. jq로 필요한 필드를 추출해 사용합니다.

2. http — URL로 POST 요청

{
  "type": "http",
  "url": "http://localhost:8080/hooks/pre-tool-use",
  "headers": { "Authorization": "Bearer $MY_TOKEN" },
  "allowedEnvVars": ["MY_TOKEN"]
}

이벤트 JSON을 POST 본문으로 보내고, 응답 본문을 command 훅의 JSON 출력과 같은 형식으로 해석합니다. 헤더에 환경변수를 넣으려면 allowedEnvVars에 이름을 등록해야 합니다.

3. mcp_tool — MCP 도구 호출

{
  "type": "mcp_tool",
  "server": "my_server",
  "tool": "security_scan",
  "input": { "file_path": "${tool_input.file_path}" }
}

설정된 MCP 서버의 도구를 직접 호출합니다. 도구의 텍스트 결과는 command 훅의 stdout처럼 처리됩니다.

4. prompt — LLM에 질문

{
  "type": "prompt",
  "prompt": "이 명령이 시스템에 위험한 변경을 가하는지 판단합니다: $ARGUMENTS. 안전하면 {\"ok\": true}, 위험하면 {\"ok\": false, \"reason\": \"이유\"} 형식의 JSON으로 답합니다."
}

$ARGUMENTS 자리에 훅 입력 JSON이 들어갑니다. 모델은 ok와 reason 필드를 가진 JSON으로 답하고, ok: false일 때의 동작은 이벤트마다 다릅니다. 기본 모델은 Claude Code가 백그라운드 작업에 쓰는 모델이며, model 필드로 바꿀 수 있습니다.

5. agent — 에이전트 실행

{
  "type": "agent",
  "prompt": "변경된 파일에 대해 단위 테스트가 함께 추가됐는지 검증"
}

Read, Grep, Glob 같은 도구로 조건을 확인한 뒤 판단을 돌려주는 서브에이전트를 실행합니다. 토큰 비용이 더 크고, 공식 문서는 이 타입을 실험적 기능으로 분류합니다.

실전 예: 위험 명령 차단

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "prompt",
            "prompt": "다음 셸 명령이 데이터를 영구 삭제하거나 되돌리기 어려운 변경을 하는지 판단합니다: $ARGUMENTS. 그렇지 않으면 {\"ok\": true}, 그렇다면 {\"ok\": false, \"reason\": \"이유\"}로 답합니다.",
            "continueOnBlock": true
          }
        ]
      }
    ]
  }
}

PreToolUse에서 ok: false가 나오면 도구 호출이 거부됩니다. 기본값은 그 자리에서 턴을 끝내는 것이고, continueOnBlock: true를 주면 거부 이유를 Claude에게 돌려줘 다른 방법으로 작업을 이어 가게 합니다.

command 훅이나 http 훅으로 차단 규칙을 만들 때는 "onFailure": "block"(v2.1.295 이상)을 함께 지정할 수 있습니다. 훅이 시작되지 않거나 시간 초과로 실패해도 동작을 통과시키지 않고 차단합니다.

실전 예: 파일 저장 후 자동 포매팅

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_response.filePath // .tool_input.file_path' | { read -r f; case \"$f\" in *.ts|*.tsx|*.js|*.jsx|*.json|*.md) prettier --write \"$f\";; esac; } 2>/dev/null || true"
          }
        ]
      }
    ]
  }
}

확장자별로 적용 도구를 다르게 할 수 있습니다.

실전 예: 응답이 끝날 때 안내 메시지

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo '{\"systemMessage\": \"응답 완료 — 변경된 파일 확인 권장\"}'"
          }
        ]
      }
    ]
  }
}

Stop은 세션이 끝날 때가 아니라 Claude가 응답을 마칠 때마다 실행됩니다. 훅이 systemMessage를 담은 JSON을 출력하면 사용자에게 메시지가 표시됩니다. 세션 종료 시점에 실행되는 SessionEnd는 systemMessage 같은 JSON 출력을 버리므로, 메시지 표시가 아니라 정리 작업에만 씁니다.

디버깅 절차

  1. JSON 문법 — jq . settings.json으로 유효성 확인
  2. 매처 패턴 — Write|Edit처럼 정확한 도구명 사용
  3. 명령 직접 테스트 — echo '{"tool_input":{"file_path":"test.ts"}}' | <훅 명령>
  4. 등록 확인 — /hooks를 열면 설정된 훅과 정의된 위치(사용자, 프로젝트, 로컬 설정, 플러그인 등)를 볼 수 있습니다. settings 파일을 직접 고치면 file watcher가 자동으로 반영합니다.
  5. debug 모드 — claude --debug로 훅 실행 로그 확인
  6. 일시 비활성화 — 훅 때문에 문제가 생기는지 확인하려면 settings에 "disableAllHooks": true를 지정합니다. 개별 훅만 끄는 방법은 없으므로 특정 훅은 설정에서 삭제합니다.

hookify 도구 활용

hookify는 자연어로 훅을 생성해주는 플러그인입니다. 직접 JSON을 작성하기 부담스러우면 hookify로 초안을 만들고 settings.json에 적용하는 방식이 빠릅니다.

다음 단계

§ 12

자주 묻는 질문

자주 묻는 질문
§ 12.1
Hook은 무엇인가요?
특정 이벤트(도구 호출 전후, 응답 종료, 세션 시작과 종료, 컴팩션 등)에 반응해 자동으로 실행되는 핸들러입니다. 셸 명령, HTTP 요청, MCP 도구 호출, LLM 프롬프트, 에이전트 다섯 가지 타입이 있습니다.
§ 12.2
어디에 설정하나요?
`~/.claude/settings.json`(사용자 전체), `.claude/settings.json`(프로젝트 공유), `.claude/settings.local.json`(개인용 로컬)의 `hooks` 필드에 정의합니다. 각 이벤트에 매처와 핸들러를 연결합니다.
§ 12.3
어떤 이벤트에 훅을 걸 수 있나요?
PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest, UserPromptSubmit, Stop, SubagentStop, SessionStart, SessionEnd, PreCompact, PostCompact 등 30가지가 넘습니다. 도구 사용 전후 자동화에는 PreToolUse와 PostToolUse가 가장 자주 쓰입니다.
§ 12.4
코드 실행 없이 LLM으로 검증하는 훅도 가능한가요?
네. 훅 type을 `prompt`로 지정하면 모델이 `{"ok": true}` 또는 `{"ok": false, "reason": "..."}` 형식의 JSON으로 판단을 돌려줍니다. 도구를 사용해 확인해야 하면 `agent` 타입을 쓸 수 있지만, 공식 문서는 이 타입을 실험적 기능으로 분류합니다.
§ 12.5
훅이 동작하지 않을 때는 어떻게 디버깅하나요?
settings.json JSON 문법 오류, 매처 패턴 불일치가 가장 흔한 원인입니다. `/hooks`로 훅이 등록됐는지 확인하고, `claude --debug`로 실행 로그를 봅니다. settings 파일을 직접 고치면 file watcher가 자동으로 반영하므로 보통 재시작은 필요하지 않습니다.