blevels

Home / AI / AI 바이브코딩 / 훅(Hook) 설정하기 — AI의 행동에 자동 트리거 거는 법

VIBE

훅(Hook) 설정하기 — AI의 행동에 자동 트리거 거는 법

게시일 2026-04-30수정일 2026-04-30
공식 링크
On this page

:::callout type=info 이 튜토리얼은 Claude Code 1.x / 훅(Hook) 설정 기준입니다 (2026-04). 도구 업데이트 시 검토 필요. :::

Claude Code를 쓰다 보면 반복되는 행동 패턴이 생긴다. 파일을 편집할 때마다 lint를 돌리고, 배포 직전에는 반드시 테스트를 확인하고, 특정 명령 후에는 알림을 보내는 식이다. 훅(Hook)은 이 모든 반복을 자동화하는 장치다. AI가 특정 행동을 취하기 전(PreToolUse)이나 취한 후(PostToolUse)에 지정한 셸 명령이 자동으로 실행된다.

훅이란 무엇인가

훅은 Claude Code의 이벤트 시스템이다. AI가 도구(Tool)를 호출하는 순간을 가로채서 원하는 스크립트를 실행할 수 있다. 지원하는 이벤트는 크게 네 가지다.

  • PreToolUse — 도구 실행 직전에 실행. 검증·가드 역할
  • PostToolUse — 도구 실행 직후에 실행. 알림·로깅 역할
  • Notification — Claude가 사용자 알림을 보낼 때
  • Stop — 세션 종료 시점

훅은 settings.json에서 정의한다. 프로젝트 단위로 .claude/settings.json에 쓰거나, 전역으로 ~/.claude/settings.json에 쓸 수 있다.

준비물

  • Claude Code CLI (최신 버전)
  • Node.js 20+ (스크립트 작성 시)
  • 텍스트 에디터 (settings.json 편집용)
  • 예상 시간: 20분

1단계 — settings.json 열기

프로젝트 루트에서 .claude/settings.json 파일을 확인한다. 없으면 생성한다.

mkdir -p .claude
touch .claude/settings.json

기본 구조는 다음과 같다.

{
  "hooks": {}
}
AD

2단계 — PreToolUse 훅 추가하기

파일을 편집(Edit, Write)하기 전에 lint를 자동으로 실행하는 훅을 추가한다.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npm run lint --silent"
          }
        ]
      }
    ]
  }
}

matcher는 정규식으로 도구 이름을 필터링한다. Edit|Write는 Edit 또는 Write 도구가 호출될 때만 실행된다는 의미다.

3단계 — PostToolUse 훅으로 알림 보내기

Bash 도구가 실행된 후 텔레그램으로 알림을 보내는 예시다.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "node scripts/notify-telegram.mjs"
          }
        ]
      }
    ]
  }
}

알림 스크립트(notify-telegram.mjs)는 환경 변수로 봇 토큰과 채팅 ID를 받는다.

// notify-telegram.mjs
const token = process.env.TG_BOT_TOKEN;
const chatId = process.env.TG_CHAT_ID;
const text = `✅ Bash 도구 실행 완료 — ${new Date().toLocaleString('ko-KR')}`;

await fetch(`https://api.telegram.org/bot${token}/sendMessage`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ chat_id: chatId, text }),
});
AD

4단계 — Stop 훅으로 세션 로그 자동 저장

세션이 끝날 때마다 작업 내역을 자동으로 기록하려면 Stop 훅을 활용한다.

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "node scripts/log-session.mjs close"
          }
        ]
      }
    ]
  }
}

matcher를 생략하면 모든 Stop 이벤트에 반응한다.

결과 확인

훅이 올바르게 동작하는지 확인하려면 Claude Code를 열고 파일 편집을 요청해 본다. 터미널 하단에 훅 실행 결과가 표시된다. 오류가 발생하면 exit code가 0이 아닌 값으로 반환되고, 에러 메시지가 출력된다.

다음 단계

훅을 조합하면 AI의 행동에 일관된 품질 게이트를 걸 수 있다. 다음 단계로 CLAUDE.md와 훅을 결합해 프로젝트 전용 자동화 규칙을 만들어 보자.

관련 가이드: claude-md / mcp-입문 / 플러그인-만들기

AD