클로드(Claude) 코드 훅 사용법, settings.json 설정과 실행 시점별 예시

아직도 Claude Code에게 "커밋 전에 테스트 돌려", "이 파일은 건드리지 마"를 매번 다시 말하고, 그래도 가끔 잊어버려서 직접 되돌리고 계신가요? 지침 파일에 적어 둔 규칙은 AI가 읽고 따르려고 노력할 뿐이라, 대화가 길어지면 빠지는 일이 생깁니다.

클로드(Claude) 코드 훅(hooks)은 Claude Code가 도구를 쓰기 전후나 작업을 마칠 때처럼 정해진 시점에 사용자가 지정한 명령을 자동으로 실행하는 기능입니다. AI의 판단에 맡기지 않고 항상 같은 동작이 일어나게 만드는 장치라는 점이 핵심입니다. 이 글은 2026년 10월 공식 문서를 기준으로 훅과 지침 파일·스킬의 차이, 실행 시점별 활용 예, settings.json에 훅을 추가하는 순서, 실패했을 때 작업을 막는 옵션과 비밀정보 주의점을 정리합니다. 마지막에는 다글로로 받아쓴 팀 회의에서 훅으로 만들 규칙을 고르는 방법도 담았습니다.

클로드 코드 훅이란? CLAUDE.md·스킬과 무엇이 다른가요

CLAUDE.md와 스킬은 Claude가 읽고 판단하는 지시문이고, 훅은 Claude Code 프로그램이 직접 실행하는 명령입니다. 그래서 "반드시 지켜야 하는 규칙"은 훅으로, "상황에 맞게 판단할 일"은 지침이나 스킬로 나눕니다.

스킬을 만드는 방법은 클로드 코드 스킬 글에, 지침·도구·권한을 함께 설계하는 개념은 하네스 엔지니어링 글에 정리해 두었습니다.

실행 시점별 훅 활용 예

훅은 이벤트 이름으로 실행 시점을 고릅니다. 처음에는 PreToolUse(도구 실행 전), PostToolUse(도구 실행 후), Stop(응답을 마칠 때), Notification(입력을 기다릴 때) 네 가지만 알아도 대부분의 규칙을 자동화할 수 있습니다.

공식 문서에는 이 밖에도 서브에이전트 종료, 대화 압축, 워크트리 생성 같은 이벤트가 30개 넘게 있습니다. 이벤트 이름은 버전마다 추가되므로 쓰기 전에 공식 훅 문서에서 확인하세요.

settings.json에 훅을 추가하는 순서

훅은 settings.json의 hooks 항목에 "이벤트 → 매처(matcher) → 실행할 명령" 3단계로 적습니다. 매처는 어떤 도구에만 반응할지 고르는 조건으로, Edit|Write처럼 쓰면 파일 수정 도구에만 실행됩니다.

1. 저장 위치 정하기: 모든 프로젝트에 적용할 훅은 ~/.claude/settings.json, 팀과 공유할 훅은 프로젝트의 .claude/settings.json, 나만 쓸 훅은 .claude/settings.local.json에 둡니다. 여러 파일의 훅은 덮어쓰지 않고 합쳐서 실행됩니다.
2. 훅 적기: 파일을 고칠 때마다 자동 포맷하려면 아래처럼 적습니다.
   {"hooks": {"PostToolUse": [{"matcher": "Edit|Write", "hooks": [{"type": "command", "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"}]}]}}
3. 스크립트로 분리하기: 조건이 길어지면 .claude/hooks/ 폴더에 스크립트를 만들고 "$CLAUDE_PROJECT_DIR"/.claude/hooks/protect-files.sh처럼 프로젝트 기준 경로로 부릅니다. 훅은 실행 정보를 JSON으로 표준 입력(stdin)에 받으므로 tool_name, tool_input 값을 읽어 판단합니다.
4. 등록 확인하기: Claude Code에서 /hooks를 입력하면 이벤트별로 등록된 훅과 정의된 파일이 보입니다.
5. 직접 테스트하기: echo '{"tool_name":"Bash","tool_input":{"command":"ls"}}' | ./my-hook.sh로 예시 입력을 넣어 종료 코드를 확인합니다. 자세한 실행 기록은 claude --debug로 봅니다.

매처는 대소문자를 구분합니다. 훅이 실행되지 않으면 /hooks에서 이벤트와 매처 이름이 맞는지 먼저 확인하세요.

훅이 실패할 때 작업을 막는 법과 비밀정보 주의점

훅 스크립트가 종료 코드 2로 끝나면 해당 동작이 막히고, 표준 오류(stderr)에 쓴 이유가 Claude에게 전달됩니다. 종료 코드 0은 통과, 그 밖의 코드는 경고만 남기고 작업을 계속합니다.

• 막을 수 있는 시점: PreToolUse, UserPromptSubmit, Stop 등에서는 종료 코드 2로 동작을 막습니다. PostToolUse는 도구가 이미 실행된 뒤라 되돌리지 못하고, 이유를 Claude에게 알려 다음 행동을 고치게 합니다.
• 실패하면 멈추게 하기: 기본값에서는 훅이 오류를 내거나 시간 제한(timeout)을 넘겨도 작업이 계속됩니다. 검사 훅이 고장 난 사이에 위험한 명령이 통과하면 안 되는 경우에는 훅 항목에 "onFailure": "block"을 넣습니다. 최신 버전에서 추가된 옵션이므로 공식 문서에서 지원 여부를 확인하세요.
• 세밀하게 판단하기: 종료 코드 대신 JSON을 출력하면 permissionDecision 값으로 허용·거부·사용자에게 묻기를 고를 수 있습니다.

훅은 내 계정 권한으로 실행되므로 비밀정보를 특히 조심해야 합니다.

• 토큰·API 키를 settings.json이나 훅 명령에 직접 적지 않습니다. .claude/settings.json은 저장소에 함께 올라가기 때문입니다. 값은 환경변수나 저장소 밖 파일에 두고 스크립트가 경로로 읽게 합니다.
• 훅의 출력은 Claude의 대화 맥락과 디버그 로그에 남습니다. 오류 메시지에 토큰 값이나 전체 요청 내용을 echo하지 않습니다.
• 실행한 명령을 파일로 기록하는 훅은 명령줄에 들어간 비밀번호까지 저장할 수 있으니, 기록 파일 위치를 .gitignore에 넣고 민감한 패턴은 가린 뒤 저장합니다.
• 다른 사람이 만든 훅이나 플러그인을 쓰기 전에는 명령 내용을 직접 읽어 봅니다.

다글로로 받아쓴 팀 회의에서 훅 후보 고르기

좋은 훅은 팀이 반복해서 말하는 규칙에서 나옵니다. 회고나 운영 회의를 다글로로 받아쓰면 화자가 구분된 원문과 요약이 남아, "또 이 실수가 나왔다"는 대목을 근거로 훅 후보를 고를 수 있습니다.

1. 참석자 동의를 받고 회의를 녹음한 뒤 다글로에 올려 받아씁니다.
2. 몇 주 치 회의 기록을 한 보드에 모으고, 보드챗에 "회의에서 두 번 이상 나온 작업 규칙과 실수를 목록으로 정리해 줘"라고 묻습니다.
3. 답변을 원문과 바로 대조해, 매번 같은 방식으로 지켜야 하는 규칙(파일 보호, 테스트, 알림)은 훅으로, 판단이 필요한 규칙은 CLAUDE.md나 스킬로 나눕니다.

회의마다 "반복된 규칙과 실수" 형식으로 정리하고 싶다면 그 요청을 다글로 '내 템플릿'에 저장해 두세요. 다글로가 프롬프트를 기억해 녹음이 끝날 때마다 그 형식으로 자동 요약합니다.

정리하면, 꼭 지켜야 하는 규칙 하나를 골라 PreToolUse나 PostToolUse 훅으로 만들고, /hooks와 예시 입력으로 확인한 뒤 차례로 늘려 가면 Claude Code에게 같은 말을 반복할 일이 줄어듭니다.

#클로드코드훅 #ClaudeCode #클로드코드 #hooks #settingsjson #PreToolUse #하네스엔지니어링 #다글로

👉 팀 회의 무료로 받아쓰기 시작하기