Hooks 소개

이번 영상에서는 Hooks(훅) 를 살펴봅니다. Hooks는 Claude가 도구(tool)를 실행하기 전이나 후에 명령을 실행할 수 있게 해주는 기능입니다. Hooks는 자동화된 워크플로우를 구현하는 데 매우 유용합니다. 대표적인 활용 예시는 다음과 같습니다.

• Claude가 파일을 작성한 뒤 자동으로 코드 포매터 실행

• 파일이 편집된 뒤 자동으로 테스트 실행

• Claude가 특정 파일에 접근하지 못하도록 차단

Hooks로 할 수 있는 작업의 가능성은 사실상 무한합니다.

1. Hooks는 어떻게 동작하는가?

Hooks를 이해하려면 먼저 Claude Code와 여러분이 상호작용할 때의 일반적인 흐름을 짚어봐야 합니다. [사용자 질의] → Claude 모델 (+ 도구 정의) → 도구 사용 결정 → Claude Code가 도구 실행 → 결과 반환(코딩 어시스턴트란 참고)

여러분이 Claude Code에 무언가 질문하면, 질의는 도구 정의와 함께 Claude 모델로 전송됩니다. Claude 모델은 잘 포맷된 응답을 제공하며 도구를 실행하기로 결정할 수 있는데, 이 지점에서 Claude Code가 요청된 도구(예: ReadFile)를 실행하고 그 결과를 응답합니다. Hooks는 위와같은 일반적인 흐름 중간에 끼어들어 도구 실행 직전이나 직후(예: 파일을 읽기 직전이나 읽은 직후)에 코드를 실행할 수 있게 해줍니다.

2. Hook의 두 가지 주요 타입

가장 일반적인 두 가지 Hook 타입입니다. (다른 Hook 종류는 이후 강의에서 다룹니다.)

3. Hook 설정 위치

Hooks는 Claude 설정 파일에 정의합니다. 다음 세 위치에 추가할 수 있습니다.

작성 방법은 두 가지입니다.

1. 설정 파일에 직접 작성

   

2. Claude Code 내에서 /hooks 명령어 사용

4. PreToolUse Hook: 도구 실행 전 개입

PreToolUse Hook은 도구가 실행되기 전에 동작합니다. 이 때, matcher를 통해 어떤 도구 타입을 대상으로 할지 지정하게 됩니다.

"PreToolUse": [
  {
    "matcher": "Read",
    "hooks": [
      {
        "type": "command",
        "command": "node /home/hooks/read_hook.js"
      }
    ]
  }
]

위와같이 PreToolUse Hook을 설정하면 파일 읽기(Read)라는 도구가 실행되기 전(파일을 읽기 전)에 지정된 명령어(node /home/hooks/read_hook.js)가 실행됩니다. 이 명령은 Claude가 수행하려는 도구 호출의 세부 정보(무엇을 읽으려고 하는지에 대한 세부 정보)를 전달받으며, 다음 중 하나를 선택하게 됩니다.

• 작업이 정상적으로 진행되도록 허용

• 도구 호출을 차단하고 Claude에 에러 메시지 반환

5. PostToolUse Hook: 도구 실행 후 개입

PostToolUse Hook은 도구가 실행된 후에 동작합니다. 다음은 Write, Edit, MultiEdit 작업 후에 명령어가 트리거되는 예시입니다.

"PostToolUse": [
  {
    "matcher": "Write|Edit|MultiEdit",
    "hooks": [
      {
        "type": "command",
        "command": "node /home/hooks/edit_hook.js"
      }
    ]
  }
]

💡 포인트: matcher에서 |를 사용해 여러 도구를 한 번에 매칭할 수 있습니다.

도구 호출이 이미 일어났기 때문에 PostToolUse Hook은 작업을 차단할 수는 없습니다. 대신 다음을 할 수 있습니다.

• 후속 작업 수행 (예: 방금 편집된 파일을 자동 포맷)

• 해당 도구 사용에 대한 추가 피드백을 Claude에 전달

예를 들어 코드 품질 점검 프로그램을 별도로 실행하거나 타입 체크를 돌린 뒤, 그 결과를 Claude에게 피드백할 수 있습니다. Claude는 그 피드백을 받아 방금 작성한 파일을 다시 업데이트할 수 있습니다.

6. 실용적인 활용 사례

핵심 인사이트는 이렇습니다.

Hooks는 여러분의 도구와 프로세스를 Claude Code의 워크플로우에 통합해, Claude Code의 능력을 확장할 수 있게 해줍니다.

• PreToolUse hook은 Claude가 무엇을 할 수 있는지 통제하고,

• PostToolUse hook은 Claude가 한 일을 보강합니다.

핵심 요약

Hooks라는 개념이 아직 헷갈리더라도 괜찮습니다. Hooks를 머릿속에서 정리하는 일은 꽤 까다로울 수 있으니, 다음 강의에서 실제 샘플 프로젝트를 기반으로 Hooks를 직접 다뤄보며 자연스럽게 익혀봅시다.