Files

- CLAUDE.md 운영 규칙
- wiki/ 정리된 지식 페이지 (Nuxt + Claude Code)
- raw/ 원본 자료
- reference/ Nuxt 4.x 공식 문서

Co-authored-by: Cursor <cursoragent@cursor.com>

2026-05-13 00:31:51 +09:00

4.1 KiB

Raw Blame History

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)

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit|Write",
      "handler": {
        "type": "command",
        "command": "npx prettier --write $FILEPATH"
      }
    }]
  }
}

중요 파일 보호 (PreToolUse)

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Edit",
      "handler": {
        "type": "command",
        "command": "node scripts/block-critical.js"
      }
    }]
  }
}

의존성 가드 (PreToolUse)

프로덕션 패키지 무단 설치 차단:

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "handler": {
        "type": "command",
        "command": "node scripts/block-deps.js"
      }
    }]
  }
}

Prompt 기반 보안 (PreToolUse)

컨텍스트 의존적 결정을 Claude에 위임:

{
  "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: 개인 기본값
프로젝트 설정이 우선 적용

도입 로드맵 (단계별)

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

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

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

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

4.1 KiB Raw Blame History