⌨️ 02. Claude Code HTTP Hook 실무 가이드

00편에서 역할(CLI·Hook·Skill·MCP)을 구분했고, 01편에서 CLI 실행 중심 자동화를 봤다. 이제 02편은 그 다음 단계다. 이벤트가 생겼을 때 자동으로 웹서버에 전달하고 정책을 받는 HTTP Hook 운영을 다룬다.

쉽게 말하면:

01편 CLI는 “내가 버튼을 눌러 실행”하는 방식이고,
02편 HTTP Hook은 “센서가 울리면 관제실에 자동 보고”하는 방식이다.

flowchart LR
A[Claude Code 이벤트 발생
PreToolUse/Notification 등] --> B[HTTP Hook POST]
B --> C[정책 서버
검사/기록/판단]
C --> D[허용/차단/후속 액션]
D --> E[Claude Code 실행 흐름 반영]

🧠 칠판 치트시트

CLI는 실행 중심, HTTP Hook은 통제·관찰 중심

이벤트 기반이라 사람 개입 없이 정책을 집행할 수 있음

로컬호스트도 가능해서 작은 팀도 바로 도입 가능

운영 포인트는 “무엇을 자동 판단할지”를 명확히 정하는 것

왜 HTTP Hook이 주목받나

뉴스 요약의 포인트는 “기존 command hook보다 다루기 쉽고 안전한 운영 패턴”이다. 핵심은 훅 이벤트를 URL로 보내고 응답을 받아 흐름을 제어한다는 점이다.

참고: 뉴스(HNKR)

공식 문서에서도 Hook은 Claude Code 라이프사이클의 특정 시점에 자동 실행되는 확장 지점으로 정의한다.

참고: Hooks reference
참고: Hooks guide

작동 방식 (How)

1) 이벤트 발생

SessionStart, PreToolUse, PostToolUse, Notification 같은 이벤트가 발생한다.

2) HTTP Hook 호출

Claude Code가 이벤트 컨텍스트(JSON)를 HTTP 엔드포인트로 POST한다.

3) 정책 서버 판단

서버가 규칙을 검사하고, 필요 시 허용/차단 또는 기록/알림을 수행한다.

4) 실행 반영

판단 결과가 실행 흐름에 반영되어, 위험 작업은 막고 정상 작업은 계속 진행한다.

효과 (Why)

1) 안전 가드 자동화

사람이 매번 확인하지 않아도 위험 패턴을 자동 차단할 수 있다.

2) 감사 로그 일원화

훅 호출 로그를 DB/모니터링으로 모으면 운영 추적이 쉬워진다.

3) 정책 변경 속도 향상

프롬프트를 길게 바꾸기보다 서버 룰을 업데이트해 정책을 빠르게 조정할 수 있다.

4) 팀 표준 운영

개인별 습관 차이를 줄이고, 팀 단위로 동일한 가드레일을 적용할 수 있다.

CLI/Skill/MCP와 어떻게 결합하나

CLI: 실제 실행 로직 담당 (예: 데이터 수집/정리)
Skill: 결과물 품질 규칙 담당 (형식/톤/검증)
HTTP Hook: 이벤트 통제 담당 (허용/차단/로깅)
MCP: 외부 시스템 연결 담당 (툴 표준화)

즉, HTTP Hook은 실행 도구를 대체하는 게 아니라, 실행 체계를 운영 레벨로 끌어올리는 통제층이다.

미니 사례

Before: 운영자가 수동으로 위험 명령 점검, 놓침 발생
After: PreToolUse HTTP Hook에서 정책 서버 검사 후 차단/허용
결과: 실행 속도 유지 + 사고 가능성 감소 + 로그 확보

20분 도입 루틴

5분: 막고 싶은 이벤트 1개 정의 (예: 민감 파일 수정)
5분: 로컬 HTTP 엔드포인트 1개 준비
5분: 이벤트 JSON 수신/로그 확인
5분: 허용/차단 규칙 1개 적용해 동작 검증

처음에는 규칙을 많이 넣지 말고, “가장 위험한 한 가지”부터 자동화하는 게 안정적이다.

앞뒤 연결

개념 전체 프레임: MCP이해
실행 중심 실무: cli 실무 가이드

다음 읽기

AI 활용 고지: 이 문서는 공개 링크와 공식 문서를 바탕으로 생성형 AI로 초안을 구성하고 실무 관점으로 재정리했습니다.

일하는 ai

탐색기