Claude Code 훅 작성 가이드

무엇을 해주나

CLAUDE.md에 규칙을 적어놨는데도 Claude가 계속 어기는 상황을 '훅(hook)'이라는 구조적 차단 장치로 바꿔 줍니다.

• 훅 종류별 발동 시점과 종료 코드(0=허용, 2=차단) 계약 정리
• PreToolUse Bash 가드 스켈레톤 및 실행 가능한 패턴 모음(references/hook_patterns.md)
• 오탐(false-block)을 막는 shlex 토큰 단위 매칭 기법 (awk 분할 금지)
• 등록 전 bash -n + 실제 JSON 이벤트로 하는 엔드투엔드 테스트 절차와 테스트 하네스 스크립트
• SSOT + 심볼릭 링크로 ~/.claude 재설치 시에도 가드가 사라지지 않게 하는 배치법
• 여러 프로필 동기화, 사람이 직접 확인해야 하는 릴리스 게이트(osascript 대화상자 등)
• Stop 훅 무한 루프를 막는 종료 증명(loop variant V) 방법론

이런 분께 추천

• Claude Code가 위험한 명령(강제 푸시, 파일 삭제, 시크릿 커밋)을 실행하지 못하게 막고 싶은 개발자
• 프롬프트로 규칙을 아무리 강조해도 반복 위반이 발생해 지친 팀 리드
• 이미 훅을 만들었지만 오탐하거나 세션이 깨져 원인을 못 찾는 사람
• 여러 프로필/머신에 가드레일을 일관되게 배포해야 하는 운영 담당자

활용 예시

1. "git push --force를 무조건 막는 훅 만들어줘" → 명령 토큰 위치를 검사하는 PreToolUse 가드를 생성하고, grep이나 커밋 메시지 안의 문자열은 통과하도록 예외 처리까지 해줍니다.
2. "방금 만든 훅이 멀쩡한 명령까지 차단해" → awk 분할/원문 문자열 매칭 문제를 진단하고 shlex.shlex(punctuation_chars=True) 기반 워커로 교체합니다.
3. "커밋 후에 Claude가 커밋했다고 착각하는 걸 막고 싶다" → PostToolUse에서 실제 git HEAD를 다시 읽어 컨텍스트로 주입하는 훅을 설계해 줍니다.

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