Claude Code - Hook을 통한 자동화.

Claude Code-Hook의 개념

조대협(http://bcho.tistory.com)

 

Hook은 Claude Code의 실행중에, 특정 이벤트가 발생하였을때 사용자가 정해 지정해놓은 Shell Command나, HTTP 요청 또는 프롬프트를 실행할 수 있는 기능이다.

 

예를 들어, Claude Code를 통해서 파일을 에디트 했을때 자동으로, 포맷팅을 검사하도록 지시할 수 있다. 물론 프롬프트를 통해서 지시할 수 도 있지만, 프롬프트는 가이드일뿐 Claude 모델이 지킬 수 도, 안 지킬 수 도 있다. 그래서 조금 더 명시적으로 어떤 이벤트가 발생했을때 사용자가 특정 명령을 수정하도록 강제할 수 있다. 

 

클로드코드의 라이프 사이클

Claude Code의 Life cycle와, 각각 툴을 걸 수 있는 포인트는 다음과 같다. 

 

<그림 Claude Code life cycle>

출처 : https://code.claude.com/docs/en/hooks

 

Hook의 종류

Event	When it fires (발생 시점)
SessionStart	Session이 시작되거나 재개될 때
UserPromptSubmit	프롬프트를 제출했고, Claude가 처리하기 전
PreToolUse	Tool 호출이 실행되기 전. (호출을 차단할 수 있음)
PermissionRequest	Permission 대화 상자가 나타날 때
PostToolUse	Tool 호출이 성공한 후
PostToolUseFailure	Tool 호출이 실패한 후
Notification	Claude Code가 알림을 보낼 때
SubagentStart	Subagent가 생성될 때
SubagentStop	Subagent가 완료될 때
Stop	Claude가 응답을 마쳤을 때
TeammateIdle	Agent team 동료가 유휴 상태가 되기 직전
TaskCompleted	Task가 완료로 표시될 때
InstructionsLoaded	CLAUDE.md 또는 .claude/rules/*.md 파일이 context에 로드될 때. Session 시작 시 및 Session 중 파일이 지연 로드될 때 발생
ConfigChange	Session 중 Configuration 파일이 변경될 때
WorktreeCreate	--worktree 또는 isolation: "worktree"를 통해 worktree가 생성될 때. 기본 git 동작을 대체함
WorktreeRemove	Session 종료 시 또는 Subagent가 완료될 때 worktree가 제거될 때
PreCompact	Context compaction 전
SessionEnd	Session이 종료될 때

 

Hook 설정하기

Hook 설정은 Event에 대해서, Hook type과 실행할 명령등을 .claude/setting.json 파일안에 아래와 같이 지정하면 된다.

이 예제는 사용자가 프롬프트를 입력했을때, log_event.sh 쉘 명령어를 수행하도록 하는 Hook 정의 이다. 

만약 Hook을 추가하고자하는 이벤트가 많을 경우에는 json 파일에 아래와 같이 배열 형식으로 추가하면 된다.

설정값은 .claude/setting.json 파일뿐만 아니라, 프로젝트의 스코프나, Skill, Agent등의 용도에 따라서 아래와 같이 각각 다른 파일에 정의해야한다. 

Location (위치)	Scope (적용 범위)	Shareable (공유 가능 여부)
``` ~/.claude/settings.json ```	모든 프로젝트	아니요, 내 로컬 컴퓨터에만 해당
``` .claude/settings.json ```	단일 프로젝트	예, repo에 커밋 가능
``` .claude/settings.local.json ```	단일 프로젝트	아니요, gitignored 됨
Managed policy settings	조직 전체	예, 관리자 제어
[Plugin] hooks/hooks.json	Plugin이 활성화될 때	예, Plugin과 함께 묶임
[Skill] or [agent] frontmatter	Component가 활성화되어 있는 동안	예, Component 파일에 정의됨

Hook의 활용

그러면 Hook은 어디에 사용할것인가? 

• 파일을 삭제하거나 에디트 할때, 파일 수정 Tool 호출에 Hook을 걸어서, 특정 파일이면 수정이나 삭제를 막거나.
• 코드가 변경되었을때, 파일 수정 이벤트에 훅을 걸어서 코드 스타일을 리뷰하거나 또는 테스트를 자동으로 생성하거나.
• 또는 코드 작성이 모두 완료되었을때 문제가 없는지 확인하고 문제가 있으면 다시 수행하는 랄프 루프와 같은 기능을 구현할 수 있다. 

Claude Code를 확장하여, 기능에 대한 자동화를 구현할 수 있다.