CLAUDE.md에 적어둬도 AI가 가끔 무시하나요? /hooks로 '꼭 할 일'을 무조건 자동 실행시키기

"커밋 전에 꼭 검사 돌려줘"라고 CLAUDE.md(클로드 코드의 규칙 파일)에 적어뒀는데, AI가 가끔 그냥 넘어가버린 적 있나요? CLAUDE.md는 어디까지나 '부탁'이라, 100% 지켜진다는 보장이 없어요. 정말 빠뜨리면 안 되는 규칙이라면, 안내가 아니라 강제가 필요합니다. /hooks는 그걸 해주는 명령이에요. 정해진 순간에 무조건 자동 실행되는 규칙을 거는 겁니다. 고급 기능이라 입문 단계라면 '꼭 지켜야 할 규칙엔 이런 게 있다' 정도로 알아두면 됩니다.

정의

/hooks는 특정 상황에서 자동 실행되도록 걸어둔 '훅(hook)' 설정을 보는 명령입니다.

'훅(hook)'이란 정해진 시점이 되면 무조건 실행되는 자동 규칙이에요. '갈고리'라는 뜻 그대로, 특정 순간(예: 커밋하기 직전)에 걸려서 정해진 명령을 자동으로 끌어다 실행합니다.

CLAUDE.md와 비교하면 차이가 분명해요.

• CLAUDE.md = 안내: "이렇게 해줘"라는 부탁. AI가 상황을 보고 따르긴 하지만, 가끔 빠뜨릴 수 있습니다.
• 훅 = 강제: "이 시점엔 무조건 이걸 실행한다"는 규칙. AI의 판단과 무관하게 항상 실행됩니다.

즉 '반드시 지켜야 하는 일'은 훅으로 걸어야 확실합니다.

사용법 (난이도별)

기초 — 훅 설정 보기

대화창에 입력합니다.

/hooks

입력하면 현재 걸려 있는 훅 설정 목록이 화면에 뜹니다. "어떤 시점에 어떤 명령이 자동 실행되도록 돼 있는지"를 확인하는 거예요. 처음엔 비어 있을 텐데, 여기서 어떤 훅이 걸려 있는지 점검하는 용도로 씁니다.

응용 — 훅으로 걸 규칙 정하기

훅을 새로 거는 건 대화로 부탁할 수 있어요. 예를 들어 이렇게요.

커밋하기 전에 항상 lint 검사를 자동으로 돌리도록 훅으로 걸어줘

이렇게 하면 '커밋 직전'이라는 시점에 'lint 검사 실행'이라는 명령이 묶입니다. (lint는 코드의 형식·오류를 점검하는 검사예요.) 그 뒤로는 커밋할 때마다 AI가 까먹든 말든 검사가 무조건 먼저 실행됩니다. /hooks로 그 설정이 잘 걸렸는지 확인하면 돼요.

흔한 함정 — /hooks는 '보는' 명령, 거는 건 설정

헷갈리기 쉬운 지점이에요. /hooks라고 입력한다고 훅이 새로 만들어지는 게 아닙니다. /hooks는 지금 걸린 훅을 보여주는 명령이에요.

• 보기: /hooks → 현재 설정 확인.
• 걸기: 대화로 "~를 훅으로 걸어줘"라고 요청하거나, 설정 파일에 직접 추가.

그리고 한 가지 더. 훅은 강제력이 센 만큼 잘못 걸면 매번 의도치 않은 명령이 실행될 수 있어요. 그러니 정말 '항상 실행돼야 하는 일'에만 신중하게 거는 게 좋습니다. 어쩌다 한 번 하면 되는 일은 굳이 훅으로 만들 필요가 없어요.

실전 사례

테스트를 안 돌리고 커밋하는 일이 반복돼서, CLAUDE.md에 "커밋 전 검사 실행"을 적어뒀습니다. 그런데도 가끔 그냥 넘어가더라고요. '안내'라서 100% 지켜지지 않았던 거죠. 그래서 아예 훅으로 걸었습니다.

커밋 전에 자동으로 검사를 실행하는 훅 걸어줘

그 뒤로는 단 한 번도 검사가 빠지지 않았어요. AI의 판단에 맡기지 않고 '강제'로 고정하니, "이번엔 빠뜨렸네" 하는 일이 사라졌습니다. 반드시 지켜야 하는 규칙은 안내가 아니라 강제여야 한다는 걸 체감했죠.

이렇게 더 씁니다

• 자동 실행 규칙: 특정 시점에 명령을 강제로 실행시킵니다.
• 커밋 전 검사: 'commit 전 lint·테스트' 같은 걸 못 어기게 고정.
• CLAUDE.md와 역할 분담: 가벼운 권장 사항은 CLAUDE.md(안내), 절대 빠뜨리면 안 되는 건 훅(강제).
• 반드시 할 일에만: AI 판단에 맡기고 싶지 않은 핵심 규칙에 아껴 씁니다.

팁: 모든 규칙을 훅으로 걸 필요는 없어요. 대부분은 CLAUDE.md 안내로 충분합니다. '이거 빠지면 사고 난다' 싶은 한두 개만 훅으로 거는 게, 관리도 쉽고 의도치 않은 실행도 막아줍니다.

정리

핵심은 한 문장입니다. 반드시 지켜야 하는 일은 안내가 아니라 훅으로 강제하라. CLAUDE.md는 부탁이라 가끔 무시될 수 있지만, 훅은 정해진 시점에 무조건 실행됩니다. '꼭 해야 하는 일'을 AI의 판단에 맡기고 싶지 않을 때, 훅이 가장 확실한 안전장치예요.

기준: Claude Code v2.1.154 (2026.05)