Claude Code 훅 레시피 5가지: 프롬프트로 부탁하지 말고 코드로 강제하세요

핵심 요약: 훅은 특정 이벤트(파일 수정 후, 명령 실행 전 등)에 자동으로 실행되는 스크립트입니다. 프롬프트("수정하면 꼭 린트 돌려줘")는 모델이 잊을 수 있지만 훅은 코드라서 100% 실행됩니다. 이 글은 실전에서 바로 쓰는 레시피 5가지 — ① 수정 후 자동 린트·포맷 ② 위험 명령 차단 ③ 커밋 전 테스트 게이트 ④ 보호 파일 수정 경고 ⑤ 긴 작업 완료 알림. CLAUDE.md에서 "지시"로 있던 것들을 훅으로 옮기는 것이 규칙 파일 다이어트의 핵심이기도 합니다.

이 글에서 다루는 내용: 훅의 동작 구조, 레시피 5가지(이벤트·동작·효과), 작성 팁.

훅의 구조: 이벤트 + 스크립트

설정에서 "어떤 이벤트에"(도구 사용 전/후, 세션 시작 등) "어떤 명령을" 실행할지 연결합니다. 스크립트는 셸 명령이면 뭐든 되고, 종료 코드로 작업을 차단할 수도 있습니다(실행 전 훅에서 실패 반환 = 그 동작 중단). 개념 비교는 서브에이전트·훅·스킬 글에서 다뤘고, 이 글은 레시피 편입니다.

레시피 ① 수정 후 자동 린트·포맷

이벤트: 파일 수정 후 → 동작: 해당 파일에 포매터·린터 실행(예: ruff format, prettier). 효과: "AI 코드 스타일이 제각각" 문제가 소멸합니다. CLAUDE.md의 스타일 규칙 절반을 지울 수 있는, 가성비 최고의 첫 훅입니다.

레시피 ② 위험 명령 차단

이벤트: 셸 명령 실행 전 → 동작: 패턴 검사(rm -rf, drop table, 프로덕션 배포 명령, migrate 등)에 걸리면 실패 반환으로 차단. 효과: "마이그레이션 실행 금지"를 부탁이 아니라 물리 법칙으로 만듭니다. 자동 승인 범위를 넓혀 쓰는 사람일수록 이 훅이 보험입니다.

레시피 ③ 커밋 전 테스트 게이트

이벤트: git commit 실행 전 → 동작: 관련 테스트 실행, 실패 시 커밋 차단. 효과: "테스트 통과 상태로 보고"가 강제됩니다. 에이전트가 커밋까지 하는 워크플로라면 필수이고, 아니라도 빨간 상태로 멈춰 있는 걸 방지합니다.

레시피 ④ 보호 파일 수정 경고

이벤트: 파일 수정 전 → 동작: 경로 검사(마이그레이션 폴더, .env, 인프라 설정 등 보호 목록)에 걸리면 차단 또는 경고. 효과: "건드리면 안 되는 곳"의 명단화. 레거시 작업(Django 리팩토링 기록)에서 특히 값집니다.

레시피 ⑤ 긴 작업 완료 알림

이벤트: 작업/세션 종료 시 → 동작: Slack 웹훅이나 OS 알림 호출. 효과: 덩어리 작업을 걸어두고 다른 일을 할 때 "끝났나?" 하고 들여다보는 낭비가 사라집니다. 위임형 워크플로(조합 워크플로)의 마감재 같은 훅입니다.

작성 팁 3가지

① 차단은 메시지와 함께. 왜 막혔는지 출력해야 에이전트가 우회로를 스스로 찾습니다("마이그레이션은 사람이 실행함. 파일 생성까지만 할 것"). ② 느린 훅 주의. 수정할 때마다 전체 테스트를 돌리면 에이전트가 기어갑니다 — 수정 후엔 빠른 검사(린트), 커밋 전엔 무거운 검사(테스트)로 나누세요. ③ 팀 공유. 훅 설정을 저장소에 커밋하면 팀 전체 에이전트가 같은 규율로 일합니다.

자주 묻는 질문 (FAQ)

Q. 훅 때문에 에이전트가 막혀서 진행을 못 하면요?

A. 차단 메시지를 명확히 쓰면 에이전트가 대안 경로로 진행합니다. 그래도 막히는 상황이 반복되면 차단 대신 "경고 + 계속"으로 낮추는 조정이 가능합니다.

Q. 다섯 개 중 하나만 만든다면?

A. ①(자동 린트)입니다. 만들기 가장 쉽고 매일 체감되며, 스타일 관련 재지시가 사라져 사용량도 아낍니다.

Q. Cursor에도 훅이 있나요?

A. Cursor도 hooks를 지원합니다(Pro 기능 목록의 hooks). 개념은 동일하므로 이 레시피들의 발상을 그대로 옮길 수 있습니다.

한눈에 보는 요약

반드시 지켜져야 하는 것은 프롬프트가 아니라 훅으로: 린트(품질), 명령 차단(안전), 테스트 게이트(검증), 보호 파일(경계), 완료 알림(흐름). 첫 훅은 자동 린트부터 — 10분 투자로 매일 돌아옵니다.

함께 보면 좋은 글

서브에이전트·훅·스킬: 언제 뭘 써야 할까?
CLAUDE.md 작성법 (훅으로 다이어트)
슬래시 명령 총정리

참고 자료

Claude Code 공식 문서 - Hooks
Steering Claude Code (공식 블로그)