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.0 KiB

Raw Blame History

Claude Code Hooks 완전 가이드

카테고리: 패턴 & 레시피 최종 수정: 2026-05-13 관련: claude-code-project-setup, claude-code-overview

요약

Hooks는 Claude Code의 라이프사이클 포인트에서 자동으로 실행되는 강제 메커니즘이다. CLAUDE.md 지시는 "권고 사항"이지만, Hooks는 결정론적으로 매번 실행된다 — 예외 없이.

핸들러 타입 3가지

타입	동작	적합한 용도
Command	shell script 실행. JSON → stdin, exit code로 결과 반환	포맷팅, 린팅, 파일 검증
Prompt	`$ARGUMENTS` 주입해 Claude 모델에 평가 요청	regex로 불가한 의미론적 결정 (보안 분류 등)
Agent	subagent 실행 (Read, Grep, Glob 도구 접근)	크로스 파일 검증, 아키텍처 패턴 준수

💡 경험: Claude Code가 Cursor, Copilot보다 차별화되는 핵심이 Prompt 훅과 Agent 훅이다. LLM이 판단할 수 있는 영역(보안, 아키텍처 패턴)을 훅으로 위임할 수 있다.

핵심 이벤트

이벤트	Blocking	용도
PreToolUse	✅ (유일)	실행 전 평가. 작업을 거부할 수 있는 유일한 훅
PostToolUse	❌	실행 후 포맷팅·검증
Stop	❌	Claude 응답 완료 시
SubagentStop	❌	subagent 완료 검증

프로덕션 패턴 (설정 예시)

자동 포맷팅 — 파일 편집 후 Prettier 실행

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

중요 파일 보호 — 특정 파일 편집 차단

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

의존성 가드 — 프로덕션 패키지 무단 설치 차단

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

Prompt 기반 보안 — 민감 영역 편집을 Claude에게 판단 위임

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Edit",
      "handler": {
        "type": "prompt",
        "prompt": "Analyze edit: $ARGUMENTS. Check for auth, DB, payments. DENY if any touched."
      }
    }]
  }
}

설정 파일 위치

파일	범위	우선순위
`.claude/settings.json`	프로젝트 레벨 (팀 공유)	높음
`~/.claude/settings.json`	개인 기본값	낮음

CI/CD 통합

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

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

도입 로드맵 (단계별)

Phase	훅 종류	내용	리스크
1	PostToolUse	자동 포맷팅 (Prettier, ESLint)	없음, 즉각 효과
2	PreToolUse	중요 경로 파일 보호	낮음
3	PreToolUse	의존성 가드 (공급망 공격 방지)	중간
4	Prompt	의미론적 보안 검토	중간
5	Agent	아키텍처 심층 검증	높음 (충분한 테스트 후 도입)

훅을 도입해야 하는 기준

CLAUDE.md에 같은 지시를 두 번 이상 추가했다면 → Hook으로 이전할 타이밍. "매번 예외 없이 실행되어야 하는가?" → Yes면 Hook.

참고 / 출처

raw/claude-code-hooks-cicd-patterns.md (pixelmojo.io)
raw/claude-code-full-stack-mcp-skills-subagents-hooks.md (alexop.dev)
raw/claude-code-best-practices-official.md (code.claude.com 공식 문서)

4.0 KiB Raw Blame History