Cursor 훅(Hooks)으로 에이전트 안전장치 만들기: 위험 명령 차단부터 완료 알림까지

핵심 요약: 에이전트에게 자율성을 줄수록 필요한 건 감시가 아니라 자동 안전장치입니다. Cursor 훅은 에이전트 루프의 특정 시점(셸 명령 실행 전, 턴 완료 등)에 내 스크립트를 끼워 넣는 기능으로, .cursor/hooks.json에 선언해 사용합니다. 이 글은 바로 쓰는 레시피 4개 — ① 위험 명령(rm -rf, 프로덕션 접근) 차단 ② 작업 완료 데스크톱 알림 ③ 편집 후 자동 린트 ④ 무한 루프 제한. 3.11부터는 클라우드 에이전트에도 훅이 적용되므로 밤새 돌리는 작업에도 같은 안전장치를 걸 수 있습니다.

이 글에서 다루는 내용: 훅 동작 구조, hooks.json 설정, 안전장치 레시피 4개, 클라우드 확장.

훅이 끼어드는 지점

훅은 "에이전트 루프에 올라탄 스크립트"입니다. 대표 이벤트는 beforeShellExecution(셸 명령 실행 직전 — 명령·작업 디렉터리를 받아 허용/차단 결정)과 stop(턴 종료 시점 — 알림·후처리·루프 제어)이고, 3.11부터 대화·프롬프트·서브에이전트·턴 완료 시점까지 관찰·제어 범위가 넓어졌습니다. 중요한 규칙 하나: 스크립트만 두면 동작하지 않고, 반드시 hooks.json에 선언해야 합니다(사용자 전역은 ~/.cursor/hooks.json, 프로젝트는 .cursor/hooks.json).

레시피 ① 위험 명령 차단 (beforeShellExecution)

실행될 명령을 받아 패턴 검사 후, 걸리면 차단 응답을 돌려주는 스크립트를 겁니다. 차단 목록의 최소 구성: rm -rf 계열, git push --force, DB 파괴 명령(drop/truncate), 프로덕션 호스트로의 접근. 화이트리스트 방식(허용 명령만 통과)이 더 안전하지만 개인 프로젝트에는 블랙리스트로도 충분합니다. 에이전트가 "명령을 실행해도 되냐"고 묻는 단계를 신뢰하는 대신, 물어봐도 실행될 수 없는 구조를 만드는 것이 훅의 가치입니다.

레시피 ② 완료 알림 (stop)

턴이 끝나면 데스크톱 알림을 쏘는 훅입니다. macOS면 osascript -e 'display notification "작업 완료" with title "Cursor"' 한 줄, Windows면 PowerShell 토스트로 같은 일을 합니다. 장시간 위임 작업 중 다른 일을 하다가 끝나는 시점만 통보받는 용도로, 써보면 가장 자주 발동하는 훅입니다.

레시피 ③ 편집 후 자동 린트

파일 편집 이벤트에 린터(ruff, eslint 등)를 걸어 결과를 에이전트에게 돌려주면, 스타일 지적을 사람이 하지 않아도 에이전트가 스스로 고치는 피드백 루프가 됩니다. Rules로 "린트 통과시켜라"라고 지시하는 것(선언)과 훅으로 강제하는 것(집행)의 차이 — 지시는 잊혀도 훅은 잊히지 않습니다.

레시피 ④ 루프 제한 (loop_limit)

stop 훅에는 루프 제한 설정을 둘 수 있어, 에이전트가 같은 작업을 무한 반복하며 사용량을 태우는 사고를 구조적으로 막습니다. 특히 "테스트 통과할 때까지 반복" 같은 지시와 조합할 때 필수 안전장치입니다.

3.11: 클라우드 에이전트에도 같은 안전장치

이번 확장의 의미는 "밤새 돌리는 작업에도 훅이 적용된다"입니다. 클라우드 위임(Cloud Agents 글)의 불안 요소가 "안 보이는 동안 뭘 할지"였는데, 위험 명령 차단과 턴 완료 로그를 걸어두면 로컬과 같은 통제 수준이 됩니다. 저는 클라우드 작업에 ①과 ④를 기본으로 걸어두는데, 아침에 로그를 열어 "차단 0건"을 확인하는 것으로 검토를 시작하는 루틴이 자리 잡았습니다. 한 번은 의존성 업그레이드 작업이 lock 파일 충돌로 재시도를 반복하다 루프 제한에 걸려 멈춰 있었는데, 그 한 번으로 사용량 폭탄 하나를 막았으니 설정 비용은 이미 회수한 셈입니다.

자주 묻는 질문 (FAQ)

Q. 훅 스크립트는 무슨 언어로 써야 하나요?

A. 실행 가능하면 뭐든 됩니다(셸, Python, Node 등). 표준 입출력으로 이벤트 데이터를 주고받는 구조라 간단한 것은 셸 한 줄로도 충분합니다.

Q. Claude Code 훅과 같은 건가요?

A. 개념은 같고(에이전트 루프에 스크립트 삽입) 이벤트 이름과 설정 파일이 다릅니다. Claude Code 쪽 레시피는 별도 글에 정리했습니다.

Q. 훅이 느리면 에이전트도 느려지나요?

A. 네, 동기 실행되는 지점의 훅은 대기를 만듭니다. 차단 판정 같은 훅은 가볍게 유지하고, 무거운 처리(로그 적재 등)는 백그라운드로 넘기세요.

한눈에 보는 요약

차단은 beforeShellExecution, 알림·루프 제한은 stop, 품질 강제는 편집 훅. 그리고 hooks.json 선언을 잊지 말 것. 자율성은 지시가 아니라 구조로 통제하는 것이고, 훅이 그 구조입니다.

함께 보면 좋은 글

Cursor Cloud Agents 사용법
Claude Code 훅 레시피 5가지
Cursor Rules(.mdc) 설정 방법

참고 자료

Hooks 공식 문서 (Cursor Docs)
Cursor 체인지로그 (3.11)