Claude Code Hooks Mastery

Claude Code Hooks Mastery는 Claude Code의 동작을 결정론적으로 또는 비결정론적으로 제어하는 훅을 실제 구현으로 익히도록 만든 시연 저장소입니다. 훅뿐 아니라 서브에이전트, 메타 에이전트, 에이전트 오케스트레이션을 포함한 팀 기반 검증 시스템도 함께 다룹니다. 주요 기능 · UserPromptSubmit: 프롬프트 검증, 로깅, 컨텍스트 주입, 보안 필터링을 수행합니다 · PreToolUse: rm -rf 실행이나 .env 접근 같은 위험한 명령을 차단합니다 · PostToolUse와 PostToolUseFailure: 도구 실행 결과를 수집하고 실패는 타임스탬프와 전체 컨텍스트를 담아 구조화 기록합니다 · Notification과 Stop, SubagentStop: 입력 요청과 응답 완료, 서브에이전트 종료를 음성으로 알립니다 · PreCompact: 압축 직전 트랜스크립트를 백업합니다 · SessionStart와 SessionEnd: git 상태와 최근 이슈, 컨텍스트 파일을 불러오고 종료 시 세션을 기록합니다 · PermissionRequest: 권한 요청을 감사하고 읽기 전용 작업은 자동 허용합니다 · Setup: CLAUDE_ENV_FILE로 환경을 유지하고 additionalContext로 컨텍스트를 주입합니다 총 13개 훅 이벤트가 구현되어 로깅되며 그중 11개가 자동화 테스트로 검증되었습니다. 사용하려면 Python 패키지 설치와 의존성 해석을 담당하는 Astral UV와 Claude Code가 필요하고, ElevenLabs와 ElevenLabs MCP 서버, Firecrawl MCP 서버, OpenAI, Anthropic, Ollama는 선택 사항입니다. settings.json에 훅 경로를 적을 때는 경로 해석이 확실하도록 $CLAUDE_PROJECT_DIR 접두사를 사용하라고 안내합니다. 훅으로 에이전트 동작에 안전장치와 자동화를 직접 붙여보려는 사람에게 맞습니다.