CPN 한국어 자습서 · Claude Code in Action
3 · 훅과 SDK
Introducing hooks
훅(hook)은 Claude가 도구를 실행하기 직전·직후에 우리가 정한 명령을 끼워 넣는 장치입니다. 파일을 쓰고 나면 자동으로 포매터를 돌리거나, 특정 파일은 읽지 못하게 막을 수도 있습니다. 도구 실행 전 훅을 PreToolUse, 실행 후 훅을 PostToolUse라고 부릅니다.
Stephen Grider · 강사
이번 영상에서는 훅(hook)을 살펴봅니다. 훅은 Claude가 도구를 실행하려고 할 때, 그 전이나 후에 명령을 실행하게 해 줍니다. 훅으로는 정말 흥미롭고 유용한 기능을 만들 수 있습니다.
예를 들어 Claude가 파일을 쓰기로 하면 생성된 파일에 자동으로 코드 포매터를 돌릴 수 있고, 파일이 수정된 뒤 테스트를 돌릴 수도 있으며, Claude가 특정 파일을 읽지 못하도록 막을 수도 있습니다. 가능성은 정말 무궁무진하고, 좋은 예시 몇 개를 준비해 두었습니다.
먼저 훅이 정확히 어떻게 동작하는지 짚어 봅시다. 다시 떠올려 보면, Claude Code에 무언가를 요청하면 그 질의가 도구 정의와 함께 Claude 모델로 전달됩니다. 그러면 모델은 정해진 형식의 응답을 돌려주며 도구를 실행하기로 결정할 수 있습니다. 그 시점에 실제로 도구(예: 파일 읽기)를 실행하고 그 결과로 응답하는 것은 Claude Code의 몫입니다.
훅은 바로 그 도구 실행 직전 또는 직후에 코드를 실행할 수 있게 해 줍니다. 도구 앞에서 도는 훅은 PreToolUse(사전 도구 사용) 훅, 도구 뒤에서 도는 훅은 PostToolUse(사후 도구 사용) 훅이라고 부릅니다.
훅을 정의하려면 Claude 설정 파일(settings)에 설정을 추가합니다. 설정 파일은 여러 개가 있다는 점을 기억하세요 — 내 컴퓨터의 모든 프로젝트에 적용되는 전역용, 다른 엔지니어와 공유되는 프로젝트용, 그리고 그 프로젝트에서 나에게만 적용되는 개인용이 있습니다. 훅은 이 파일에 직접 손으로 적어 넣거나, Claude Code 안의 내장 /hooks 명령으로 추가할 수 있습니다.
설정 자체는 화면 오른쪽 같은 모습입니다. 이 예시 파일을 함께 살펴봅시다. 먼저 파일 안에 뚜렷한 두 영역이 있습니다. 한 영역은 도구 사용 전에 실행할 명령을 모두 나열합니다 — PreToolUse 훅이죠. 다른 영역은 도구 사용 후에 실행할 명령을 나열합니다 — PostToolUse 훅입니다.
각 영역에는 matcher를 지정합니다. 어떤 도구 사용 유형을 찾을지 가리키는 값입니다. 이 예시에서는 read 도구의 사용을 찾으려 합니다. Claude Code가 파일을 읽으려 할 때마다 거기 적힌 명령을 실행하겠다는 뜻이죠. 마찬가지로 PostToolUse 영역에서는 write·edit·multi-edit 도구를 쓴 뒤에 다른 명령을 실행하도록 했습니다.
여기서부터가 중요합니다. 방금 본 명령들에는 Claude가 실행하려는 도구 호출의 정보가 전달됩니다. PreToolUse 훅이라면 Claude가 무엇을 하려는지 들여다보고, 어떤 이유로든 허용하고 싶지 않다면 그 도구 사용을 차단하고 Claude에 에러 메시지를 돌려보낼 수 있습니다.
반면 PostToolUse 훅이라면 도구 호출이 이미 일어난 뒤라 막기엔 늦었습니다. 하지만 그 호출을 바탕으로 후속 작업을 할 수 있습니다 — 예컨대 방금 수정된 파일을 포매팅하는 것처럼요. 그리고 그 도구 사용에 관한 메시지를 Claude에 돌려줄 수도 있습니다. 예를 들어 별도 프로그램으로 코드 품질을 검사하거나 타입 체크를 한 뒤 그 결과를 Claude에 피드백하면, Claude가 그 피드백을 받아 방금 쓴 파일을 다시 고칠 수 있습니다.
훅이 무엇이고 무엇을 위한 것인지 아직 헷갈려도 괜찮습니다. 훅 개념을 머릿속에 그리는 일은 꽤 까다롭습니다. 그래서 잠시 뒤 훅을 직접 쓰는 예제 프로젝트로 돌아와 함께 만들어 보겠습니다.
이 장에서 배우는 것What you'll learn
약 4분훅 = 도구 실행 직전·직후에 끼워 넣는 명령
도구 앞은 PreToolUse, 뒤는 PostToolUse
정의 위치는 settings 파일 (전역 · 프로젝트 · 개인)
matcher로 어떤 도구를 감시할지 지정
Pre 훅은 도구를 차단할 수 있다
Post 훅은 막진 못해도 후속 작업·피드백 가능
Read, Write).훅은 Claude가 도구를 실행하기 직전이나 직후에 우리가 정한 명령을 끼워 넣는 장치입니다. 파일을 쓰면 자동으로 포매터를 돌리고, 파일이 바뀌면 테스트를 돌리고, 특정 파일은 읽지 못하게 막을 수 있습니다 — 가능성은 무궁무진합니다.
요청
.env 읽어줘
모델 결정
Read 도구 호출
PreToolUse 훅
matcher: Read · 검사/차단
도구 실행
Claude Code가 실행
PostToolUse 훅
포매팅 · 피드백
훅은 흐름을 가로채는 지점입니다. Pre 훅은 도구가 실행되기 전이라 막을 수 있고, Post 훅은 실행된 뒤라 후속 작업만 가능합니다.
훅을 이해하려면 먼저 평소 흐름을 떠올려야 합니다. 요청이 도구 정의와 함께 모델로 가고, 모델은 정해진 형식으로 도구를 호출하기로 결정하며, 실제 실행과 결과 응답은 Claude Code가 맡습니다.
훅은 바로 ③ 실행의 앞뒤에 코드를 실행합니다. 앞이면 PreToolUse, 뒤면 PostToolUse입니다.
훅은 settings 파일에 적습니다. 손으로 직접 적거나 Claude Code 안의 /hooks 명령으로 추가합니다. 파일에는 PreToolUse·PostToolUse 두 영역이 있고, 각 영역의 matcher가 감시할 도구를 가리킵니다.
{
"hooks": {
"PreToolUse": [
{
"matcher": "Read", # Read 도구를 감시
"hooks": [
{
"type": "command",
"command": "node /home/hooks/read_hook.js"
}
]
}
],
"PostToolUse": [
{
"matcher": "Write|Edit|MultiEdit", # 셋 중 하나가 끝난 뒤
"hooks": [
{
"type": "command",
"command": "node /home/hooks/edit_hook.js"
}
]
}
]
}
}matcher: "Read" — Claude가 Read 도구를 쓰려 하면 그 앞에서 명령 실행.matcher: "Write|Edit|MultiEdit" — 세 도구 중 하나가 끝난 뒤 명령 실행.두 훅의 결정적 차이는 타이밍입니다. 도구가 돌기 전이냐 후냐에 따라 할 수 있는 일이 달라집니다.
Claude가 무엇을 하려는지 미리 들여다봅니다.
✓ 도구 사용을 막을 수 있다
이미 실행됐으니 막기엔 늦었습니다. 대신 후속 작업을 합니다.
✗ 막을 수 없다 · 후속만
PreToolUse는 도구를 차단할 수 있고, PostToolUse는 후속 작업·피드백만 가능.matcher로 감시할 도구를 고른다 (|로 여러 개).Q1도구를 실행하기 전에 막으려면 어떤 훅이 필요한가요?
Pre 훅은 도구가 돌기 전에 실행되므로, 검사 후 차단하고 에러를 돌려줄 수 있습니다.
Q2훅이 감시할 도구를 지정하는 키는?
matcher가 어떤 도구 유형을 감시할지 가리킵니다. 파이프(|)로 여러 도구를 묶습니다.
Q3파일을 쓴 뒤 자동 포매팅을 하려면 어떤 훅이 적절한가요?
포매팅은 파일이 이미 쓰인 뒤에 하는 후속 작업이므로 Post 훅이 맞습니다.
개념을 잡았으니, 이제 예제 프로젝트에서 직접 훅을 설계해 봅니다 — 어떤 종류의 훅을 쓸지, 어떤 도구를 감시할지 단계로 정합니다. → 훅 정의하기
전 코스는 계속 무료입니다. 등록하면 이 코스의 남은 16개 레슨을 끝까지 읽을 수 있습니다.
이미 등록하셨다면 그때 쓰신 이메일을 넣어 주세요.