# Claude Code Hooks: 프로덕션 CI/CD 패턴 완전 가이드

> 출처: https://www.pixelmojo.io/blogs/claude-code-hooks-production-quality-ci-cd-patterns
> 수집일: 2026-05-13

---

## 개요

Claude Code hooks는 특정 라이프사이클 포인트에서 자동으로 실행되는 강제 메커니즘. 2026년 초 출시. 코딩 표준을 "권고 사항"에서 "Claude가 코드베이스에 접근할 때마다 실행되는 강제 게이트"로 전환.

---

## 핸들러 타입 3가지

### 1. Command Hooks
shell script 실행. JSON을 stdin으로 받고 exit code로 결과 반환.
→ 포맷팅, 린팅, 파일 검증에 적합.

### 2. Prompt Hooks
`$ARGUMENTS` 플레이스홀더로 컨텍스트를 주입해 Claude 모델에 평가 요청.
→ regex로 자동화하기 어려운 **의미론적 결정** (보안 분류 등)에 적합.

### 3. Agent Hooks
도구 접근 권한 있는 subagent 실행 (Read, Grep, Glob).
→ 크로스 파일 검증, 아키텍처 패턴 준수 검사에 적합.

---

## 12개 라이프사이클 이벤트

핵심 이벤트:
- **PreToolUse** (blocking): 실행 전 평가. **유일하게 작업을 거부할 수 있는 훅 타입**
- **PostToolUse** (non-blocking): 실행 후 포맷팅·검증
- **Stop** (non-blocking): Claude 응답 완료 시
- **SubagentStop** (non-blocking): subagent 완료 검증

---

## 프로덕션 패턴

### 자동 포맷팅 (PostToolUse)
```json
{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit|Write",
      "handler": {
        "type": "command",
        "command": "npx prettier --write $FILEPATH"
      }
    }]
  }
}
```

### 중요 파일 보호 (PreToolUse)
```json
{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Edit",
      "handler": {
        "type": "command",
        "command": "node scripts/block-critical.js"
      }
    }]
  }
}
```

### 의존성 가드 (PreToolUse)
프로덕션 패키지 무단 설치 차단:
```json
{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "handler": {
        "type": "command",
        "command": "node scripts/block-deps.js"
      }
    }]
  }
}
```

### Prompt 기반 보안 (PreToolUse)
컨텍스트 의존적 결정을 Claude에 위임:
```json
{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Edit",
      "handler": {
        "type": "prompt",
        "prompt": "Analyze edit: $ARGUMENTS. Check for auth, DB, payments. DENY if any touched."
      }
    }]
  }
}
```

---

## CI/CD 통합

GitHub Actions, GitLab CI와 동일한 hooks 실행. PR/MR 생성 시 트리거 → 결과를 PR 코멘트로 게시 → 모든 품질 게이트 통과 전까지 merge 차단.

통합 포인트:
- PR opened/updated → PostToolUse: lint + type check
- MR opened/updated → PostToolUse: lint + security scan
- git commit → Stop: 전체 품질 스위트
- Scheduled tasks → Agent: 코드베이스 감사

---

## 경쟁 도구 비교

| 기능 | Claude Code | Cursor | Copilot |
|---|---|---|---|
| 핸들러 타입 | Command, Prompt, **Agent** | Command만 | Command만 |
| 작업 차단 가능 | ✅ PreToolUse | ✅ | ✅ |
| LLM 기반 훅 | ✅ | ❌ | ❌ |
| Subagent 훅 | ✅ | ❌ | ❌ |

---

## 설정 파일 위치

- `.claude/settings.json`: 프로젝트 레벨 (팀 공유)
- `~/.claude/settings.json`: 개인 기본값
- 프로젝트 설정이 우선 적용

---

## 도입 로드맵 (단계별)

1. **Phase 1**: PostToolUse 포맷팅 훅 (리스크 없음, 즉각 효과)
2. **Phase 2**: 중요 경로 파일 보호 PreToolUse
3. **Phase 3**: 공급망 공격 대비 의존성 가드
4. **Phase 4**: 의미론적 보안 검토를 위한 Prompt 훅
5. **Phase 5**: 아키텍처 심층 검증을 위한 Agent 훅

---

## 기술 부채 방지 효과 (통계)

- **66% 생산성 세금**: PostToolUse 훅이 포맷팅·타입 오류를 즉시 잡아냄
- **41% 코드 churne**: PreToolUse prompt 훅이 아키텍처 패턴 검증 → 리팩토링 필요 감소
- **45% 취약점 비율**: PreToolUse 보안 훅이 리뷰 없는 민감 영역 편집 차단

> 인간 리뷰어는 아키텍처, 비즈니스 로직, 시스템 설계 등 섬세한 결정에 집중.
> 반복 가능한 검증 작업은 훅이 처리.