클로드 코드(Claude Code)를 계속 쓰다 보면 비슷한 확인 작업이 반복되는 순간이 있습니다. 예를 들어 명령 실행 전에 한 번 더 점검하고 싶거나, 작업이 끝난 뒤 간단한 후처리를 붙이고 싶을 때가 그렇습니다. 이럴 때 쓰는 기능이 hooks입니다.
이 글은 클로드 코드 hooks 사용법을 처음 보는 기준으로 정리한 글입니다. 복잡한 예제보다 먼저, hooks가 어떤 문제를 줄여주는지, 어떤 이벤트에 연결하는지, 어디까지 자동화하고 어디서 멈추는 편이 좋은지부터 차근차근 설명하겠습니다.
Table of Contents
hooks는 어떤 상황에서 필요한가
공식 문서 기준으로 hooks는 특정 이벤트가 발생했을 때 명령을 실행하도록 설정하는 구조입니다. 즉 클로드 코드 안에서 어떤 작업이 일어나기 전이나 후에, 내가 정한 점검이나 알림을 붙일 수 있습니다.
- 명령 실행 전에 위험한 작업을 한 번 더 점검하고 싶을 때
- 파일 수정 후 간단한 검사나 포맷팅 흐름을 붙이고 싶을 때
- 작업이 끝났을 때 알림이나 로그를 남기고 싶을 때
반복해서 확인하는 흐름이 있을수록 hooks의 체감이 커집니다.
설정은 어디에 두나
hooks는 설정 파일 안에서 관리합니다. 공식 문서에는 아래 위치가 안내되어 있습니다.
~/.claude/settings.json: 사용자 전역 설정.claude/settings.json: 프로젝트 공유 설정.claude/settings.local.json: 로컬 프로젝트 설정
개인 취향에 가까운 자동화는 전역이나 로컬에 두고, 팀 전체가 같이 써야 하는 규칙은 프로젝트 설정에 두는 편이 깔끔합니다.
어떤 이벤트에 걸 수 있나
공식 reference 기준으로 대표적인 이벤트는 PreToolUse, PostToolUse, Notification, UserPromptSubmit입니다. 이름 그대로 보면 이해가 쉽습니다.
PreToolUse: 도구 실행 직전PostToolUse: 도구 실행 직후Notification: 알림 발생 시점UserPromptSubmit: 프롬프트 제출 직후
처음에는 모든 이벤트를 다 만지기보다, 가장 이해하기 쉬운 전후 처리부터 보는 편이 좋습니다.
처음에는 이렇게 생각하면 쉽다
hooks를 어려워하는 이유는 자동화를 너무 크게 보기 때문입니다. 처음에는 “위험한 명령 전에 한 번 멈추기”, “작업 뒤에 검사 하나 붙이기”, “오래 기다릴 때 알림 받기” 정도만 떠올려도 충분합니다.
즉 복잡한 자동화보다, 반복해서 놓치는 습관을 줄이는 보조 장치라고 보면 훨씬 이해가 쉽습니다.
무조건 많이 거는 게 좋은 건 아니다
hooks는 편하지만 과하게 걸면 오히려 흐름이 답답해질 수 있습니다. 모든 작업에 과도한 검사를 붙이면 작업 속도가 떨어지고, 왜 멈췄는지 파악하기도 어려워집니다.
그래서 처음에는 아래 기준이 좋습니다.
- 정말 자주 반복되는 흐름만 자동화하기
- 위험한 작업과 단순 작업을 구분하기
- 팀 전체 규칙과 개인 편의 규칙을 섞지 않기
어떤 사람에게 특히 잘 맞을까
혼자 쓰는 개발자보다, 비슷한 작업을 자주 반복하는 사람에게 특히 잘 맞습니다. 테스트 전 점검, 수정 후 검사, 알림 처리처럼 흐름이 일정할수록 hooks의 의미가 커집니다.
반대로 아직 기본 명령도 익숙하지 않다면 hooks부터 깊게 들어가기보다, 먼저 /config, /permissions, /add-dir 같은 기본 흐름을 익히는 편이 낫습니다.
함께 보면 좋은 글
정리
클로드 코드 hooks는 거창한 기능이라기보다, 반복해서 놓치기 쉬운 흐름을 자동화해 주는 도구에 가깝습니다. 처음에는 모든 것을 자동화하려고 하기보다, 자주 반복되는 전후 처리 한두 개만 먼저 붙이는 편이 훨씬 현실적입니다.
공식 문서에서도 hooks는 설정 파일에 정의된 이벤트 기반 구조로 설명합니다. 따라서 어떤 이벤트에 어떤 명령을 연결할지부터 작게 정리하는 것이 가장 안전한 시작입니다.
참고한 공식 문서
- Anthropic Claude Code Hooks reference
- Anthropic Claude Code Settings
