훅 생성과 실행 방법 | 클로드 코드

이전 글에서 훅(Hook)의 개념과 종류를 살펴봤어요. 훅이 무엇인지, PreToolUse와 PostToolUse가 어떤 시점에 동작하는지, 그리고 Notification이나 Stop 같은 다양한 내장 훅이 있다는 것까지 알아봤어요.

이번 글에서는 한 발 더 나아가, 훅을 직접 만들어 보는 과정을 다뤄요. 감시할 도구를 지정하는 매처(Matcher)부터, 훅 커맨드가 전달받는 데이터 구조, 종료 코드(Exit Code)를 활용한 제어 흐름, 그리고 설정 파일에 훅을 등록하고 실행하는 방법까지 단계별로 풀어볼게요.

글 마지막에는 민감한 설정 파일을 보호하는 실무 예시도 함께 구현해 볼 거예요.

1. 훅을 만드는 4가지 단계

훅을 만드는 과정은 네 가지 질문에 답하는 것과 같아요.

단계	핵심 질문	하는 일
1단계	언제 개입할 것인가?	PreToolUse 또는 PostToolUse 선택
2단계	어떤 도구를 감시할 것인가?	매처(Matcher)로 대상 도구 지정
3단계	무엇을 확인할 것인가?	툴 콜 데이터를 받는 커맨드 작성
4단계	어떻게 응답할 것인가?	종료 코드(Exit Code)로 허용/차단 결정

아래 다이어그램은 클로드가 .env 파일을 읽으려 할 때, 각 훅이 어느 시점에 실행되는지를 보여줘요.

사용자(You)             Claude Code              Claude(LLM)
      │                       │                        │
      │  ".env 파일 내용을       │                        │
      │   알려줘"               │                        │
      │ ─────────────────────>│                        │
      │                       │   사용자의 요청 전달       │
      │                       │───────────────────────>│
      │                       │                        │
      │                       │   "Read: .env"         │
      │                       │<───────────────────────│
      │                       │                        │
      │                ┌──────────────┐                │
      │                │ PreToolUse   │                │
      │                │ hook 실행     │                │
      │                └──────┬───────┘                │
      │                       │                        │
      │                ┌──────────────┐                │
      │                │ Claude Code  │                │
      │                │ 파일 읽기 실행  │                │
      │                └──────┬───────┘                │
      │                       │                        │
      │                ┌──────────────┐                │
      │                │ PostToolUse  │                │
      │                │ hook 실행     │                │
      │                └──────┬───────┘                │
      │                       │                        │
      │                       │   읽은 내용 전달          │
      │                       │───────────────────────>│
      │                       │                        │
      │                       │  ".env 파일에는          │
      │                       │   DB_HOST, API_KEY     │
      │                       │   등이 설정되어...\"       │
      │                       │<──────────────────────│
      │                       │                        │
      │  ".env 파일에는         │                        │
      │   DB_HOST, API_KEY    │                        │
      │   등이 설정되어...\"      │                        │
      │<──────────────────────│                        │
      │                       │                        │

1) PreToolUse vs PostToolUse: 간단 리마인드

이전 글에서 자세히 다뤘으므로 핵심만 짚고 넘어갈게요.

PreToolUse: 도구 실행 이전에 동작. 도구 호출 자체를 차단할 수 있음
PostToolUse: 도구 실행 이후에 동작. 결과를 확인하고 후속 조치를 취하는 데 활용

이번 글의 예시에서는 민감한 파일 접근을 사전에 막아야 하므로 PreToolUse 훅을 중심으로 설명할게요.

2) 감시할 도구(Tool) 지정하기: 매처(Matcher)

훅의 시점을 정했다면, 다음은 “어떤 도구를 감시할 것인가”를 결정할 차례예요. 클로드 코드는 내부적으로 여러 가지 도구를 사용하는데, 훅은 이 중 원하는 도구에만 반응하도록 설정할 수 있어요. 이때 사용하는 것이 매처(Matcher) 이에요.

먼저 클로드 코드가 사용하는 주요 내장 도구(Built-in Tools)를 살펴볼게요.

도구 이름	역할
Read	파일 읽기
Edit, MultiEdit	기존 파일 수정
Write	새 파일 생성 및 내용 작성
Bash	터미널 명령어 실행
Glob	패턴 기반으로 파일/폴더 검색
Grep	파일 내용 검색
Task	하위 에이전트(Sub-agent) 생성
WebFetch, WebSearch	웹 페이지 조회 및 검색

매처는 이 도구 이름들과 대조하여 훅을 실행할지 결정해요. 설정 파일에서 매처를 지정하는 방식은 다음과 같아요.

단일 도구 감시:

"matcher": "Read"

여러 도구 동시 감시 (파이프 | 사용):

"matcher": "Read|Grep"

위 예시는 Read 또는 Grep 도구가 호출될 때 훅이 실행되도록 설정한 것이에요. 파이프 기호(|)가 OR 연산자 역할을 해요.

모든 도구 감시 (와일드카드 * 사용):

"matcher": "*"

와일드카드를 사용하면 클로드가 어떤 도구를 호출하든 훅이 실행돼요. 디버깅 용도로 유용하지만, 모든 동작마다 훅이 실행되므로 성능에 영향을 줄 수 있다는 점은 유의해야 해요.

매처는 CCTV의 감시 범위를 설정하는 것과 비슷해요. 건물 전체를 감시할 수도 있고(*), 정문과 후문만 집중 감시할 수도 있어요(Read|Write). 어떤 지점을 감시할지는 보호하려는 자산에 따라 달라지는 것이죠.

3) 툴 콜 데이터를 받는 커맨드 작성하기

이제 훅이 “언제”, “어떤 도구를” 감시할지 정했으니, 실제로 실행될 커맨드를 작성할 차례예요. 이 커맨드는 클로드가 도구를 호출할 때마다 표준 입력(Standard Input, stdin) 을 통해 JSON 형태의 데이터를 전달받게 돼요.

(1) 툴 콜 데이터의 구조

클로드가 도구를 호출하면, 훅 커맨드에는 다음과 같은 JSON 데이터가 전달돼요.

{
  "session_id": "abc12345-de67-...",
  "transcript_path": "/Users/username/project/...",
  "hook_event_name": "PreToolUse",
  "tool_name": "Read",
  "tool_input": {
    "file_path": "/my-project/config/.env"
  }
}

각 필드가 담고 있는 정보를 정리하면 다음과 같아요.

필드	설명	예시
`session_id`	현재 클로드 코드 세션의 고유 식별자	`"abc12345-de67-..."`
`transcript_path`	대화 기록이 저장되는 파일 경로	`"/Users/username/..."`
`hook_event_name`	훅의 종류 (어떤 시점에 실행되었는지)	`"PreToolUse"` 또는 `"PostToolUse"`
`tool_name`	호출된 도구의 이름	`"Read"`, `"Bash"`, `"Write"` 등
`tool_input`	도구에 전달되는 입력 파라미터	도구마다 다른 구조를 가짐

여기서 핵심은 tool_name과 tool_input이에요. 이 두 필드를 조합하면 “클로드가 어떤 도구로 무엇을 하려는지”를 정확히 파악할 수 있어요.

tool_input의 내부 구조는 호출되는 도구에 따라 달라진다는 점도 기억해 두세요. 예를 들어 Read 도구는 file_path 필드를 포함하고, Bash 도구라면 command 필드를 포함하게 돼요.

(2) 커맨드가 데이터를 읽는 방식

훅 커맨드는 이 JSON 데이터를 표준 입력(stdin)으로 받아서 파싱해요. Node.js로 작성한다면 아래와 같은 흐름이 돼요.

async function main() {
  // 1. stdin에서 데이터 수집
  const chunks = [];
  for await (const chunk of process.stdin) {
    chunks.push(chunk);
  }

  // 2. JSON 파싱
  const toolData = JSON.parse(Buffer.concat(chunks).toString());

  // 3. 필요한 정보 추출
  const toolName = toolData.tool_name;
  const filePath = toolData.tool_input?.file_path || "";

  // 4. 조건에 따라 허용/차단 결정
  // (다음 단계에서 다룹니다)
}

main();

흐름을 정리하면 세 단계예요. stdin을 통해 들어오는 데이터를 모두 수집하고, JSON으로 변환한 뒤, 필요한 필드를 꺼내서 조건을 판단하는 거예요.

(3) PostToolUse 훅의 데이터는 조금 달라요

PostToolUse 훅에서는 도구가 이미 실행된 후이기 때문에, tool_response라는 추가 필드가 포함돼요. 아래는 TodoWrite 도구가 실행된 후의 데이터 예시예요.

{
  "session_id": "abc12345-...",
  "transcript_path": "/Users/username/...",
  "hook_event_name": "PostToolUse",
  "tool_name": "TodoWrite",
  "tool_input": {
    "todos": [
      {
        "content": "README 작성하기",
        "status": "pending",
        "priority": "medium",
        "id": "1"
      }
    ]
  },
  "tool_response": {
    "oldTodos": [],
    "newTodos": [
      {
        "content": "README 작성하기",
        "status": "pending",
        "priority": "medium",
        "id": "1"
      }
    ]
  }
}

tool_response를 통해 도구 실행의 이전 상태(oldTodos)와 이후 상태(newTodos)를 비교할 수 있어요. 이 정보를 활용하면 “변경 사항이 의도대로 반영되었는지” 검증하는 로직을 작성할 수 있어요.

(4) 데이터 구조를 미리 파악하는 팁

훅을 처음 작성할 때 가장 어려운 부분은 “내 커맨드에 정확히 어떤 데이터가 들어오는지 모른다”는 점이에요. 도구마다 tool_input의 구조가 다르기 때문이에요.

이럴 때 유용한 방법이 있어요. jq 명령어를 활용해서 들어오는 데이터를 파일로 저장하는 헬퍼 훅을 먼저 만들어 보는 거예요.

"PostToolUse": [
  {
    "matcher": "*",
    "hooks": [
      {
        "type": "command",
        "command": "jq . > hook-debug-log.json"
      }
    ]
  }
]

이렇게 설정하면 모든 도구 호출 시 전달되는 데이터가 hook-debug-log.json 파일에 기록돼요. 이 파일을 열어보면 자신의 커맨드가 어떤 구조의 데이터를 받게 되는지 정확히 확인할 수 있어요. 본격적인 훅 로직을 작성하기 전에 이 방법으로 데이터 형태를 먼저 파악해 두면 훨씬 수월해요.

훅 커맨드가 데이터를 받는 과정은 택배 분류 센터의 작업과 비슷해요. 물건이 도착하면(stdin으로 JSON 전달), 운송장을 스캔하고(JSON 파싱), 보낸 사람과 내용물을 확인한 뒤(tool_name, tool_input 추출), 문제가 없으면 배송을 계속하고 문제가 있으면 반송 처리를 하는 것(허용/차단 결정)이죠.

4) 종료 코드(Exit Code)로 피드백 전달하기

커맨드가 데이터를 분석한 뒤에는 클로드에게 “이 동작을 허용할지, 차단할지”를 알려줘야 해요. 이때 사용하는 것이 종료 코드(Exit Code) 예요.

(1) 종료 코드란?

종료 코드는 프로그램이 실행을 마칠 때 운영체제에 반환하는 정수 값이에요. 일반적으로 0은 “정상 종료”를, 0이 아닌 값은 “오류 발생”을 의미해요. 터미널에서 명령어를 실행한 뒤 echo $?를 입력하면 직전 명령어의 종료 코드를 확인할 수 있어요.

# 정상 실행된 경우
$ ls
file1.txt  file2.txt
$ echo $?
0

# 오류가 발생한 경우
$ ls /nonexistent-folder
ls: /nonexistent-folder: No such file or directory
$ echo $?
2

클로드 코드의 훅에서는 이 종료 코드에 특별한 의미를 부여하고 있어요.

(2) 훅에서 사용하는 종료 코드

종료 코드	의미	동작
`0`	허용	도구 호출을 정상적으로 진행해요
`2`	차단 (PreToolUse 전용)	도구 호출을 중단하고, stderr 메시지를 클로드에게 전달해요

코드에서 종료 코드를 반환하는 방법은 간단해요.

허용하는 경우:

process.exit(0);  // 문제 없음, 도구 호출 진행

차단하는 경우:

console.error("이 파일에 대한 접근이 제한되어 있어요.");
process.exit(2);  // 도구 호출 차단

여기서 주목할 점은 console.error()이에요. 종료 코드 2로 차단할 때, 표준 에러(stderr) 에 출력한 메시지가 클로드에게 피드백으로 전달돼요. 클로드는 이 메시지를 읽고 “아, 이 동작이 훅에 의해 차단되었구나”라고 이해하게 돼요. 단순히 차단만 하는 것이 아니라 “왜 차단되었는지”까지 알려줄 수 있는 것이죠.

(3) 전체 흐름 정리

4단계를 모두 합친 전체 흐름을 다이어그램으로 정리하면 다음과 같아요.

클로드가 도구 호출 시도
        │
        ▼
  [1단계] PreToolUse 시점에 훅 실행
        │
        ▼
  [2단계] 매처 확인: 감시 대상 도구인가?
        │
        ├── 대상 아님 ──▶ 훅 건너뜀 ──▶ 도구 정상 실행
        │
        └── 대상 맞음 ──▶ 커맨드 실행
                              │
                              ▼
                    [3단계] stdin으로 JSON 수신, 조건 검사
                              │
                    ┌─────────┴─────────┐
                    │                   │
                  문제 없음              문제 발견
                    │                   │
                    ▼                   ▼
            [4단계] exit(0)     stderr에 사유 출력
            도구 호출 진행        exit(2) → 도구 차단
                                클로드가 사유 전달받음

종료 코드는 건물 출입 관리 시스템과 비슷하다고 볼 수 있어요. 출입증을 태그하면(도구 호출), 시스템이 권한을 확인한 뒤(조건 검사), 문제가 없으면 문을 열어주고(exit 0), 권한이 없으면 문을 잠근 채 안내 메시지를 표시해 주는 것(stderr + exit 2)이죠. 안내 메시지 덕분에 방문자(클로드)도 왜 거절당했는지 이해하고 다른 방법을 시도할 수 있어요.

2. 훅 설정 및 실행 방법

4가지 단계를 통해 훅의 작동 원리를 이해했으니, 이제 실제로 프로젝트에 훅을 등록하고 실행하는 방법을 알아볼게요.

1) 설정 파일의 구조

이전 글에서 훅을 설정할 수 있는 세 가지 경로(Global, Project, Project Local)를 살펴봤어요. 이번에는 그 설정 파일 안에 훅을 어떤 구조로 작성하는지에 초점을 맞추겠어요.

.claude/settings.local.json 파일의 전체 구조는 다음과 같아요.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Read|Grep",
        "hooks": [
          {
            "type": "command",
            "command": "node /absolute/path/to/hooks/block-sensitive.js"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "node /absolute/path/to/hooks/post-edit-check.js"
          }
        ]
      }
    ]
  }
}

구조를 계층별로 분해해 볼게요.

계층	역할	비고
`hooks`	모든 훅을 담는 최상위 객체
`"PreToolUse"` / `"PostToolUse"`	훅의 실행 시점	배열로, 여러 훅 그룹을 등록 가능
`matcher`	감시할 도구 지정	`"Read"`, `"Read\|Grep"`, `"*"` 등
`hooks[].type`	훅의 실행 방식	현재는 `"command"`만 지원
`hooks[].command`	실행할 스크립트 경로 또는 명령어	절대 경로 권장

하나의 매처에 여러 커맨드를 등록할 수도 있고, 서로 다른 매처를 가진 여러 훅 그룹을 동일한 시점에 등록할 수도 있어요.

2) 훅 스크립트 파일 배치

설정 파일에서 command에 지정하는 스크립트는 프로젝트 내 원하는 위치에 둘 수 있어요. 일반적으로는 프로젝트 루트에 hooks 디렉토리를 만들어 관리하는 것이 깔끔해요.

my-project/
├── .claude/
│   └── settings.local.json       ← 훅 설정 파일
├── hooks/
│   ├── block-sensitive-files.js   ← PreToolUse 훅 스크립트
│   └── post-edit-typecheck.sh     ← PostToolUse 훅 스크립트
├── src/
│   └── ...
└── package.json

스크립트 파일은 Node.js(.js), 쉘 스크립트(.sh), Python(.py) 등 원하는 언어로 작성할 수 있어요. 설정 파일의 command에서 해당 런타임을 명시해 주기만 하면 돼요.

"command": "node /Users/me/my-project/hooks/block-sensitive-files.js"

"command": "bash /Users/me/my-project/hooks/post-edit-typecheck.sh"

"command": "python3 /Users/me/my-project/hooks/validate-query.py"

3) 절대 경로 사용과 팀 공유 전략

클로드 코드 공식 문서에서는 보안을 위해 훅 스크립트의 경로를 절대 경로(Absolute Path) 로 지정할 것을 권장하고 있어요. 상대 경로를 사용하면 경로 가로채기(Path Interception)나 바이너리 심기(Binary Planting) 같은 공격에 취약해질 수 있기 때문이에요.

하지만 절대 경로를 사용하면 한 가지 문제가 생겨요. 팀원 A의 프로젝트 경로가 /Users/alice/projects/my-app이고, 팀원 B의 경로가 /Users/bob/dev/my-app이라면, 같은 설정 파일을 공유할 수 없는 거예요.

이 문제를 해결하는 실무적인 방법은 템플릿 파일과 초기화 스크립트를 조합하는 것이에요.

Step 1. settings.example.json 파일에 플레이스홀더를 넣어 버전 관리에 포함해요.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Read|Grep",
        "hooks": [
          {
            "type": "command",
            "command": "node $PWD/hooks/block-sensitive-files.js"
          }
        ]
      }
    ]
  }
}

Step 2. 초기화 스크립트(scripts/init-claude.js 등)에서 $PWD를 실제 절대 경로로 치환한 뒤, settings.local.json으로 복사해요.

// scripts/init-claude.js (간략화한 예시)
const fs = require("fs");
const path = require("path");

const projectRoot = process.cwd();
const template = fs.readFileSync(".claude/settings.example.json", "utf-8");
const resolved = template.replaceAll("$PWD", projectRoot);

fs.writeFileSync(".claude/settings.local.json", resolved);
console.log("settings.local.json 생성 완료!");

Step 3. package.json의 scripts에 등록하여 팀원 누구나 한 번에 실행할 수 있도록 해요.

{
  "scripts": {
    "setup": "node scripts/init-claude.js"
  }
}

이렇게 하면 settings.example.json은 Git에 커밋하고, settings.local.json은 .gitignore에 추가하여 각자의 환경에 맞는 절대 경로를 사용할 수 있어요.

이 패턴은 .env.example과 .env의 관계와 동일해요. 템플릿은 공유하되, 실제 값은 각자 환경에서 생성하는 것이죠. 훅 설정도 같은 원리를 적용하면 보안과 팀 협업을 동시에 챙길 수 있어요.

4) 설정 변경 후 적용

훅 설정 파일을 수정하거나 훅 스크립트를 새로 추가한 후에는 클로드 코드를 재시작해야 변경 사항이 반영돼요. 설정 파일은 세션 시작 시점에 한 번 읽히기 때문에, 실행 중인 세션에서는 변경 사항이 자동으로 적용되지 않아요.

설정을 변경한 뒤 훅이 제대로 동작하는지 확인하려면, 앞서 3단계의 (4)에서 소개한 jq 디버깅 훅을 함께 등록해 두면 편리해요. 훅이 실제로 실행되는지, 어떤 데이터를 받는지를 로그 파일로 바로 확인할 수 있으니까요.

3. 실무 예시: .env 파일 보호 훅 만들기

지금까지 배운 내용을 종합하여, 클로드가 .env 파일에 접근하지 못하도록 차단하는 PreToolUse 훅을 처음부터 끝까지 만들어 볼게요.

1) 요구사항 정리

프로젝트에 API 키나 데이터베이스 비밀번호가 담긴 .env 파일이 있다고 가정해 볼게요. 클로드가 작업 중에 이 파일을 읽거나 내용을 검색하면 민감한 정보가 대화 컨텍스트에 노출될 수 있어요.

이를 방지하기 위해 다음 두 가지를 차단해야 해요.

Read 도구: .env 파일을 직접 읽는 경우
Grep 도구: .env 파일 내용을 검색하는 경우

4단계 프레임워크에 대입하면 이렇게 돼요.

단계	결정
1단계 (시점)	PreToolUse (읽기 전에 차단해야 하므로)
2단계 (매처)	`Read\|Grep`
3단계 (커맨드)	파일 경로에 `.env`가 포함되어 있는지 검사
4단계 (종료 코드)	포함 시 exit(2), 미포함 시 exit(0)

2) 훅 스크립트 작성

프로젝트 루트에 hooks 디렉토리를 만들고, block-env-access.js 파일을 작성해요.

// hooks/block-env-access.js

async function main() {
  // stdin에서 툴 콜 데이터 수집
  const chunks = [];
  for await (const chunk of process.stdin) {
    chunks.push(chunk);
  }

  const toolData = JSON.parse(Buffer.concat(chunks).toString());

  // Read 도구는 file_path, Grep 도구는 path 필드를 사용
  const targetPath =
    toolData.tool_input?.file_path ||
    toolData.tool_input?.path ||
    "";

  // .env 파일에 접근하려는지 확인
  if (targetPath.includes(".env")) {
    console.error(
      "[훅 차단] .env 파일에는 접근할 수 없습니다. " +
      "민감한 환경변수가 포함되어 있어 보안 정책에 의해 차단되었습니다."
    );
    process.exit(2);  // 차단
  }

  // .env가 아닌 경우 정상 진행
  process.exit(0);
}

main();

코드의 핵심 로직은 단순해요. tool_input에서 파일 경로를 추출한 뒤, 그 경로에 .env가 포함되어 있으면 차단하고, 아니면 통과시키는 거예요.

Read와 Grep 도구가 파일 경로를 담는 필드명이 다를 수 있으므로(file_path 또는 path), 두 가지를 모두 확인하는 점도 눈여겨볼 부분이에요.

3) 설정 파일 등록

.claude/settings.local.json에 방금 작성한 훅을 등록해요.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Read|Grep",
        "hooks": [
          {
            "type": "command",
            "command": "node /Users/username/my-project/hooks/block-env-access.js"
          }
        ]
      }
    ]
  }
}

command의 경로는 반드시 본인 환경의 절대 경로로 지정해 주세요.

4) 테스트 및 동작 확인

설정을 저장한 후 클로드 코드를 재시작해요. 그리고 클로드에게 .env 파일을 읽어달라고 요청해 보세요.

클로드가 Read 도구로 .env 파일을 읽으려 하면, 훅이 이를 가로채서 차단해요. 클로드는 stderr로 전달된 메시지를 확인하고, 해당 파일에 접근이 제한되어 있다는 사실을 사용자에게 알려줄 거예요.

Grep으로 .env 파일 내용을 검색하려는 시도도 마찬가지로 차단돼요. 매처에 Read|Grep을 모두 지정했기 때문이에요.

5) 확장 아이디어

이 기본 패턴을 응용하면 다양한 보호 정책을 구현할 수 있어요.

확장 시나리오	수정 포인트
`.env` 외에 `.secret`, `.pem` 등도 차단	경로 검사 조건에 패턴 추가
특정 디렉토리 전체 쓰기 금지	매처를 `Write`로 변경, 디렉토리 경로 검사
코드 수정 후 타입 체크 자동 실행	PostToolUse + `Edit\|MultiEdit` 매처로 `tsc --noEmit` 실행
쿼리 파일 중복 작성 방지	PostToolUse + `Write` 매처로 기존 쿼리와 비교 로직 실행

이 예시는 현관문에 스마트 잠금장치를 설치하는 것과 같아요. 한 번 설치해 두면, 이후에는 별도로 신경 쓰지 않아도 허가되지 않은 접근을 자동으로 막아줘요. 그리고 이 잠금장치의 규칙(어떤 파일을 보호할지, 어떤 도구를 감시할지)은 언제든 설정 파일에서 수정할 수 있어요.