터미널 창을 켜 둔 채 답을 기다린 적 있으신가요?
Claude Code의 훅을 쓰면 AI가 내 확인을 기다리는 순간에만 알림을 띄울 수 있습니다. 파일을 고친 뒤 정리하거나, 건드리면 안 되는 파일을 막는 일도 같은 방식으로 연결할 수 있죠.
핵심 내용
- 훅은 Claude Code가 정해진 시점에 실행하는 사용자 지정 셸 명령입니다. AI가 알아서 판단해 주기를 기다리지 않아도, 지정한 작업을 실행하게 만들 수 있습니다.
- 가볍게 시작하기 좋은 기능은 Notification 훅입니다. Claude가 입력이나 권한을 기다릴 때만 알림을 받아, 터미널을 계속 들여다볼 일이 줄어듭니다.
- 훅 설정은 사용자 전체에 적용하는 ~/.claude/settings.json 또는 프로젝트의 .claude/settings.json에 넣습니다. 기존 hooks 항목이 있다면 통째로 덮어쓰지 않아야 합니다.
- 파일 자동 정리, 보호 파일 편집 차단, 대화 내용 압축 뒤 프로젝트 규칙 다시 넣기처럼 반복되는 규칙도 훅으로 만들 수 있습니다.
- 권한 자동 승인은 범위를 아주 좁혀야 합니다. 모든 도구 요청에 적용되는 설정은 파일 쓰기와 셸 명령까지 자동으로 통과시킬 수 있습니다.
왜 터미널 대기 시간이 답답할까
Claude Code에 일을 맡겨 두고 다른 문서를 보다가, 언제 내 확인이 필요한지 몰라 터미널을 다시 열어 본 적 있으시죠? 작업이 끝난 뒤 추가 지시를 기다리거나 권한 확인이 필요한 순간을 놓치면 흐름이 끊깁니다. 계속 화면을 지켜보는 방법은 단순하지만, 다른 일을 하기가 어렵습니다.
클로드 코드 훅은 이런 특정 시점에 미리 정한 명령을 실행하는 장치입니다. AI가 어떤 행동을 고를지 기대하는 기능과 달리, 조건만 맞으면 정해 둔 작업이 실행됩니다. 공식 도움말에는 알림 보내기, 파일 편집 뒤 서식 정리, 실행 전 명령 차단, 세션 시작 때 프로젝트 정보 넣기 같은 예시가 나옵니다.
처음부터 복잡한 규칙을 만들 필요는 없습니다. Claude가 입력을 기다릴 때 알림을 받는 Notification 훅 하나만 설정해도 쓸모를 바로 느낄 수 있거든요. 터미널은 작업을 맡기는 곳으로 두고, 확인이 필요할 때만 돌아오는 흐름을 만들어 보세요.
훅은 사용자 전체에 적용할 수도 있고, 특정 프로젝트 안에서만 쓸 수도 있습니다. 개인 알림처럼 어느 작업에서나 필요한 기능은 사용자 설정 파일에, 특정 저장소의 파일 보호 규칙처럼 프로젝트에만 필요한 기능은 프로젝트 설정 파일에 두면 구분하기 쉽습니다.
꿀팁 · 처음에는 Notification 훅 하나만 켜고, 알림이 오는 타이밍이 내 작업 흐름에 맞는지 확인하세요.
알림 훅은 어디에 설정하나
시작할 곳은 ~/.claude/settings.json 파일입니다. 파일이 없다면 새로 만들면 됩니다. 파일 안에 hooks 블록을 넣고, 그 안에 Notification 이벤트용 설정을 추가하는 방식입니다. 이미 hooks 키가 있다면 기존 내용을 지우고 새 객체로 바꾸면 안 됩니다. 기존 이벤트와 같은 단계에 Notification만 더해야 합니다.
공식 안내의 첫 예시는 macOS에서 osascript로 데스크톱 알림을 보내는 방식입니다. Linux와 Windows PowerShell도 각 운영체제의 기본 알림 명령을 쓰도록 안내합니다. 사용하는 운영체제에 맞는 공식 예시를 그대로 설정 파일에 넣는 편이 안전합니다. 명령 일부를 섞어 쓰면 알림이 조용히 실패할 수 있습니다.
설정을 저장한 뒤 Claude Code 프롬프트에서 /hooks를 입력하세요. 훅 목록 화면이 열리고, Notification 아래에 방금 추가한 훅이 보여야 합니다. 보이지 않는다면 설정 파일 위치와 JSON의 쉼표·괄호, Notification을 넣은 위치부터 다시 확인해 보세요.
작동 시험도 순서가 있습니다. Esc로 명령줄 화면으로 돌아간 뒤 상태 표시줄에 manual mode on이 나타날 때까지 Shift+Tab을 누릅니다. 그다음 Claude에게 권한이 필요한 작업을 요청하고 터미널 밖의 다른 창으로 이동하세요. Claude가 확인을 기다리는 순간 알림이 뜨는지 보면 됩니다. macOS에서 알림이 보이지 않는다면 Script Editor의 알림 권한도 점검해야 합니다.
꿀팁 · 설정한 뒤에는 /hooks를 먼저 실행하세요. 목록에 보이는지만 확인해도 알림을 기다리며 원인을 추측할 일이 줄어듭니다.
클로드 코드 훅을 이렇게 써 보세요
알림 다음으로 자주 쓰는 흐름은 파일 편집 뒤 정리입니다. Claude가 Edit 또는 Write 도구로 파일을 수정한 뒤에만 실행되도록 PostToolUse 이벤트와 Edit|Write matcher를 연결할 수 있습니다. 공식 예시는 수정한 파일 경로를 꺼내 Prettier로 서식을 맞춥니다. 프로젝트에서 이미 Prettier를 쓴다면, 수정할 때마다 같은 정리 기준을 적용하는 용도입니다.
파일을 바꾸는 경로가 편집 도구뿐인 것은 아닙니다. Claude가 셸 명령으로 파일을 다시 쓸 수도 있죠. 어떤 방식으로 고쳤는지와 무관하게 특정 파일 변경에 반응해야 한다면 FileChanged 훅이 더 맞을 수 있습니다. 반대로 모든 파일을 대상으로 하면 불필요한 실행이 늘 수 있으니, 감시할 파일 이름은 필요한 것만 정하는 편이 좋습니다.
보호 규칙도 훅으로 만들 수 있습니다. .env, package-lock.json, .git 안의 파일처럼 실수로 바뀌면 곤란한 대상을 정하고, Edit 또는 Write 전에 PreToolUse 훅으로 검사합니다. 보호 스크립트가 차단 신호를 보내면 Claude Code는 편집을 실행하지 않고 Claude에게 막힌 이유를 전달합니다. 단순히 ‘수정하지 마세요’라고 요청하는 것보다 규칙을 더 확실히 적용하는 방법이죠.
대화가 길어져 Claude의 대화 공간이 정리될 때 프로젝트 규칙이 희미해질까 걱정된다면 SessionStart 훅도 쓸 수 있습니다. compact 조건에서 프로젝트 규칙이나 최근 작업 내용을 다시 넣는 식입니다. 반면 모든 세션 첫머리에 늘 필요한 설명이라면 CLAUDE.md를 고려하라는 것이 공식 안내의 구분입니다.
"Claude가 입력을 기다릴 때만 데스크톱 알림을 보내도록 Notification 훅을 설정해 주세요."
"이 프로젝트에서 .env와 .git 안의 파일은 수정 전에 차단하는 규칙을 훅으로 만들고 싶습니다."
"파일을 Edit 또는 Write로 바꾼 뒤에만 기존 Prettier 명령을 실행하도록 설정해 주세요."
꿀팁 · 자동 서식 정리는 Edit|Write처럼 대상을 먼저 좁히고, 보호 규칙은 실제로 .env 편집을 요청해 차단되는지 시험해 보세요.
자동 승인 전에 확인할 점
훅은 여러 개가 같은 시점에 맞으면 함께 실행될 수 있습니다. 예를 들어 하나는 셸 명령을 기록하고, 다른 하나는 위험한 명령을 막도록 만들 수 있습니다. 차단을 반환한 훅이 있어도 다른 훅 자체의 실행이 멈추는 것은 아닙니다. 기록 훅은 이미 로그를 남길 수 있으므로, 한 규칙의 거부가 다른 규칙의 부작용까지 없애 줄 것이라고 기대하면 안 됩니다.
훅은 Claude Code와 입력, 출력, 종료 상태로 소통합니다. 일반적으로 문제가 없다는 뜻은 종료 코드 0이고, 작업을 막을 때는 종료 코드 2와 이유 메시지를 씁니다. 다만 모든 이벤트가 종료 코드 2로 멈추는 것은 아닙니다. 예를 들어 SessionStart처럼 오류 메시지를 보여 주고 계속 진행하는 경우도 있어서, ‘차단해야 하는 작업’에 해당 이벤트가 맞는지 확인해야 합니다.
JSON으로 더 구체적인 결정을 돌려줄 수도 있습니다. 특히 PreToolUse에서는 거부, 사용자에게 다시 묻기, 허용 같은 선택을 낼 수 있습니다. 가장 조심할 부분은 자동 허용입니다. matcher를 비워 두거나 .*로 넓히면 파일 쓰기와 셸 명령을 포함한 모든 도구 권한 요청이 자동 승인될 수 있습니다. 처음에는 ExitPlanMode처럼 공식 예시처럼 범위가 제한된 대상에만 적용하세요.
설정 파일을 바꾼 시점을 남기는 ConfigChange 훅도 있습니다. 외부 편집기나 다른 프로세스가 설정 또는 스킬 파일을 수정할 때 기록하거나 차단하는 용도입니다. 혼자 쓰는 가벼운 알림 훅부터 시작한다면 당장 필요하지 않을 수 있습니다. 그래도 설정이 예상과 다르게 바뀌었을 때 추적할 수 있다는 점은 기억해 둘 만합니다.
훅 명령 예시에서 JSON 값을 다룰 때 jq가 필요할 수 있습니다. 공식 안내의 Bash 예시는 jq로 입력 데이터를 읽습니다. 명령이 실패한다면 훅 자체보다 jq 설치 여부와 JSON 출력 형식부터 확인하는 편이 빠릅니다.
꿀팁 · 자동 승인 설정은 matcher를 비워 두지 말고, 먼저 /hooks에서 적용 범위를 확인한 뒤 한 가지 작업으로 시험하세요.
그래서 나에게 무엇이 달라질까
클로드 코드 훅을 쓰면 AI에게 같은 주의를 반복해서 요청하는 대신, 확인·정리·차단이 필요한 순간을 규칙으로 분리할 수 있습니다. 비개발자도 알림 훅부터 시작하면 기다리는 시간이 줄었다는 변화를 느끼기 쉽습니다. 1인 개발자라면 프로젝트마다 지켜야 할 파일 규칙을 작업 흐름에 붙여 둘 수 있습니다.
내일 바로 써먹기
- ~/.claude/settings.json을 열어 기존 hooks 항목이 있는지 확인하고, 운영체제에 맞는 Notification 훅 예시를 추가하세요.
- Claude Code에서 /hooks를 입력해 Notification 아래에 훅이 표시되는지 확인하세요.
- Shift+Tab으로 manual mode on을 표시한 뒤, 권한이 필요한 작업을 요청해 알림을 시험하세요.
용어사전
- Hooks · Claude Code의 특정 작업 시점에 사용자가 정한 명령을 실행하는 기능입니다. 알림, 파일 검사, 자동 정리 같은 반복 규칙을 붙일 수 있습니다.
- Notification · Claude가 입력이나 권한 확인을 기다리는 상황에서 발생하는 훅 이벤트입니다. 데스크톱 알림을 보내는 용도로 쓸 수 있습니다.
- matcher · 훅이 언제 실행될지를 더 좁히는 조건입니다. 예를 들어 Edit|Write는 파일 편집 도구를 썼을 때만 반응하게 합니다.
- PreToolUse · Claude가 도구를 실행하기 직전에 발생하는 이벤트입니다. 민감한 파일 편집이나 특정 명령을 막는 데 사용할 수 있습니다.
- PostToolUse · Claude가 도구 실행을 마친 직후 발생하는 이벤트입니다. 파일 수정 뒤 서식을 정리하는 작업에 맞습니다.
- jq · JSON 형식의 데이터를 명령줄에서 읽고 처리하는 도구입니다. 공식 Bash 예시에서 수정한 파일 경로를 꺼낼 때 사용합니다.
출처
- 원문: Claude Code 공식 도움말 · https://code.claude.com/docs/ko/hooks-guide