🧩 레슨

Hook 개념 — '부탁'이 아니라 '강제'

규칙을 글로 쓰면 AI가 가끔 잊어요. Hook은 잊을 수 없게 만드는 장치예요.

① 오늘의 미션

"분명 적어놨는데…"

반찬가게 코드에 규칙을 하나 정했어요. CLAUDE.md에 또렷이 적어뒀죠 — "코드 고치면 항상 테스트부터 돌려라."

처음 몇 번은 Claude가 잘 지켜요. 그런데 대화가 길어지고 바빠지자, 어느 순간 테스트를 건너뛰고 그냥 코드를 고칩니다. 규칙을 적어둔 게 무용지물이 된 걸까요? 오늘은 "부탁"을 "강제"로 바꾸는 장치 — hook을 배웁니다.

설명을 따라 진행하면, 여기서 직접 쳐보게 돼요 👇

~/my-shop

$ _

📚 「Hook 개념 — '부탁'이 아니라 '강제'」 레슨 내용 전체 텍스트로 훑어보기

"분명 적어놨는데…"

반찬가게 코드에 규칙을 하나 정했어요. CLAUDE.md에 또렷이 적어뒀죠 — "코드 고치면 항상 테스트부터 돌려라."

CLAUDE.md에 또렷이 적어둔 규칙을 Claude가 어쩌다 한 번씩 건너뛰는 진짜 이유는 뭘까요?

맞아요. LLM은 다음 토큰을 확률로 고르는 모델이라, CLAUDE.md 규칙은 '거의 항상' 따르지만 가끔 흔들려요. 부탁은 부탁일 뿐 — 보장은 아니에요. 그래서 '반드시'가 필요한 일엔 다른 장치가 필요해요.

hook(훅)은 Claude의 작업 흐름 특정 순간에 내가 만든 스크립트를 자동으로 끼워 넣는 장치예요. CLAUDE.md가 '말로 하는 부탁'이라면, hook은 '코드로 거는 장치'예요.

결정적 차이

· CLAUDE.md 규칙 → LLM이 판단해서 따름 → 확률적(가끔 잊음)
· hook 스크립트 → 그냥 코드가 실행됨 → 결정적(매번 똑같이)

반찬가게 비유로, CLAUDE.md는 알바에게 "퇴근 전 가스 꼭 잠가줘"라고 부탁한 메모, hook은 문에 단 자동 가스 차단 장치예요. 사람이 깜빡해도 장치는 안 깜빡해요.

hook은 아무 데나 끼는 게 아니라, Claude 작업 흐름의 정해진 순간(이벤트)에 걸어요. 자주 쓰는 네 가지예요.

· UserPromptSubmit — 내가 메시지를 보낸 직후 (입력을 검사·보강할 때)
· PreToolUse — Claude가 도구(파일 수정·명령 실행)를 쓰기 직전 (위험한 짓 막을 때)
· PostToolUse — 도구를 쓴 직후 (고친 코드에 테스트·포맷 자동 적용)
· Stop — Claude가 답을 마치고 멈추려 할 때 (마무리 점검)

반찬가게 코드라면 — "코드 고치면 테스트" 규칙은 PostToolUse(파일을 고친 직후)에 걸면 딱이에요.

PreToolUse에 건 스크립트가 위험한 명령을 발견하고 exit 2로 끝나면, Claude는 어떻게 될까요?

맞아요. hook 스크립트가 exit 2로 끝나면 그 동작은 차단돼요. 막힌 이유가 Claude에게 전달돼서, Claude는 그걸 보고 다른 안전한 방법을 시도하죠. 즉 hook은 단순 알림이 아니라 실제로 막을 힘이 있어요.

hook이 왜 CLAUDE.md보다 확실한지, Claude에게 직접 우리 반찬가게 예로 물어봐요. 가게 폴더에서 Claude를 켜고 대화해봐요.

우리 가게 코드는 '고치면 테스트부터' 규칙이 있어. 이걸 CLAUDE.md에 적는 거랑 hook으로 거는 거랑 뭐가 달라?

— 확률 vs 결정의 차이를 대화로 확인해요

핵심을 Claude 입으로 다시 들었어요 — 판단은 부탁(CLAUDE.md), 보장은 장치(hook).

같은 '테스트 먼저' 규칙을 두 방식으로 걸면 이렇게 달라요.

📝 CLAUDE.md (부탁): "코드 고치면 테스트 돌려줘"라고 적어둠. Claude가 읽고 판단해서 대체로 따름.
약점: 바쁘거나 대화가 길면 가끔 건너뜀.

🔒 hook (강제): 파일 수정(PostToolUse) 직후 테스트 스크립트가 코드로 실행됨.
강점: Claude가 잊든 말든 매번 무조건 실행. 실패하면 막아줌.

반찬가게 코드를 고친 직후마다 자동으로 테스트를 돌리고 싶어요. 이 hook은 어떤 이벤트에 걸어야 할까요?

정답! PostToolUse예요. '도구를 쓴 뒤(Post)'에 도니까, 파일을 고치자마자 테스트가 자동으로 따라 붙죠. 반대로 위험한 명령을 미리 막고 싶다면 PreToolUse에 걸어요.

오늘의 한 문장 원칙. 빈자리를 채워보세요 — '___은 AI에게, ___은 hook에게.'

맞아요. 판단은 AI에게, 보장은 hook에게. 유연하게 생각하고 결정하는 일은 Claude가 잘하고, '반드시 매번'을 책임지는 일은 코드인 hook이 맡아요. 둘은 경쟁이 아니라 역할 분담이에요.

Claude Code에는 지금 어떤 hook이 걸려 있는지 보는 명령이 있어요. 가게 폴더에서 슬래시 커맨드 /hooks를 쳐보세요.

/hooks — 현재 설정된 hook 목록을 확인해요

아직 직접 만들진 않았어요 — 다음 레슨에서 우리 손으로 hook을 하나 걸어봅니다.

한 줄로

CLAUDE.md는 확률적 부탁이라 가끔 잊혀요. hook은 결정적 코드라 매번 실행돼요. UserPromptSubmit·PreToolUse·PostToolUse·Stop 같은 이벤트에 스크립트를 걸고, exit 2면 차단까지 돼요.

다음 레슨에서

"Hook 실전 — 이 사이트의 실습도 hook으로 돈다"에서, 지금 배운 hook을 실제로 하나 걸어 반찬가게 작업 흐름을 자동화해봐요. 가게는 계속 자랍니다. 🌱