Claude Code hooks 실전 2026 — 승인 루프·로그·알림 자동화 어디까지 붙여도 되나

Posted on by

2026년 4월 3일 기준으로 Anthropic 공식 Hooks reference와 Get started with Claude Code hooks 문서를 다시 읽어보면, hooks는 그냥 “파일 저장 후 포맷터 돌리기” 수준으로 보기엔 아까운 기능이다.

진짜 포인트는 더 운영 쪽에 있다.

Claude가 어디서 멈춰야 하는가, 어디서 로그를 남겨야 하는가, 언제 사람을 다시 불러야 하는가를 도구 레벨에서 붙잡는 장치라는 점이다.

많은 사람이 hooks를 처음 볼 때 자동화 사탕처럼 본다. “오, 테스트 돌리겠네.” 물론 맞다. 근데 오래 쓰면 진짜 체감은 승인 루프, 알림, 가벼운 정책 체크, 세션 로그 쪽에서 먼저 온다. 자동화는 멋있고, 승인 루프는 안 멋있는데, 실무는 보통 안 멋있는 쪽이 더 중요하다.

Quick Answer: Claude Code hooks는 Claude Code 라이프사이클 특정 지점에서 사용자 정의 명령, HTTP 호출, 프롬프트, 에이전트를 붙이는 장치다. 실전에서 제일 잘 먹히는 건 Notification, PostToolUse, SessionStart, SessionEnd, PermissionRequest 근처다. 대신 훅을 무겁게 붙이면 자동화가 아니라 자동 지연이 된다. 특히 비동기 async hook은 편하지만 행동을 막을 수 없고, 정책 차단은 동기 훅에서 처리해야 한다.

이 글이 필요한 사람

  • Claude Code hooks를 봤는데 어디부터 붙여야 할지 감이 안 오는 사람
  • 알림은 받고 싶고, 테스트도 자동화하고 싶고, 위험한 명령은 조금 막고 싶은 사람
  • hooks를 넣었다가 세션만 느려지고 짜증났던 사람
  • Claude Code를 개인 장난감이 아니라 팀 워크플로로 굴리고 싶은 사람

지금 결론

먼저 결론부터 줄이면 이렇다.

  1. hooks는 반복 작업 자동화보다 운영 질서 자동화에 더 잘 맞는다.
  2. 가장 먼저 붙일 건 보통 Notification 하나, PostToolUse 하나다.
  3. 위험한 작업 차단은 가볍고 결정적인 훅으로, 무거운 검증은 async로 따로 보내는 게 낫다.
  4. 훅이 많아질수록 중요한 건 기능 수보다 언제 막고, 언제 알리고, 언제 로그만 남길지의 구분이다.

hooks가 정확히 뭐냐

Anthropic 공식 문서 기준으로 hooks는 Claude Code 라이프사이클 특정 시점에 자동으로 실행되는 사용자 정의 동작이다. 설정 위치도 분명하다.

  • ~/.claude/settings.json
  • .claude/settings.json
  • .claude/settings.local.json
  • 엔터프라이즈 관리 정책

훅 타입도 단순 명령 하나가 전부가 아니다.

  • command
  • http
  • prompt
  • agent

즉 “셸 명령 하나 실행”뿐 아니라, HTTP 서비스로 넘기거나, 가벼운 모델 판단을 태우거나, 아예 서브에이전트처럼 파일을 읽게 해서 판단하게 할 수도 있다.

여기서부터 이미 느낌이 온다. 이건 포맷터 버튼이 아니라 작은 운영 레이어다.

실전에서 진짜 많이 쓰는 훅은 몇 개 안 된다

공식 가이드엔 이벤트가 꽤 많지만, 매일 체감이 오는 건 보통 이 다섯 줄기다.

1. Notification

Claude가 네 입력이나 승인을 기다릴 때 데스크톱 알림을 보낸다.

이건 별거 아닌 것 같아도 꽤 크다. Claude Code는 live UI가 강점이지만, 사람은 늘 터미널만 보고 살 수가 없다. 문서 읽다가, 다른 탭 보다가, 물 마시다가 놓친다. 이때 Notification 훅 하나만 있어도 “내가 Claude를 감시”하는 모드에서 “Claude가 나를 다시 부름” 모드로 바뀐다.

2. PostToolUse

파일 쓰기나 편집 뒤에 검증을 자동으로 붙이기 좋다.

예를 들어:

  • Write 뒤에 빠른 테스트
  • 포맷터 실행
  • 변경 파일 로그 적재
  • 특정 디렉토리 수정 시 규칙 검사

여기서 제일 중요한 건 “무거운 걸 다 돌리지 말 것”이다. 모든 수정 뒤에 풀 테스트를 걸면 훅이 아니라 도로공사다.

3. PermissionRequest

이건 승인 루프 자동화에 가깝다. Claude가 어떤 행동에 승인을 요청했을 때, 정책을 조금 더 체계적으로 붙일 수 있다.

예:

  • 위험한 명령어면 바로 deny
  • 특정 경로 수정은 한 번 더 경고
  • 외부 네트워크나 민감 파일 접근은 별도 메시지

이 자리는 재미보다 안전이 우선이다. 화려한 똑똑함보다 “이건 막자” 한 줄이 더 낫다.

4. SessionStart

세션 시작 시 현재 브랜치, 최근 변경, 오늘 해야 할 일 같은 기본 브리핑을 붙이기 좋다.

매번 사람이 같은 설명을 반복하는 프로젝트라면 여기 효과가 생각보다 크다. Claude가 처음부터 현재 상태를 알고 들어오니까, 대화 첫 다섯 턴을 덜 버린다.

5. SessionEnd

끝날 때 로그 요약, 남은 TODO, 다음에 이어볼 체크포인트를 남길 수 있다.

세션 종료 때 남긴 한 줄 메모가 다음 세션의 열 줄 설명을 줄여준다. AI와 일할 때 귀찮은 건 생각보다 “다시 설명하기”거든.

승인 루프엔 hooks가 왜 잘 맞나

Claude Code를 오래 쓰다 보면, 성능보다 짜증을 만드는 건 모델이 아니라 승인 흐름인 경우가 많다.

  • 작은 수정인데 자꾸 승인을 눌러야 함
  • 반대로 자동으로 열어놨더니 너무 많은 게 그냥 지나감
  • 같은 위험 명령을 세션마다 또 설명해야 함

hooks는 여기서 꽤 쓸모 있다.

공식 레퍼런스 기준으로 hook은 실행을 막거나, 허용하거나, 특정 메시지를 추가할 수 있다. HTTP 훅도 2xx 응답과 함께 decision: "block" 또는 permission deny 성격의 응답을 줄 수 있고, prompt/agent 훅도 조건 판단에 쓸 수 있다.

다만 여기서 중요한 해석 하나.

정책 차단은 짧고 결정적이어야 한다.

예를 들면 이런 식이 좋다.

  • .env, 키 파일, 배포 스크립트 수정은 막음
  • rm -rf, 대량 삭제, 위험한 네트워크 명령은 막음
  • 특정 운영 폴더 변경은 메시지와 함께 재확인

반대로 “이게 진짜 위험한가?”를 길게 토론시키면 승인 루프가 아니라 승인 드라마가 된다. 이런 자리는 차라리 규칙을 더 단순하게 가져가는 게 낫다.

로그는 언제 hooks로 남기면 좋나

로그도 비슷하다. 전부 다 기록하면 로그가 아니라 쓰레기통이 된다.

hooks로 남기기 좋은 건 이런 류다.

  • 세션 시작/종료 시점
  • 어떤 파일이 바뀌었는지
  • 테스트가 통과했는지 실패했는지
  • 사람이 다시 개입해야 하는 순간

내 기준 추천은 이렇다.

목적 추천 이벤트 왜 여기서 남기나
세션 브리핑 SessionStart 시작 문맥을 고정하기 좋음
변경 추적 PostToolUse 실제 파일 수정 직후라 누락이 적음
승인 흔적 PermissionRequest 나중에 왜 막혔는지 되짚기 쉬움
종료 요약 SessionEnd 다음 세션 연결이 쉬워짐

로그는 “많이”보다 “다음 행동에 도움 되게”가 중요하다. 사람이 다시 읽을 걸 생각하고 남겨야지, 기계가 남길 수 있으니 다 남기는 건 거의 디지털 영수증 산사태다.

알림 훅은 생각보다 ROI가 높다

공식 가이드가 가장 앞에 두는 예시도 Notification이다. 이건 괜히 그런 게 아니다.

알림 훅이 좋은 이유는 세 가지다.

  1. Claude Code가 사람을 기다리는 순간만 잡아준다
  2. 사람은 터미널 앞에 묶이지 않아도 된다
  3. 가장 구현이 간단한데 체감은 빠르다

특히 macOS에서 osascript로 데스크톱 알림 한 줄 붙이는 건 투자 대비 체감이 크다. 실전 자동화는 종종 “거창한 파이프라인”보다 “나를 다시 불러주는 한 줄”이 먼저 이긴다.

async hooks는 편하지만 브레이크는 아니다

이 부분이 꽤 중요하다.

Anthropic 공식 문서 기준으로 async: true를 주면 hook은 백그라운드에서 돌고 Claude는 계속 진행한다. 여기서 제약도 분명하다. async hook은 이미 행동이 진행된 뒤라 decision, permissionDecision, continue 같은 제어 효과가 먹지 않는다.

쉽게 말하면:

  • async는 검증, 알림, 후처리에는 좋다
  • async는 차단, 보류, 승인 제어에는 안 맞는다

그래서 설계는 보통 이렇게 가는 게 좋다.

  • 막아야 하는 것: 동기 훅
  • 오래 걸리는 테스트: async 훅
  • 결과 알려주기: async 훅 + 다음 턴 context

공식 문서 예시처럼 PostToolUse에서 파일 변경 뒤 테스트 스크립트를 async로 태우는 패턴은 꽤 실전적이다. Claude는 계속 일하고, 테스트 결과는 다음 턴에 돌아온다. 일단 일은 멈추지 않고, 망했으면 다음에 바로 잡으면 된다.

hooks가 피곤해지는 순간

이건 꼭 적어야 한다. hooks는 너무 쉽게 “똑똑한 자동화” 흉내를 낼 수 있는데, 그만큼 과잉설계 함정도 빠르다.

1. 모든 변경 뒤 무거운 테스트

작은 문서 수정에도 대형 테스트가 돌아가면 Claude보다 훅이 더 무거워진다.

2. 정책 훅이 너무 수다스러움

막을지 말지 애매한 메시지를 다섯 줄씩 내보내면 승인 루프가 느려진다.

3. 팀마다 훅이 달라 재현성이 깨짐

공식 문서가 훅 스냅샷과 /hooks 브라우저를 강조하는 이유도 여기랑 닿아 있다. 세션 시작 시 훅 구성을 스냅샷으로 잡고, 외부 변경이 있으면 경고를 주는 건 보안뿐 아니라 재현성 문제도 막기 위해서다.

4. 훅이 본업보다 더 복잡해짐

훅은 Claude를 돕는 조연이어야지, 메인 플롯을 빼앗으면 안 된다.

그럼 처음엔 뭘 붙이면 되나

내 추천은 이 3단계다.

1단계. Notification

사람 호출 비용부터 낮춘다.

2단계. PostToolUse에 가벼운 후처리 하나

예:

  • 수정 후 formatter
  • 변경 파일 로그
  • 빠른 smoke test

3단계. PermissionRequest 또는 PreToolUse에 얇은 정책

예:

  • 민감 파일 막기
  • 위험 명령 차단
  • 특정 경로 경고

여기까지면 이미 쓸 만하다. 그 다음부터는 팀이나 프로젝트 운영 성격에 따라 늘리면 된다.

사람 유형별 추천

개인 개발자

  • Notification
  • PostToolUse async 테스트

이 정도면 체감이 제일 빠르다.

소규모 팀

  • 공용 SessionStart 브리핑
  • 민감 경로 정책 훅
  • 종료 로그

팀 규칙이 조금 생기면 이 조합이 꽤 좋다.

운영 리스크가 큰 프로젝트

  • 위험 명령 deny
  • 민감 파일 deny
  • 별도 로그 적재
  • async 테스트와 알림 분리

이쪽은 멋보다 안전이 우선이다.

실수 TOP 4

1. hooks를 다 붙이면 더 똑똑해진다고 믿는다

아니다. 대개 더 피곤해진다.

2. async 훅으로 위험 행동을 막으려 한다

이미 늦었다. async는 브레이크가 아니다.

3. 로그를 너무 많이 남긴다

읽히지 않는 로그는 존재하지 않는 로그랑 비슷하다.

4. 경로를 대충 적는다

공식 문서가 $CLAUDE_PROJECT_DIR와 plugin 경로 변수를 따로 설명하는 이유가 있다. 작업 디렉토리가 달라져도 훅이 깨지지 않게 하려면 경로를 안정적으로 잡아야 한다.

FAQ

Q1. hooks는 꼭 셸 명령이어야 하나?

아니다. 공식 문서 기준으로 command, http, prompt, agent 타입을 쓸 수 있다.

Q2. 먼저 하나만 붙인다면?

대부분은 Notification이 제일 빨리 체감된다. 그다음 PostToolUse 하나.

Q3. 위험한 명령 차단은 어디에 붙이는 게 좋나?

보통 PermissionRequest나 PreToolUse 쪽처럼 행동 전에 개입할 수 있는 지점이 맞다.

Q4. 테스트 자동화는 sync가 좋아 async가 좋아?

짧고 반드시 막아야 하는 검증이면 sync, 오래 걸리고 후속 확인이면 async가 더 낫다.

다음에 읽을 글

공식 출처