Claude Code의 Hooks 실용 설정: '매번 요청하는 것'을 Hook으로 자동화하기

Claude Code를 한동안 사용하다 보면, 이런 '반복적인 수작업'이 쌓이지 않나요?

• 파일을 편집시킨 후, 매번 포맷터나 Lint를 직접 적용하고 있다.
• '위험한 명령어만은 절대 막고 싶다'는 것을 매번 확인에 의존하고 있다.
• 어떤 명령어를 실행했는지 나중에 추적할 수 있도록 로그를 남기고 싶다.
• 작업이 한 단계 마무리되었을 때, 정해진 처리를 자동으로 실행하고 싶다.

이러한 것들은 **Hooks(훅)**로 자동화할 수 있습니다. Hooks는 'Claude Code가 특정 이벤트가 발생했을 때, 사용자가 미리 정한 명령어를 자동으로 실행하는' 메커니즘입니다. 본 기사에서는 Hooks의 기본 구조와 바로 사용할 수 있는 실용 설정을 정리했습니다.

주의: Hooks의 사양(이벤트 이름, 출력 필드 등)은 변경될 수 있습니다. 본 기사는 작성 시점(2026년 6월)의 공식 문서를 참조하고 있지만, 실제로 설정할 때는 최신 문서를 확인해 주십시오.

Hooks는 settings.json에 작성하는 설정입니다. '언제(이벤트)', '어떤 도구에 대해(matcher)', '무엇을 실행할지(command)' 세 가지를 지정합니다.

대표적인 이벤트는 다음과 같습니다 (작성 시점 기준).

이벤트	발생 타이밍
PreToolUse	도구를 실행하기 직전
PostToolUse	도구를 실행한 직후
UserPromptSubmit	사용자가 프롬프트를 전송했을 때
Stop	Claude가 응답을 끝내려고 할 때
SubagentStop	서브 에이전트가 종료하려고 할 때

핵심은, PreToolUse는 실행을 막을 수 있다는 점입니다. '이 명령어는 위험하니 실행시키지 않겠다'라는 제어에 사용할 수 있습니다. 반면 PostToolUse는 '실행한 후에 작동한다'는 점에서 포맷팅이나 로깅에 적합합니다.

Hooks는 프로젝트 단위라면 .claude/settings.json에 작성합니다. 최소 구성은 다음과 같은 형태입니다.

{
"hooks": {
"PostToolUse": [
...

읽어보면 이렇습니다.

• PostToolUse: 도구 실행 직후에 - `

하고 싶은 일	사용하는 이벤트	제어 방법
편집 후 포맷팅·Lint	PostToolUse (matcher: Edit|Write)	명령어를 실행하기만 하면 됨
위험한 명령어 차단	PreToolUse (matcher: Bash)	스크립트로 exit 2
실행 로그 남기기	PostToolUse (matcher: Bash)	명령어를 실행하기만 하면 됨

생각하는 방식은 간단합니다. "멈추고 싶다"면 PreToolUse + exit 2, "한 후에 처리하고 싶다"면 PostToolUse 입니다.

처음부터 전부 넣으려 하지 말고, 가장 스트레스가 되는 한 가지부터 시작하는 것을 추천합니다. 많은 사람에게는 "편집 후 자동 포맷팅"이 효과를 실감하기 쉬운 입구입니다.

또한, Hook 스크립트는 일반적인 쉘 스크립트(Shell Script)이므로, 먼저 로컬에서 단독으로 실행하여 기대한 대로 동작하는지 확인한 후 등록하는 것이 안전합니다. PreToolUse를 사용하여 차단(Block) 계열을 넣는 경우에는, 실수로 필요한 작업까지 멈추지는 않는지 테스트용 명령어로 동작을 살펴본 뒤 실전에 투입하면 안심할 수 있습니다.

• Hooks는 "이벤트가 발생하면, 스스로 결정한 명령어를 자동 실행하는" 메커니즘
• PostToolUse는 "수행 후 처리" (포맷팅·로그)에 적합
• PreToolUse는 "수행 전 체크"에 적합. exit 2로 조작을 중단할 수 있음
• 설정은 .claude/settings.json에 작성하며, matcher로 도구를 좁힘

우선 편집 후 자동 포맷팅부터 시작해서, 익숙해지면 위험한 명령어 가드나 로그 기록을 추가해 나가면 무리 없이 "매번 하는 수작업"을 줄일 수 있습니다.

Hooks는 "매번 하고 있는 수작업"을 찾아 자동화하는 메커니즘입니다. 그 전 단계로서 CLAUDE.md나 개발 진행 방식의 틀이 갖춰져 있으면 무엇을 자동화해야 할지 더 잘 보입니다. 제가 사용 중인 스킬을 무료로 공개하고 있습니다.

무료 스타터 (GitHub · CC BY 4.0):

CLAUDE.md 설계 · 계획 우선 개발 (PIV) · AI 커밋 전략 · 애자일(Agile) 프롬프트 설계의 4가지 스킬이 일본어·영어로 포함되어 있습니다. 개발의 틀을 먼저 정돈한 뒤, 반복되는 작업을 Hooks로 넘겨주면 매끄럽게 진행할 수 있습니다. 우선 무료 리포지토리(Repository)부터 시도해 보세요.

최신 팁은 X에서도 발신하고 있습니다: @k___n___t_1125