Claude Code 훅 작성 가이드

무엇을 해주나

• CLAUDE.md의 '문서상 규칙'으로는 반복 위반되는 행동을 훅(shell 가드)으로 구조적으로 차단하도록 설계를 잡아줍니다.
• 훅 종류별 계약을 정리해 줍니다: PreToolUse(exit 2 = 차단, stderr가 모델에게 보이는 메시지), PostToolUse(컨텍스트 주입), SessionStart(항상 exit 0 헬스체크), Stop(모델 자신의 응답을 검사할 수 있는 유일한 훅).
• 실전에서 터진 함정을 규칙으로 담았습니다: awk 분리 대신 shlex.shlex(punctuation_chars=True) 토큰 단위 매칭, git commit 메시지 예외 처리, bash -n + 실제 JSON 이벤트로 등록 전 E2E 테스트, SSOT + 심볼릭 링크, 프로필별 등록 수렴, 사람이 클릭/타이핑해야 하는 릴리스 게이트, 실패 방향(fail-open/fail-closed) 결정, 종료성(loop variant V) 증명.
• references/hook_patterns.md의 실행 가능한 스켈레톤과 scripts/test_hook.sh 테스트 하네스를 함께 사용합니다.

이런 분께 추천

• Claude Code를 매일 쓰면서 위험한 명령(강제 push, 파일 삭제, 시크릿 노출)을 실제로 막고 싶은 개발자
• 팀 규칙을 프롬프트가 아니라 강제 게이트로 만들고 싶은 리드/플랫폼 엔지니어
• 이미 만든 훅이 오탐하거나 세션 전체를 망가뜨려 원인을 못 찾고 있는 사람

활용 예시

1. "git push --force를 아예 못 하게 막아줘" → PreToolUse Bash 가드 작성 → 트리거/정상 명령 JSON으로 테스트 → settings.json에 등록.
2. "모델이 확인하지 않은 이름을 지어내는 걸 막고 싶다" → UserPromptSubmit이 아니라 Stop 훅이 맞다는 판단과 한 번의 블록에 모든 위반을 담는 메시지 설계.
3. "훅을 켰더니 Bash 호출이 전부 이상해졌다" → bash -n 문법 검사와 실제 이벤트 재현으로 세션 오염 원인 추적, 심볼릭 링크 끊김 여부 SessionStart 헬스체크.

이 파일의 지시를 읽고 그대로 따라서 나를 도와줘:
https://raw.githubusercontent.com/daymade/claude-code-skills/HEAD/daymade-claude-code/claude-code-hooks/SKILL.md

내가 원하는 것: (여기에 하고 싶은 일을 쓰세요)

클로드스킬마트에서 찾은 스킬을 설치해줘.
GitHub 저장소 daymade/claude-code-skills 의 daymade-claude-code/claude-code-hooks 폴더를 내 ~/.claude/skills/claude-code-hooks/ 에 그대로 복사해줘.
설치가 끝나면 이 스킬로 무엇을 할 수 있는지 한 줄로 알려줘.