Cmd. /hooks
이벤트 기반 자동화 훅을 점검/설계할 때 사용하는 운영 심화 명령
명령어 원본 선언
/hooks공식 설명 요약
/hooks는 작업 이벤트 전후 자동화를 다루는 중심 명령입니다.
코드 생성 자체보다 운영 품질을 일정하게 만드는 데 큰 효과가 있습니다.
최소 지원 버전
- 초기 내장/legacy 항목으로 보이며, Changelog에 최초 도입 버전이 명시되지 않았습니다.
사용법
/hooks/hooks pre-commit 점검 자동화를 설계해줘좋은 사용 예
- 리뷰 전 체크리스트 자동 실행
- 작업 완료 후 상태 알림/기록 자동화
- 위험 명령 실행 전 사전 검증 추가
InstructionsLoaded훅으로 CLAUDE.md 로드 시 커스텀 동작 실행 (v2.1.69)- HTTP hooks로 외부 URL에 JSON POST하고 JSON 응답 수신 (v2.1.63)
TeammateIdle/TaskCompletedhooks에서{"continue": false, "stopReason": "..."}응답으로 작업 중단 제어 (v2.1.69)
비슷한 명령어 추천
| 명령어 | 차이점 | 언제 선택 |
|---|---|---|
/hooks | 이벤트 자동화 설계 | 반복 운영 자동화 |
/permissions | 실행 권한 정책 | 안전 가드레일 |
custom-commands | 사용자 호출 명령 | 수동 반복 작업 표준화 |
활용 사례
- PR 오픈 전 자동 검증 요약
- 장애 대응 플레이북 단계 자동 기록
- 운영 로그 아카이빙 자동화
주의사항
- 자동화 실패 시 수동 fallback 경로 문서화
- 훅 실행 비용/시간 모니터링 필요
- v2.1.69에서 훅 이벤트에
agent_id/agent_type/worktree필드가 추가되어 에이전트 구분 가능 - v2.1.77에서
PreToolUse훅의"allow"반환이deny퍼미션 규칙을 우회하던 보안 버그 수정 - v2.1.78에서
StopFailure훅 이벤트 추가 — API 에러로 턴이 종료될 때 발생 - v2.1.78에서
${CLAUDE_PLUGIN_DATA}변수 추가 — 플러그인 영구 상태 저장 경로
v2.1.74: SessionEnd 훅 타임아웃 수정
이전 버전에서는 SessionEnd 훅이 hook.timeout 설정과 무관하게 종료 시 1.5초 후 강제 종료되었습니다.
v2.1.74부터 환경변수 CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS로 타임아웃을 직접 설정할 수 있습니다.
# 예: SessionEnd 훅에 10초 여유 부여
export CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS=10000세션 종료 시 로그 전송, 정리 스크립트 등 시간이 걸리는 훅을 운영한다면 반드시 설정하세요.
출처
- Claude Code Docs: https://code.claude.com/docs
- Changelog: https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md