gil
5f664546cf
- CLAUDE.md 운영 규칙 - wiki/ 정리된 지식 페이지 (Nuxt + Claude Code) - raw/ 원본 자료 - reference/ Nuxt 4.x 공식 문서 Co-authored-by: Cursor <cursoragent@cursor.com>
155 lines
4.1 KiB
Markdown
155 lines
4.1 KiB
Markdown
# 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 보안 훅이 리뷰 없는 민감 영역 편집 차단
|
|
|
|
> 인간 리뷰어는 아키텍처, 비즈니스 로직, 시스템 설계 등 섬세한 결정에 집중.
|
|
> 반복 가능한 검증 작업은 훅이 처리.
|