본문으로 건너뛰기
Kreath Archive
TechProjectsBooksAbout
TechProjectsBooksAbout

내비게이션

  • Tech
  • Projects
  • Books
  • About
  • Tags

카테고리

  • AI / ML
  • 웹 개발
  • 프로그래밍
  • 개발 도구

연결

  • GitHub
  • Email
  • RSS
© 2026 Kreath Archive. All rights reserved.Built with Next.js + MDX
홈TechProjectsBooksAbout
//
  1. 홈
  2. 테크
  3. 5장: 훅(Hooks)으로 자동화 파이프라인 구축하기
2026년 2월 23일·개발 도구·

5장: 훅(Hooks)으로 자동화 파이프라인 구축하기

Claude Code 훅 시스템의 개념과 라이프사이클을 이해하고, 코드 품질 게이트와 자동화 파이프라인을 구축하는 방법을 다룹니다.

13분426자8개 섹션
ai-agentanthropicmcpautomationdevtools
공유
claude-code-guide5 / 10
12345678910
이전4장: 핵심 워크플로우 - 코드 작성, 리뷰, 리팩터링다음6장: 커스텀 슬래시 명령어와 스킬 만들기

훅이란 무엇인가

훅(Hooks)은 Claude Code의 라이프사이클 특정 지점에서 자동으로 실행되는 사용자 정의 동작입니다. CLAUDE.md가 Claude에게 "무엇을 해야 하는지" 알려주는 정적 지시서라면, 훅은 "언제 무엇을 자동으로 할지" 정의하는 동적 자동화 메커니즘입니다.

훅의 핵심 가치는 결정론적 실행에 있습니다. 프롬프트의 표현이나 모델의 판단에 관계없이, 조건이 충족되면 반드시 실행됩니다. 예를 들어 "파일을 수정한 후에는 항상 린트를 돌려 줘"라는 CLAUDE.md 지시는 Claude가 잊거나 무시할 수 있지만, PostToolUse 훅으로 설정하면 100% 실행됩니다.

라이프사이클 이벤트

Claude Code는 다양한 라이프사이클 지점에서 훅을 실행할 수 있습니다. 주요 이벤트를 실행 순서대로 살펴보겠습니다.

이벤트실행 시점주요 용도
SessionStart세션 시작 시환경 검증, 동적 컨텍스트 로드
UserPromptSubmit사용자 프롬프트 제출 시입력 검증, 프롬프트 변환
PreToolUse도구 실행 직전위험 명령어 차단, 입력 검증
PostToolUse도구 실행 직후린트 자동 실행, 결과 검증
StopClaude 응답 완료 시최종 검증, 자동 후처리
SubagentStop서브에이전트 완료 시서브에이전트 결과 검증
Notification알림 발생 시외부 알림 전송
PreCompact컨텍스트 압축 직전중요 정보 보존
PostCompact컨텍스트 압축 직후압축 후 컨텍스트 보강
SessionEnd세션 종료 시정리 작업, 로그 기록

훅 설정 방법

훅은 .claude/settings.json 또는 ~/.claude/settings.json에 정의합니다. 기본 구조는 다음과 같습니다.

.claude/settings.json
json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "npx eslint --fix $CLAUDE_FILE_PATH",
        "timeout": 30000
      }
    ]
  }
}

구성 요소

필드설명필수
matcher훅을 실행할 조건 (도구 이름 등)선택
command실행할 셸 명령어필수
timeout실행 제한 시간 (ms)선택

matcher는 정규식 패턴을 지원합니다. Write|Edit은 Write 또는 Edit 도구가 사용될 때 매칭됩니다. matcher를 생략하면 해당 이벤트의 모든 호출에서 실행됩니다.

환경 변수

훅 명령어에서 사용할 수 있는 환경 변수가 제공됩니다.

변수설명
$CLAUDE_FILE_PATH도구가 조작한 파일 경로
$CLAUDE_TOOL_NAME실행된 도구 이름
$CLAUDE_TOOL_INPUT도구 입력 (JSON)
$CLAUDE_TOOL_OUTPUT도구 출력 (JSON)
$CLAUDE_SESSION_ID현재 세션 ID
$CLAUDE_PROJECT_DIR프로젝트 루트 경로

실전 훅 레시피

1. 파일 저장 후 자동 린트 + 포맷

가장 일반적인 훅입니다. 파일을 수정할 때마다 자동으로 ESLint와 Prettier를 실행합니다.

.claude/settings.json
json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "npx eslint --fix \"$CLAUDE_FILE_PATH\" 2>/dev/null; npx prettier --write \"$CLAUDE_FILE_PATH\" 2>/dev/null",
        "timeout": 15000
      }
    ]
  }
}
Tip

2>/dev/null로 에러 출력을 억제하면, 린트 대상이 아닌 파일(예: .md, .json) 수정 시 불필요한 에러 메시지가 Claude의 컨텍스트를 오염시키는 것을 방지합니다.

2. 위험 명령어 차단

프로덕션 데이터베이스에 대한 위험한 명령어를 사전에 차단합니다.

.claude/settings.json
json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "command": "echo \"$CLAUDE_TOOL_INPUT\" | python3 -c \"import sys,json; cmd=json.load(sys.stdin).get('command',''); exit(1 if any(w in cmd for w in ['DROP TABLE','DELETE FROM','--force','rm -rf /']) else 0)\"",
        "timeout": 5000
      }
    ]
  }
}

PreToolUse 훅이 비정상 종료(exit code != 0)를 반환하면 해당 도구 실행이 차단됩니다.

3. 세션 시작 시 환경 검증

세션이 시작될 때 필수 도구와 환경 변수가 올바르게 설정되어 있는지 확인합니다.

.claude/settings.json
json
{
  "hooks": {
    "SessionStart": [
      {
        "command": "node --version >/dev/null 2>&1 && pnpm --version >/dev/null 2>&1 && echo 'Environment OK' || echo 'WARNING: Required tools missing'",
        "timeout": 10000
      }
    ]
  }
}

4. TypeScript 타입 검사 자동 실행

파일 수정 후 TypeScript 타입 에러를 자동으로 감지합니다.

.claude/settings.json
json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "if echo \"$CLAUDE_FILE_PATH\" | grep -qE '\\.(ts|tsx)$'; then npx tsc --noEmit --pretty 2>&1 | head -20; fi",
        "timeout": 30000
      }
    ]
  }
}

5. 커밋 메시지 검증

Git 커밋 시 Conventional Commits 형식을 강제합니다.

.claude/settings.json
json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "command": "echo \"$CLAUDE_TOOL_INPUT\" | python3 -c \"import sys,json; cmd=json.load(sys.stdin).get('command',''); exit(1 if 'git commit' in cmd and not any(cmd.find(p)>0 for p in ['feat:','fix:','refactor:','docs:','chore:','test:','style:','perf:']) else 0)\"",
        "timeout": 5000
      }
    ]
  }
}

6. 외부 알림 전송

Claude Code 작업이 완료되면 Slack이나 Discord로 알림을 보냅니다.

.claude/settings.json
json
{
  "hooks": {
    "Notification": [
      {
        "command": "curl -s -X POST \"$SLACK_WEBHOOK_URL\" -H 'Content-Type: application/json' -d \"{\\\"text\\\": \\\"Claude Code: $CLAUDE_TOOL_OUTPUT\\\"}\"",
        "timeout": 10000
      }
    ]
  }
}

대화형 훅 설정

JSON을 직접 편집하는 대신 /hooks 명령어로 대화형 인터페이스를 사용할 수도 있습니다.

Claude Code 세션 내
bash
/hooks

메뉴에서 이벤트를 선택하고, 명령어와 매처를 입력하면 자동으로 settings.json에 추가됩니다. JSON 문법 오류를 방지할 수 있어 초보자에게 유용합니다.

훅 디버깅

훅이 예상대로 동작하지 않을 때 확인할 사항입니다.

실행 확인

훅 명령어에 로그를 추가하여 실행 여부를 확인합니다.

.claude/settings.json
json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "command": "echo \"[HOOK] File written: $CLAUDE_FILE_PATH\" >> /tmp/claude-hooks.log && npx eslint --fix \"$CLAUDE_FILE_PATH\"",
        "timeout": 15000
      }
    ]
  }
}

일반적인 문제

훅이 실행되지 않는 경우:

  • matcher 패턴이 도구 이름과 일치하는지 확인합니다
  • settings.json의 JSON 문법이 올바른지 확인합니다
  • 훅 설정 범위(로컬/프로젝트/전역)를 확인합니다

훅이 타임아웃되는 경우:

  • timeout 값을 늘립니다
  • 명령어가 사용자 입력을 기다리지 않는지 확인합니다
  • 네트워크 요청이 포함된 경우 연결 상태를 확인합니다

훅이 도구 실행을 차단하는 경우:

  • PreToolUse 훅의 exit code를 확인합니다. 0이 아닌 값은 차단으로 해석됩니다
  • 의도치 않은 차단이면 에러 처리를 수정합니다

훅 설계 모범 사례

빠르게 유지

훅은 매 도구 호출마다 실행되므로 속도가 중요합니다. 무거운 작업은 백그라운드로 실행하거나, 특정 파일 패턴에만 매칭되도록 조건을 좁힙니다.

개선 전: 모든 파일에 실행
json
{
  "matcher": "Write|Edit",
  "command": "npx tsc --noEmit"
}
개선 후: TypeScript 파일만
json
{
  "matcher": "Write|Edit",
  "command": "if echo \"$CLAUDE_FILE_PATH\" | grep -qE '\\.(ts|tsx)$'; then npx tsc --noEmit 2>&1 | head -5; fi"
}

실패를 명확히 처리

훅의 exit code와 출력은 Claude의 컨텍스트에 반영됩니다. 실패 시 명확한 메시지를 출력하면 Claude가 문제를 이해하고 스스로 수정할 수 있습니다.

조합하여 파이프라인 구성

여러 훅을 조합하면 완전한 품질 파이프라인을 구축할 수 있습니다.

.claude/settings.json
json
{
  "hooks": {
    "SessionStart": [
      {
        "command": "pnpm install --frozen-lockfile 2>/dev/null; echo 'Dependencies verified'",
        "timeout": 30000
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "if echo \"$CLAUDE_FILE_PATH\" | grep -qE '\\.(ts|tsx)$'; then npx eslint --fix \"$CLAUDE_FILE_PATH\" 2>/dev/null; fi",
        "timeout": 15000
      }
    ],
    "Stop": [
      {
        "command": "npx tsc --noEmit 2>&1 | tail -5",
        "timeout": 60000
      }
    ]
  }
}

이 설정은 다음과 같은 파이프라인을 구성합니다:

  1. 세션 시작: 의존성 설치 확인
  2. 파일 수정 후: ESLint 자동 수정
  3. 응답 완료 후: TypeScript 전체 타입 검사

정리

훅은 Claude Code의 자동화 핵심 메커니즘입니다.

  • 라이프사이클 이벤트(SessionStart, PreToolUse, PostToolUse, Stop 등)에 셸 명령어를 연결합니다
  • CLAUDE.md 지시와 달리 결정론적으로 실행되어, 프롬프트 표현에 관계없이 일관된 동작을 보장합니다
  • 린트, 타입 검사, 위험 명령어 차단, 외부 알림 등 다양한 자동화가 가능합니다
  • 빠른 실행, 명확한 실패 처리, 파이프라인 조합이 핵심 설계 원칙입니다

다음 장에서는 훅과 함께 Claude Code를 확장하는 또 다른 축인 커스텀 슬래시 명령어와 스킬 시스템을 다룹니다.

이 글이 도움이 되셨나요?

관련 주제 더 보기

#ai-agent#anthropic#mcp#automation#devtools

관련 글

개발 도구

6장: 커스텀 슬래시 명령어와 스킬 만들기

Claude Code의 스킬 시스템을 이해하고, 반복 작업을 자동화하는 커스텀 슬래시 명령어를 설계하고 구현하는 방법을 다룹니다.

2026년 2월 25일·15분
개발 도구

4장: 핵심 워크플로우 - 코드 작성, 리뷰, 리팩터링

Claude Code로 코드를 작성하고, 리뷰하고, 리팩터링하는 핵심 워크플로우를 실전 예제와 함께 익힙니다.

2026년 2월 21일·14분
개발 도구

7장: MCP 서버 연동으로 외부 도구 통합하기

Model Context Protocol의 개념을 이해하고, Claude Code에 MCP 서버를 연결하여 데이터베이스, API, 외부 서비스를 통합하는 방법을 다룹니다.

2026년 2월 27일·13분
이전 글4장: 핵심 워크플로우 - 코드 작성, 리뷰, 리팩터링
다음 글6장: 커스텀 슬래시 명령어와 스킬 만들기

댓글

목차

약 13분 남음
  • 훅이란 무엇인가
  • 라이프사이클 이벤트
  • 훅 설정 방법
    • 구성 요소
    • 환경 변수
  • 실전 훅 레시피
    • 1. 파일 저장 후 자동 린트 + 포맷
    • 2. 위험 명령어 차단
    • 3. 세션 시작 시 환경 검증
    • 4. TypeScript 타입 검사 자동 실행
    • 5. 커밋 메시지 검증
    • 6. 외부 알림 전송
  • 대화형 훅 설정
  • 훅 디버깅
    • 실행 확인
    • 일반적인 문제
  • 훅 설계 모범 사례
    • 빠르게 유지
    • 실패를 명확히 처리
    • 조합하여 파이프라인 구성
  • 정리