훅 (Hook)

훅(Hook)은 프로그램에서 특정 사건이 발생하거나 정해진 실행 시점에 도달했을 때 추가 처리를 연결하는 확장 장치입니다. 커밋 직전의 검사나 도구 실행 뒤의 기록처럼 기존 작업 흐름에 필요한 동작을 붙이는 데 사용합니다. 언제 호출되는지, 어떤 정보를 받는지, 결과가 원래 작업을 멈출 수 있는지는 훅을 제공하는 도구와 이벤트의 규칙에 따라 달라집니다.

이벤트와 연결된 추가 처리

훅은 프로그램이 정한 호출 시점과 그때 실행할 처리를 짝지어 사용합니다. 코드를 저장하거나 작업을 시작하는 등 어떤 사건을 기준으로 삼을지는 도구가 정합니다. 사용자는 그중 필요한 시점에 검사·기록·후속 처리를 연결합니다. 훅 파일이나 설정이 있다는 사실만으로 모든 작업에 실행되는 것은 아니므로, 등록된 이벤트가 실제로 발생하고 적용 조건을 만족하는지 함께 확인합니다.

Git의 githooks 문서는 Git 실행의 특정 시점에 동작을 일으키도록 훅 디렉터리에 두는 프로그램을 설명합니다. pre-commit은 커밋을 만들기 전에 호출되고, post-commit은 커밋이 만들어진 뒤에 호출됩니다. 같은 커밋 작업에 연결되어 있어도 위치가 다릅니다. 변경을 검사하는 처리와 완료 사실을 기록하는 처리를 어디에 붙일지 결정할 때 이 차이를 사용합니다.

2026년 10월 11일 확인한 앤트로픽의 Claude Code 훅 문서는 이벤트가 발생하고 일치 조건을 만족하면 관련 문맥을 처리기에 넘기는 구조를 설명합니다. PreToolUse는 도구 호출 전에, PostToolUse는 도구 호출이 성공한 뒤에 발생합니다. 이름에 도구 사용이 들어 있어도 두 시점의 입력과 역할은 같지 않습니다. 이미 끝난 작업의 결과를 읽을 목적이라면 실행 전 이벤트만으로는 필요한 정보가 갖추어지지 않습니다.

실행 방식과 작업 제어 범위

훅의 처리 방식이 언제나 셸 스크립트인 것은 아닙니다. Claude Code 훅 명세는 셸 명령 외에도 HTTP 엔드포인트나 모델 프롬프트 등을 훅 처리 방식으로 설명합니다. 명령 훅은 이벤트 문맥을 표준 입력으로 받고, HTTP 훅은 요청 본문으로 받습니다. 연결 시점이라는 공통 개념은 같아도 입력을 전달하고 결과를 돌려주는 방식은 다르므로, 선택한 처리 유형의 입력·출력 규칙을 확인합니다.

작업을 멈출 수 있는지도 이벤트마다 다릅니다. Git 훅 명세에서 pre-commit 훅이 0이 아닌 종료 상태를 반환하면 커밋 생성 전에 명령이 중단됩니다. 반면 post-commit은 주로 알림을 위한 훅이며 이미 수행된 커밋의 결과를 바꿀 수 없다고 명시합니다. 검사에 실패했다는 같은 결과라도 언제 실행한 검사인지에 따라 영향이 다릅니다. 사후 기록을 남기는 훅을 사전 차단 장치로 사용했다고 간주하지 않습니다.

훅이 끝날 때까지 원래 작업이 기다리는지도 별도 규칙입니다. Claude Code는 명령 훅을 백그라운드에서 실행하는 비동기 설정을 제공합니다. 이런 처리는 완료를 기다리는 검사와 같은 방식으로 작업을 통제한다고 볼 수 없습니다. 후속 기록처럼 기다릴 필요가 적은 작업과 실행 전에 결과를 받아야 하는 검사는 처리 시점이 다릅니다. 도구의 지원 범위와 이벤트별 결과 처리 규칙을 함께 확인합니다.

등록 조건과 결과 확인

훅이 실행되지 않는다면 먼저 도구가 읽는 위치와 등록 조건을 확인합니다. Git 훅 등록 규칙은 훅 디렉터리를 설정으로 바꿀 수 있고, 실행 가능 표시가 없는 훅은 무시한다고 설명합니다. Claude Code는 이벤트뿐 아니라 일치 조건도 사용하므로 조건에 맞지 않으면 지정한 처리로 이어지지 않습니다. 파일 이름이나 설정 내용만 살피는 것보다 실제 호출 대상과 적용 조건을 함께 확인하는 편이 원인을 좁히기 쉽습니다.

같은 훅이라는 이름이라도 다른 기능을 가리킬 수 있습니다. React의 Hooks처럼 라이브러리의 특정 API 묶음에 붙은 이름은 해당 라이브러리의 규칙으로 해석합니다. Git이나 자동화 도구의 이벤트 훅에서 쓰는 실행 시점·종료 상태 규칙을 이름만 보고 다른 API에 옮겨 적용하지 않습니다. 문서에서 말하는 훅의 호출 주체와 실행 시점, 받는 값을 확인하면 서로 다른 기능을 구별할 수 있습니다.

운영 기록에는 어떤 이벤트가 발생했고 어떤 처리가 호출되었는지, 그 결과를 원래 작업이 어떻게 받아들였는지를 나누어 남길 수 있습니다. 훅 프로그램이 실행되었다는 사실과 검사에 통과했다는 사실, 원래 작업이 중단되었다는 사실은 각각 확인할 대상입니다. 실패를 출력했더라도 이벤트 규칙상 작업을 막지 않는다면 결과 기록과 차단 여부가 다르게 나타납니다. 자동화의 동작을 검토할 때는 이 세 상태를 실제 결과와 맞춰 봅니다.