Claude Code 훅(hooks) 활용: 커밋 메시지 규칙·자동 포맷·알림을 강제하는 자동화 패턴

Claude Code를 쓰다 보면 “작업이 끝나면 포맷을 실행해줘”, “커밋 전에는 메시지를 검사해줘” 같은 요구가 반복됩니다. 이때 매번 프롬프트로 부탁하는 대신 훅(hooks)을 두면 정해진 시점에 자동 동작을 끼워 넣을 수 있습니다.

핵심은 훅이 Claude의 기억이나 의지가 아니라, Claude Code 하네스가 특정 이벤트를 감지해 실행하는 자동화라는 점입니다. 따라서 좋은 훅은 똑똑한 지시문보다 명확한 이벤트, 제한된 권한, 예측 가능한 실패 처리가 중요합니다.

1. 훅은 Claude의 기억이 아니라 하네스의 트리거다

Claude가 하는 일과 훅이 하는 일

Claude는 코드를 읽고 수정하거나 명령 실행을 제안합니다. 훅은 그 작업의 전후에 미리 정한 명령이나 스크립트를 실행합니다. 예를 들어 파일 수정 뒤 포맷터를 실행하고, 커밋 직전에는 메시지 형식을 검사하며, 작업이 끝나면 데스크톱 알림을 보낼 수 있습니다.

이 구분을 해두면 “AI가 알아서 기억하겠지”라는 기대를 줄일 수 있습니다. 반복 규칙은 프롬프트보다 훅에, 프로젝트의 설명과 판단 기준은 CLAUDE.md 작성법: AI가 내 코드 컨벤션을 기억하게 만드는 프로젝트 규칙 파일 가이드에 두는 식으로 역할을 나누면 관리가 쉽습니다.

먼저 자동화 경계를 정하기

훅으로 자동화하기 좋은 일은 결과가 비교적 객관적인 작업입니다.

• 파일 수정 후 포맷과 정적 검사 실행
• 커밋 메시지의 접두사나 형식 확인
• 민감한 파일 변경 여부 감지
• 장시간 작업 완료 후 알림 전송

반대로 제품 방향 결정, 데이터 삭제, 배포처럼 되돌리기 어려운 일은 자동 실행 범위를 좁히는 편이 안전합니다. Claude Code 버전에 따라 이벤트 이름과 설정 방식이 다를 수 있으므로 실제 적용 전 공식 문서에서 지원 범위를 확인하세요.

2. “X할 때마다 Y”를 이벤트와 행동으로 번역하기

훅을 만들 때는 자연어 요구를 그대로 적기보다 언제 → 무엇을 → 실패하면 어떻게의 세 칸으로 바꿔 적습니다.

커밋 직전: 규칙을 검사하는 훅

예를 들어 “커밋 메시지를 깔끔하게 유지한다”는 목표는 다음처럼 구체화할 수 있습니다.

• 언제: 커밋 명령이 실행되기 직전
• 무엇을: 메시지에 정한 형식과 필요한 설명이 있는지 검사
• 실패하면: 커밋을 막고 수정 방법을 출력

검사 훅은 파일을 고치지 않는 것이 좋습니다. 자동으로 메시지를 바꾸거나 파일을 수정하면 의도하지 않은 결과를 놓칠 수 있기 때문입니다. 포맷팅처럼 결과가 예측 가능한 작업은 별도의 자동 수정 단계로 두고, 수정 뒤에는 다시 검사하는 흐름을 만들면 됩니다.

작업 후: 포맷·검사·알림을 분리하기

“작업 완료 후 모든 것을 실행”하는 하나의 거대한 훅보다 포맷, 테스트, 알림을 분리한 구성이 디버깅하기 쉽습니다. 포맷 단계가 실패했는지, 테스트가 실패했는지, 알림만 전달되지 않았는지를 각각 확인할 수 있기 때문입니다.

알림은 성공을 보장하는 장치가 아니라 작업 상태를 알려주는 보조 수단으로 취급하세요. 중요한 결과는 터미널 출력과 로그에 남기고, 알림에는 “검사 완료”나 “추가 확인 필요”처럼 짧은 상태만 전달하는 편이 좋습니다. 반복 프롬프트를 수동 버튼으로 묶는 방식은 Claude Code 슬래시 커맨드 직접 만들기: 반복 프롬프트를 작업 버튼처럼 쓰는 법과 함께 비교해보면 자동 실행과 수동 실행의 차이가 선명해집니다.

3. 권한과 실패를 설계하는 3단 안전장치

읽기·수정·외부효과를 나누기

모든 훅에 같은 권한을 주지 말고 작업의 영향 범위로 나눠보세요.

특히 비밀값을 읽거나 네트워크로 전송하는 스크립트는 훅에 쉽게 넣지 않는 것이 좋습니다. 훅이 어떤 환경변수와 디렉터리에 접근하는지 먼저 확인하고, 프로젝트에 필요한 최소 권한만 허용하세요.

실패 시 멈출지 기록할지

실패하면 항상 전체 작업을 중단해야 하는 것은 아닙니다. 커밋 메시지 검사나 타입 검사는 보통 중단이 유용하지만, 데스크톱 알림이나 선택적 로그 전송은 본 작업을 막지 않아도 됩니다.

판단 기준은 간단합니다. 실패를 무시했을 때 잘못된 결과가 저장되는가? 그렇다면 중단하고, 단지 편의 기능이 사라지는 정도라면 기록 후 계속 진행하는 방식을 고려하세요. 승인 모드와 자동 실행의 경계는 Codex 샌드박스와 승인 모드 이해하기: 자동 실행을 어디까지 허용할까에서도 비슷한 관점으로 살펴볼 수 있습니다.

4. 1인 빌더용 도입 순서

1단계: 가장 작은 반복 작업 하나 선택하기

처음부터 포맷, 테스트, 커밋, 알림을 모두 연결하지 마세요. 실패 원인을 찾기 어려워집니다. 먼저 파일 수정 후 포맷처럼 실행 결과가 명확하고 되돌리기 쉬운 작업 하나를 고릅니다.

2단계: 로그와 수동 실행 경로 남기기

훅이 실행됐다는 표시, 실행한 명령, 종료 결과를 확인할 수 있어야 합니다. 훅이 작동하지 않았을 때 수동으로 같은 검사를 실행할 명령도 문서에 남겨두세요. 자동화는 수동 대체 경로가 있을 때 운영 부담이 줄어듭니다.

3단계: 팀원이 아니라 미래의 나를 기준으로 설명하기

1인 프로젝트라도 몇 주 뒤의 나는 낯선 팀원과 비슷합니다. 훅 이름과 목적, 실행 시점, 실패 시 행동을 규칙 파일이나 개발 문서에 짧게 적으세요. 조코헌트에서 개발자 도구 분야를 선택한 프로덕트가 23%라는 점을 보면, 이런 개발 생산성 자동화는 특정 팀만의 관심사가 아니라 1인 빌더에게도 충분히 실용적인 영역입니다.

5. 훅 운영 체크리스트

출시 전에는 아래 항목만 확인해도 과한 자동화를 상당히 줄일 수 있습니다.

• 훅마다 실행 시점과 목적이 한 문장으로 설명되는가
• 읽기·수정·외부효과 권한을 구분했는가
• 실패했을 때 중단할 작업과 기록만 남길 작업을 정했는가
• 훅이 수정한 파일을 쉽게 확인할 수 있는가
• 훅 없이도 같은 검사를 수동 실행할 수 있는가
• 버전이나 운영체제가 달라져도 오류 메시지가 이해 가능한가

좋은 훅은 개발자를 대신해 판단하는 장치가 아니라, 자주 놓치는 작은 규칙을 일정하게 지키게 하는 안전망입니다. “X할 때마다 Y해줘”라는 문장이 반복해서 등장한다면, 그 규칙을 이벤트와 행동으로 분해해 가장 작은 훅부터 붙여보세요.