AI 코딩 에이전트의 Hook - 에이전트를 길들이는 가드레일 (2026년 3월 초 조사)

Hook이란 무엇인가?

AI 코딩 에이전트(Claude Code, Cursor, Copilot 등)가 코드를 읽고 쓰고 명령을 실행할 때, 그 실행 전후에 내가 만든 스크립트를 끼워 넣는 것이 바로 Hook이다.

비유하면 이렇다. AI가 파일을 수정하려는 순간, 내가 먼저 "잠깐, 이 파일은 건드리면 안 돼" 하고 막을 수 있다. 혹은 파일이 수정된 직후 "수정됐으니까 린터 돌려줘" 하고 자동으로 후처리를 할 수 있다.

즉 Hook은 두 가지 역할을 한다:

• 사전 차단(Pre-hook): 위험한 행동이 실행되기 전에 막는다
• 사후 처리(Post-hook): 실행 완료 후 추가 작업을 자동화한다

왜 Hook이 필요한가? - Harness Engineering

AI 코딩 에이전트는 강력하지만 비결정적(non-deterministic)이다. 같은 지시를 해도 매번 다른 결과가 나올 수 있고, 때로는 의도치 않은 파일을 지우거나 위험한 명령을 실행하기도 한다.

이 문제를 해결하는 개념이 Harness Engineering이다. Harness는 말에 씌우는 마구(馬具)에서 유래한 용어로, 강력하지만 예측 불가능한 AI를 안전하게 작동시키기 위한 통제 체계를 뜻한다.

"모델을 바꾸기 전에 Harness를 바꿔라. 같은 모델이 Harness에 따라 극적으로 다른 결과를 낸다."

Harness의 구성 요소 중 Hook은 '센서' 역할을 한다. AI의 행동을 감시하고, 정책에 따라 허용/차단/수정하는 것이다. Hook 없이는 AI가 무엇을 하는지 실시간으로 알 수 없고 막을 수도 없다.

주요 AI 코딩 에이전트 Hook 비교 (2026년 3월 초 기준)

2026년 3월 초 기준으로 주요 AI 코딩 에이전트 8개의 Hook 지원 현황을 조사했다. 각 도구의 Hook 성숙도 차이가 상당히 크다.

에이전트	이벤트 수	사전 차단	HTTP 웹훅	성숙도
Claude Code	18	✅	✅	높음
Windsurf	12	✅	❌	높음
Gemini CLI	11	✅	❌	높음
Cline	8	✅	❌	중간
GitHub Copilot	8	✅	❌	Preview
Cursor	7	✅	❌	중간
Codex CLI	6	❌	❌	초기
Roo Code	4	✅	❌	초기

※ 미지원: Aider(커뮤니티 요청 중), Continue(Agent mode + MCP로 대체), Antigravity(Workflows/Rules로 대체)

Claude Code - 가장 풍부한 18개 이벤트

현재 가장 많은 Hook 이벤트를 지원하는 것이 Claude Code다. 설정 파일은 .claude/hooks.json이다.

주요 이벤트만 추려보면:

• UserPromptSubmit: 사용자가 프롬프트를 제출하기 전 - 컨텍스트 자동 주입에 활용
• PreToolUse: 도구 실행 전 - 위험 명령 차단의 핵심
• PostToolUse: 도구 실행 성공 후 - 빌드 자동 실행, 로깅
• SubagentStart / SubagentStop: 서브에이전트(병렬 작업) 생성/완료 시
• PreCompact: 컨텍스트 압축 전 - 중요 정보 보존 처리

또한 Command 외에도 HTTP, Prompt, Agent 총 4가지 Hook 타입을 지원해서 외부 서비스 연동도 가능하다.

Gemini CLI - LLM 호출 단위 Hook이 독특

Gemini CLI는 BeforeModel / AfterModel 이벤트가 특이하다. LLM에 요청이 가기 직전, 응답이 온 직후에 각각 훅을 걸 수 있다. 다른 도구들은 도구 실행 단위(파일 읽기/쓰기/명령 실행)에 집중하지만, Gemini CLI는 LLM 호출 단위 자체를 인터셉트할 수 있다.

Cursor - 깔끔한 camelCase, v1.7 도입

Cursor는 v1.7부터 Hook을 지원했다. 이벤트 수는 7개로 적지만, permissionDecision으로 차단/허용/수정을 세밀하게 제어할 수 있다. 설정은 .cursor/hooks.json.

GitHub Copilot - Claude Code와 동일 포맷 호환

아직 Preview 단계지만 GitHub Copilot의 Hook이 Claude Code와 동일한 JSON 포맷을 사용한다. 두 도구를 함께 쓰는 팀이라면 Hook 설정을 공유할 수 있을 것으로 보인다.

실전 Hook 사용 예시

말로만 들으면 추상적이니, 실제로 어떻게 쓰는지 보자.

예시 1: 위험 명령 자동 차단

AI가 rm -rf나 git push --force를 실행하려 할 때 자동으로 막는다.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "command": "bash .claude/hooks/check-dangerous.sh"
      }
    ]
  }
}

check-dangerous.sh 안에서 exit 2를 반환하면 AI의 해당 도구 실행이 차단된다.

예시 2: 파일 수정 후 자동 린팅

AI가 파일을 수정할 때마다 자동으로 ESLint / Prettier를 돌린다.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "command": "npx eslint --fix $CLAUDE_TOOL_OUTPUT_PATH"
      }
    ]
  }
}

예시 3: 프롬프트 제출 시 컨텍스트 자동 주입

매번 "SDK 버전은 XX야, 브랜치는 YY야"를 입력하지 않아도 자동으로 현재 환경 정보를 주입한다.

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "command": "bash .claude/hooks/inject-context.sh"
      }
    ]
  }
}

2026년 최신 경향: Hook이 표준으로 자리잡고 있다

(아래 내용은 2026년 3월 초 조사를 기준으로 작성했다. AI 도구의 업데이트 속도가 빠르므로, 최신 버전 릴리즈 노트도 함께 확인하는 것을 권장한다.)

1. Hook 포맷이 수렴하고 있다

GitHub Copilot이 Claude Code와 동일한 Hook 포맷을 채택하고, Cline도 Claude Code 스펙 기반으로 구현했다. 여러 도구가 같은 포맷으로 수렴하고 있어, 앞으로는 하나의 Hook 설정을 여러 도구에서 재사용할 수 있게 될 가능성이 높다.

2. Hook이 Harness의 핵심 인프라로 격상

2026년 3월 OpenAI가 공개한 오픈소스 에이전트 오케스트레이션 프레임워크에서는 Hook이 단순 스크립트가 아니라 CI 검증 → PR 생성까지 이어지는 자율 루프의 핵심 제어 지점으로 사용된다. "Proof of Work"(CI 통과 확인) 개념과 결합해서, 에이전트가 한 일의 품질을 자동으로 검증하는 역할을 한다.

3. LLM 호출 단위 Hook의 등장

Gemini CLI가 BeforeModel / AfterModel Hook을 도입하면서, 이제 단순히 "파일 쓰기 전에 막는다"는 수준을 넘어 LLM의 입출력 자체를 인터셉트할 수 있는 방향으로 발전하고 있다. 이는 응답 품질 자동 검증, 프롬프트 오염 방지 등 새로운 use case를 열어준다.

4. 서브에이전트 Hook의 중요성 증가

AI가 혼자 일하는 게 아니라 여러 서브에이전트를 병렬로 띄워 작업하는 패턴이 늘고 있다. Claude Code와 GitHub Copilot은 SubagentStart / SubagentStop Hook을 지원해서, 병렬 에이전트 각각의 생명주기를 추적하고 제어할 수 있다.

Hook을 쓸 때 알아야 할 실용 팁

• exit code가 제어의 핵심이다: 0이면 허용, 2면 차단. 도구마다 약간 다르니 문서를 꼭 확인.
• 너무 많이 걸면 느려진다: 모든 도구 실행마다 무거운 스크립트가 돌면 AI가 답답해진다. 핵심 이벤트에만 집중할 것.
• 로깅부터 시작하라: 처음엔 차단하지 말고, PostToolUse에 로깅 훅만 달아서 AI가 무슨 일을 하는지 먼저 파악하라.
• Hook은 워크스페이스별로 관리하라: 프로젝트마다 다른 Hook이 필요하다. 글로벌 Hook은 최소화하고 프로젝트 루트에서 관리.

마치며

Hook은 AI 코딩 에이전트를 "그냥 쓰는" 도구에서 "내가 제어하는" 도구로 바꿔주는 핵심 메커니즘이다. 처음엔 귀찮아 보여도, 한 번 잘 설정해두면 위험 명령 차단, 자동 품질 검사, 컨텍스트 주입 등이 알아서 돌아간다.

AI 도구를 쓰는 개발자라면 지금 당장 PreToolUse 하나라도 설정해보는 걸 추천한다. "AI가 내 코드베이스에서 무슨 짓을 하는지 감시하는 것"은 생각보다 훨씬 중요하다.

---

이 글은 생성형 AI의 도움을 받아 작성되었습니다. 원본 자료를 기반으로 AI가 초안을 생성하고, 작성자가 검토·편집하였습니다.