Hooks

Hooks를 사용하는 이유

CLAUDE.md에서 Claude에게 모든 파일 편집 후 Prettier를 실행하라고 지시할 수 있습니다. 대부분의 경우 그렇게 할 것입니다. 하지만 때로는 그렇지 않을 수도 있습니다. Hook을 사용하면 예외 없이 매번 실행되도록 만들 수 있습니다.

일반적인 사용 사례는 다음과 같습니다:

• 파일 편집 후 자동 포맷팅
• 컴플라이언스를 위해 실행된 모든 명령 기록
• 프로덕션 파일 수정과 같은 위험한 작업 차단
• Claude가 작업을 완료했을 때 알림 보내기

작동 방식

Hooks는 settings.json에서 설정합니다. 이벤트를 선택하고, 선택적으로 어떤 도구에 적용할지 매처(matcher)를 설정한 다음, 실행할 명령을 제공합니다. 가장 일반적인 이벤트 중 일부는 다음과 같습니다:

• PreToolUse — 도구 호출 전에 실행됩니다
• PostToolUse — 도구 호출이 완료된 후 실행됩니다
• UserPromptSubmit — 프롬프트를 제출할 때, Claude가 처리하기 전에 실행됩니다
• Stop — Claude가 응답을 마쳤을 때 실행됩니다
• Notification — Claude가 알림을 보낼 때 실행됩니다

이는 연결할 수 있는 이벤트 중 일부에 불과합니다 — Claude Code는 훨씬 더 많은 이벤트를 지원합니다. 전체 목록은 Hooks 참조 문서를 참조하세요.

settings.json을 직접 편집하여 이를 설정합니다. Claude Code 내부의 /hooks 명령은 설정된 Hooks의 읽기 전용 목록을 열어주므로, 새로 추가한 Hook이 나타나는지 확인할 수 있습니다.



실제 예시

가장 일반적인 Hook: 편집 후 자동 포맷팅입니다. "Edit|Write" 매처를 사용하는 PostToolUse Hook을 설정하면 Claude가 Edit 또는 Write 도구를 사용한 후에 실행됩니다. 이 명령은 파일 확장자를 확인하고 적절한 포맷터를 실행합니다: TypeScript에는 Prettier, Go에는 gofmt, 프로젝트에서 사용하는 무엇이든 말이죠.

PreToolUse로 차단하기

PreToolUse Hook은 도구 호출이 실행되기 전에 도구 호출을 차단할 수 있습니다. Hook은 도구 이름과 입력을 stdin을 통해 JSON 형태로 받습니다. 종료 코드(exit code)가 동작을 결정합니다:

• 종료 코드 0 — 정상적으로 진행합니다.
• 종료 코드 2 — 작업을 차단합니다. stderr 메시지는 Claude에게 피드백으로 전달되어 왜 차단되었는지 알고 조정할 수 있게 합니다.
• 그 외의 종료 코드 — 차단하지 않는 오류로, 사용자에게 표시되지만 아무것도 중단시키지 않습니다.

이것이 엄격한 규칙을 강제하는 방법입니다. 프로덕션 설정 디렉터리에 대한 쓰기를 차단하세요. rm -rf가 포함된 bash 명령을 차단하세요. main 브랜치에 대한 커밋을 차단하세요. 팀에서 제안이 아니라 보장되어야 하는 것이라면 무엇이든 말이죠.



팀과 Hooks 공유하기

.claude/settings.json에 설정된 Hooks는 프로젝트 수준이며 저장소에 커밋할 수 있습니다. 이는 팀 전체가 자동으로 동일한 Hooks를 갖게 된다는 의미입니다. 명령에서 CLAUDE_PROJECT_DIR 환경 변수를 사용하여 프로젝트에 저장된 스크립트를 참조하면, Claude의 현재 작업 디렉터리와 관계없이 작동합니다.

요약

Hooks는 Claude Code의 동작에 대한 결정론적 제어를 제공합니다. 자동 포맷팅과 로깅에는 PostToolUse를 사용하세요. 위험한 작업을 차단하려면 PreToolUse를 사용하세요. settings.json에서 설정하고 /hooks로 확인하세요. 그리고 저장소에 커밋하여 팀도 이를 사용할 수 있게 하세요.

매번 반드시 일어나야 하는 일이 있다면, 프롬프트에 넣지 마세요. Hook에 넣으세요.