훅 — 정해진 길목의 자동 장치

훅은 정해진 순간이 오면 저절로 실행되는 자동 장치입니다. 복도의 자동 점등 센서처럼, 누가 지나가면 알아서 불이 켜집니다. 사람이 기억하지 않아도 회사가 규칙을 지키게 만드는 도구입니다. 말로 부탁하는 것만으로 모자란 이유는 AI가 무엇이 위험한 일인지 스스로 가려내지 못하기 때문입니다. 이 약점이 왜 생기는지는 「AI는 자기가 한 일을 스스로 판단하지 못합니다」 페이지에서 설명합니다.

훅이란 — 부탁이 아니라 장치

클로드에게 “파일을 고친 뒤에는 꼭 서식을 정리해 줘”라고 말로 부탁하면, 할 때도 있고 빠뜨릴 때도 있습니다. 훅으로 걸어 두면 그 순간마다 예외 없이 실행됩니다. 그래서 훅은 크게 세 가지 일에 씁니다.

• 규칙 강제 — “지켜 달라”고 말하는 대신, 안 지키면 지나가지 못하게 만듭니다. 단, 막을 수 있는 길목에 걸었을 때만 그렇습니다.
• 반복 잡무 자동화 — 매번 시키던 일을 그 길목에 아예 걸어 둡니다.
• 기존 도구와 연결 — 알림·기록 같은 바깥 장치와 클로드 코드를 잇습니다.

길목(이벤트) 전체 지도

훅을 거는 지점 하나하나를 이벤트라고 부릅니다. 이 가이드와 책에서는 길목이라고 합니다. 그중 다섯이 자주 쓰는 길목입니다. 아래 표에 ★로 표시했고, 책 10장이 다루는 다섯도 바로 이것입니다.

이 밖에도 작업 폴더가 바뀔 때, 설정 파일이 바뀔 때 같은 더 세밀한 길목이 있습니다. 다만 처음에는 위의 다섯(★)만 알아도 대부분의 자동화를 만들 수 있습니다.

매처 — 같은 길목 안의 거름망

매처(matcher)는 훅이 아무 때나 실행되지 않도록 조건을 좁히는 거름망입니다. 비워 두면 그 길목을 지날 때마다 전부 실행되고, 조건을 적으면 맞을 때만 실행됩니다.

예를 들어 도구 길목에서 매처를 Edit|Write로 적으면, 파일을 고치는 도구(Edit)나 새로 쓰는 도구(Write)에만 반응합니다. 세로줄(|)은 “또는”이라는 뜻입니다. 무엇을 거르는지는 길목마다 다릅니다.

거는 법 — 말로 시킵니다

훅도 말로 겁니다. 걸기 전에 먼저 보여 달라고 함께 말하는 것이 요령입니다.

# 클로드 코드 입력창에
세션을 시작할 때마다 인수인계서를 읽는 훅을 걸어 줘. 걸기 전에 먼저 보여 줘.

훅의 실제 내용은 settings.json 파일 안에 적힙니다.

어느 설정 파일에 넣느냐에 따라 훅의 적용 범위가 달라집니다.

훅이 클로드와 대화하는 법

훅은 실행되고 끝나는 데 그치지 않고 결과를 클로드에게 되돌려 줄 수 있습니다. 가장 간단한 방식은 종료 코드입니다. 훅으로 걸어 둔 명령은 일을 끝내면서 숫자 하나를 남기는데, 그 숫자가 몇이냐에 따라 다음 동작이 정해집니다.

더 꼼꼼하게 다루고 싶으면 종료 코드는 0으로 두고, 대신 JSON(컴퓨터끼리 주고받는, 서식이 정해진 쪽지)을 출력하는 방법도 있습니다. 예를 들어 PreToolUse 훅은 도구 사용을 막으면서 “이유는 이렇다”라고 클로드에게 직접 알릴 수 있습니다. 다만 두 방식을 섞으면 안 됩니다. 종료 코드 2로 막을 때는 JSON 출력이 무시되기 때문입니다.

판단이 필요한 길목엔 프롬프트 훅

지금까지 본 훅은 “이 문구가 있으면 막아라”처럼 규칙이 명확할 때 씁니다. 그런데 “요청한 일이 정말 다 끝났는가?”처럼 판단이 필요한 길목도 있습니다. 이럴 때는 훅의 종류를 적는 칸(type)에 command 대신 prompt를 적습니다. command는 정해진 명령어를 실행하는 종류이고, prompt는 판단을 클로드 모델에게 맡기는 종류입니다. 그러면 모델이 그 길목에서 직접 예·아니요를 정합니다.

대표 사례가 Stop 길목입니다. 클로드가 응답을 끝내려 할 때 “모든 일이 정말 끝났는지” 모델에게 되묻고, 아직이라고 판단되면 계속 일하게 만듭니다. 우리 회사도 마칠 때 보고 형식을 지켰는지 이 길목에서 자동 점검합니다. 파일을 열어 보거나 명령을 실행해 확인해야 하는 더 복잡한 판단에는 type을 agent(직접 열어 보고 실행해 보며 판단하는 종류)로 지정하는 방식도 있습니다. 다만 아직 실험 단계라, 안정적으로 돌아야 하는 작업에는 명령어 훅을 권합니다.

바로 쓰는 레시피 네 가지

전부 말로 시킵니다. 각 레시피의 문장을 그대로 입력창에 넣어도 됩니다.

① 기다릴 때 알림 — 클로드가 허락이나 입력을 기다릴 때 화면에 알림을 띄웁니다. 터미널을 계속 지켜보지 않아도 됩니다. 처음 걸어 보기에 가장 좋은 훅입니다.

# 클로드 코드 입력창에
네가 내 허락이나 입력을 기다릴 때마다 화면에 알림을 띄우는 훅을
Notification 길목에 걸어 줘. 걸기 전에 먼저 보여 줘.

이 훅이 설정 파일에 실제로 적히는 모습은 다음과 같습니다. 직접 쓸 일은 드물지만, 클로드가 보여 줄 때 읽을 줄 알면 안심하고 허락할 수 있습니다.

# ~/.claude/settings.json 안 (macOS 알림 예)
"hooks": {
  "Notification": [
    { "matcher": "",
      "hooks": [ { "type": "command",
        "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'" } ] }
  ]
}

② 민감 파일 보호 — .env(비밀번호나 API 키가 담긴 파일) 같은 파일은 도구를 쓰기 직전(PreToolUse) 길목에서 막습니다. 막을 때 이유를 함께 적어 두는 것이 요령입니다. 위 표에서 본 대로, 클로드가 그 이유를 읽고 다른 방법을 찾기 때문입니다.

# 클로드 코드 입력창에
.env 파일은 네가 절대 고치지 못하게 PreToolUse 길목에서 막는 훅을 걸어 줘.
막을 때는 이유를 함께 남기게 해 줘.

③ 압축 뒤 규칙 다시 넣기 — 대화가 길어지면 클로드 코드가 내용을 요약해 공간을 비웁니다. 이것을 압축이라고 합니다. 이때 중요한 규칙이 흐려질 수 있습니다. SessionStart 길목에 compact 매처를 걸면, 압축이 끝날 때마다 꼭 기억할 내용이 자동으로 다시 들어갑니다. 훅이 출력한 글이 그대로 클로드의 컨텍스트에 더해지는 특징을 이용한 것입니다.

# 클로드 코드 입력창에
대화가 압축된 직후마다 우리 회사 핵심 규칙을 다시 알려 주는 훅을
SessionStart 길목에 compact 매처로 걸어 줘.

④ 세션 시작 때 인수인계 읽기 — 앞의 “거는 법”에서 본 훅이 바로 이것입니다. 매일 아침 출근한 직원이 전날 업무 일지를 먼저 펴게 만드는 셈입니다. 우리 회사도 세션 첫머리에 진행 일지를 자동으로 읽는 훅으로 아침 인수인계를 대신합니다.

★작동 확인·끄기 — “걸었다”와 “돈다”는 다릅니다

훅은 자동이라 어긋나도 오류 한 줄 없이 조용히 지나갑니다. 그래서 걸고 나면 반드시 시험합니다.

1. “지금 걸려 있는 훅 목록 보여 줘”로 등록을 확인합니다.
2. 세션을 새로 열어 실제로 작동하는지 눈으로 확인합니다.
3. 작동하지 않으면 — “그 훅이 왜 안 도는지 봐 줘.”
4. 끄기는 — “그 훅 빼 줘.”

우리 회사도 “걸었다”와 “돈다”가 달랐던 적이 여러 번 있습니다. 시험까지가 거는 일입니다. 훅이 뜻대로 움직이지 않을 때는 세 가지를 차례로 봅니다.

• 훅이 실행되지 않음 — /hooks로 올바른 길목 아래에 등록됐는지, 매처의 도구 이름이 대소문자까지 정확한지 봅니다.
• 고쳤는데 목록에 안 보임 — JSON 형식이 올바른지 클로드에게 봐 달라고 시킵니다. 끝에 쉼표를 남기거나 주석을 넣으면 오류가 납니다. 그래도 안 보이면 세션을 다시 시작합니다.
• Stop 훅이 계속 막음 — Stop 훅이 응답을 자꾸 막으면 같은 자리를 맴돌게 됩니다. 이때는 클로드 코드가 같은 곳을 다시 지나는 것을 알아채고, 어느 지점부터는 훅이 막아도 따르지 않고 넘어갑니다. 무한 반복에 빠지지 않게 하는 안전장치입니다.

출근할 때·일을 지시받는 순간·도구를 쓰기 직전·퇴근할 때 길목의 훅이 실행되는 동안에는, 클로드가 일하는 중임을 알리는 입력창 위 진행 표시에 그 사실과 걸린 시간이 뜹니다. 출근할 때 길목의 훅이 오래 걸려 내 지시가 기다리고 있으면 Esc로 그 지시를 취소할 수 있습니다.