배경 및 맥락
AI 에이전트는 뛰어난 추론 능력이 있지만 확률적입니다. 같은 작업을 두 번 하면 다른 결과가 나올 수 있고, 위험한 명령을 실행할 수도 있으며, 특정 포맷을 강제할 수 없습니다. 특히 프로덕션 환경이나 규제가 강한 산업에서는 이런 불확실성을 받아들이기 어렵습니다. Anthropic의 Claude Code는 이러한 문제를 Hooks 시스템으로 해결하려 합니다. 에이전트의 라이프사이클 각 지점에 개발자가 **결정론적 가드레일(deterministic guardrails)**을 설치할 수 있게 하는 것입니다.
핵심 내용
Claude Code Hooks는 AI 에이전트의 동작을 세밀하게 제어할 수 있는 이벤트 기반 시스템입니다.
3가지 핸들러 타입:
- Command (
type: "command"): 셸 명령을 실행하는 가장 경량의 핸들러- JSON을 stdin으로 받음
- exit code로 제어 (0=성공, 2=차단)
- stderr 메시지가 Claude에게 에러로 전달
- Prompt (
type: "prompt"): Claude 모델에 단일 턴 평가를 요청- 자신의 추론 능력을 활용한 검증
- 비용이 들지만 복잡한 판단에 유용
- Agent (
type: "agent"): 도구 접근 가능한 서브 에이전트 생성- Read, Grep, Glob 등 파일 시스템 도구 사용 가능
- 가장 강력하지만 리소스 소비도 많음
라이프사이클 이벤트:
- SessionStart: 세션 시작 시 → 초기 설정, 환경 검증
- PreToolUse: 도구 실행 전 → 위험한 작업 사전 차단 (가장 중요)
- PostToolUse: 도구 실행 후 → 결과 포맷팅, 자동 정리
- Notification: 알림 필요 시 → 외부 시스템 통지
- Stop: 응답 생성 완료 시 → 최종 체크, 로깅
제어 메커니즘:
Exit code 2를 반환하면 해당 도구 호출이 차단되고, stderr의 메시지가 Claude에게 에러로 전달됩니다. 예를 들어 git push --force 같은 위험한 명령은 PreToolUse에서 감지하여 차단할 수 있습니다.
설정 위치 (우선순위):
~/.claude/settings.json(전체 시스템).claude/settings.json(프로젝트별, Git 공유).claude/settings.local.json(프로젝트별, gitignore)
경쟁 구도 / 비교
vs. CLAUDE.md (기존 방식):
- CLAUDE.md: "아마 따를 것" (Claude가 읽지 않을 수도 있음)
- Hooks: "항상 실행" (강제성이 보장됨)
이 차이는 프로덕션 환경에서 결정적입니다. CLAUDE.md는 가이드라인에 불과하지만, Hooks는 코드 레벨의 강제를 제공합니다.
vs. 전통적 CI/CD 검증:
- CI/CD: 배포 후 검사 (이미 늦음)
- Hooks: 실행 전 차단 (즉시 대응)
의미
Hooks 시스템은 AI 에이전트를 엔터프라이즈 환경에 도입하기 위한 핵심 인프라입니다. 확률적 AI의 특성상 완벽한 제어는 불가능하지만, 최소한 재앙적인 행동은 사전에 방지할 수 있습니다. 이는 금융, 헬스케어, 중요 인프라 같은 규제 강한 분야에서 AI 에이전트 도입을 현실화하는 데 필수적입니다.
장기적으로는 이러한 "검증 계층(validation layer)" 개념이 AI 시스템 설계의 표준이 될 가능성이 높습니다. 단순한 "프롬프트 엔지니어링"에서 벗어나, 구조화된 제어 메커니즘으로 AI 에이전트를 다루는 문화가 정착되는 과정이라고 볼 수 있습니다.