훅

훅은 파일 편집이나 작업 종료처럼 정해진 이벤트가 일어날 때 명령을 자동 실행한다. 사람이 기억해야 하는 반복 작업을 줄이고, 알림·로그·간단한 확인을 붙일 수 있다.

기준일: 2026-09-30

이벤트에 작은 동작 붙이기

예를 들어 파일을 바꾼 뒤 포맷터를 실행하거나, 작업이 끝났을 때 알림을 보낼 수 있다. 훅에 맡기는 일은 짧고 결과를 확인하기 쉬운 동작으로 제한한다.

파일 편집 완료
  → 포맷터 실행
  → 결과 코드 확인

에이전트 작업 완료
  → 완료 알림 전송
  → 사용량 기록 갱신

알림은 작업 내용을 과하게 보내지 말고, 완료 여부와 사람이 다음에 할 일 정도만 전달한다. 예를 들면 메시지 채널에 다음처럼 보낸다.

작업 완료: 결제 안내 문구 수정
검증: lint 통과, 테스트 42개 통과
확인 필요: 모바일 화면에서 문구 줄바꿈 확인

Discord, Slack, Telegram 같은 알림 통로를 쓸 수 있다. 연결 정보와 비밀값은 훅 파일에 직접 적지 않고 환경 변수나 런타임의 비밀 저장 기능으로 관리한다.

훅을 늘리기 전에 살필 점

훅은 매칭되는 이벤트마다 반복 실행된다. 훅이 다시 같은 도구를 호출하거나 파일을 바꾸면 같은 이벤트가 재발해 무한 루프가 생길 수 있다. 실행 조건을 좁히고, 훅이 만든 변경에는 다시 반응하지 않도록 제외 경로와 재진입 방지 조건을 둔다.

알림을 보내는 시점도 명확히 정한다. 도구를 쓰기 전에는 승인 대기 상태를 알릴 수 있고, 작업이 끝난 뒤에는 완료와 검증 결과를 전한다. 같은 이벤트가 여러 번 울리면 알림을 묶거나, 작업 식별자로 중복 전송을 막는다.

작업 시작: 변경 대상과 시작 시각 기록
도구 실행: 필요할 때만 진행 상황 기록
작업 종료: 결과와 검증 명령 기록

예를 들어 완료 훅은 메시지 전송 스크립트만 호출하고, 스크립트는 성공·실패와 실행 시간을 기록할 수 있다. 메시지에 전체 로그나 코드 diff를 넣으면 읽기 어렵고 민감 정보가 새어 나갈 수 있으므로 짧은 요약만 보낸다.

긴 절차를 훅 안에 숨기면 어떤 단계가 실행됐는지 추적하기 어렵다. 여러 단계가 필요하면 읽을 수 있는 스크립트나 별도 작업 절차로 분리하고, 훅은 그 절차를 부르는 한 줄 정도로 유지한다. 실패 코드와 로그 위치도 명확히 한다.

불필요한 훅은 실행 횟수와 모델에 전달되는 추가 정보만 늘린다. 한 번에 하나씩 추가한 뒤 어떤 이벤트에서 실행되는지 확인한다. 문제가 생기면 해당 훅을 잠시 끄고 원인을 찾을 수 있어야 한다.

점검	확인할 내용
반복	훅이 자신을 다시 호출하는 경로가 있는가?
범위	필요한 이벤트와 파일에만 실행되는가?
추적	로그와 실패 결과를 찾을 수 있는가?
비용	매번 실행할 이유가 있고 추가 사용량이 감당되는가?
권한	실행 명령이 필요한 파일과 도구에만 접근하는가?

훅을 처음 만들 때는 로그 출력만 활성화해 이벤트가 예상대로 한 번 발생하는지 확인한다. 그다음 알림이나 포맷 실행을 추가하고, 해당 훅을 끄는 방법도 함께 기록한다.

최소 설정부터 확인하기

런타임마다 이벤트 이름과 설정 문법이 다르다. 다음은 편집 뒤 검사 명령을 연결한다는 개념을 보여 주는 의사 설정이다. 실제 설정에 복사하지 말고, 사용하는 런타임의 공식 문법과 권한 범위를 확인한다.

{
  "event": "after_file_edit",
  "command": "./scripts/check-format.sh",
  "timeout": "짧은 제한 시간"
}

완료 알림도 먼저 독립 스크립트에서 시험한다. 다음처럼 입력을 고정해 메시지가 도착하는지, 비밀값이 출력되지 않는지 살핀 뒤 런타임 이벤트에 연결한다.

알림 스크립트 단독 실행
→ 테스트용 채널에서 메시지 확인
→ 훅 설정에 연결
→ 실제 완료 이벤트 한 번 확인

처음부터 포맷·린트·알림·사용량 집계를 한 훅으로 묶지 않는다. 포맷터 하나로 시작해 실행 조건과 결과를 확인한 뒤 다음 동작을 추가한다.

사용량 업데이트처럼 외부 상태를 바꾸는 동작은 중복 실행됐을 때 결과가 어떻게 되는지 확인한다. 덧셈을 다시 적용하는 방식이면 재시도 때 수치가 틀릴 수 있다. 작업 ID와 실행 시점을 기록해 한 작업의 재시도를 구분한다.

설정을 켜기 전에는 정상·실패·중복 상황을 한 번씩 직접 확인한다.

상황	확인 결과
편집 이벤트 한 번	검사나 포맷이 한 번 실행됨
검사 명령 실패	오류가 로그나 에이전트 응답에 남음
같은 완료 이벤트 재전달	중복 알림 또는 사용량 중복이 없는지 확인
알림 서비스 연결 실패	본 작업의 성공·실패와 알림 실패를 구분

훅이 실패해도 본 작업을 막아야 하는지, 기록만 남기면 되는지 목적을 먼저 정한다. 포맷·린트처럼 결과물 품질의 필수 조건이라면 실행 결과를 확인해야 한다. 알림처럼 편의 기능이라면 알림 서버가 잠시 응답하지 않아도 작업의 검증 결과와 혼동하지 않게 한다.

보충: Claude Code와 Codex의 실행·차단 동작

Claude Code의 훅 안내와 이벤트 목록은 편집 후 포맷·린트와 이벤트별 명령 실행을 설명한다. 명령 훅은 사용자 권한으로 실행되므로 설정을 검토하고 시험해야 한다. 프로젝트 훅은 워크스페이스를 신뢰하기 전에는 실행되지 않는다. 종료 코드 2의 차단 효과는 이벤트에 따라 다르며, PreToolUse는 도구 호출을 막을 수 있지만 PostToolUse는 이미 끝난 작업을 되돌리지 못한다.

Codex의 훅은 PreToolUse, PostToolUse, Stop, SubagentStart 등의 이벤트에서 스크립트나 MCP 도구를 실행할 수 있게 한다. 관리되지 않은 훅은 검토·신뢰 전 실행되지 않으며 /hooks에서 관리한다. MCP 훅은 도구가 차단 결정을 반환한 경우에만 차단한다. 서버 오류나 도구 부재 때는 차단하지 않는다.

두 런타임 모두 이벤트에 맞춰 자동 동작을 연결하지만, 신뢰 설정과 차단 동작은 다르다. 실제 차단이 필요한 검사라면 어떤 이벤트가 작업을 막는지 확인하고, 최종 완료 여부는 훅 외의 테스트·빌드 결과로도 판단한다. 기준일: 2026-09-30.