Hooks Setup

Claude Code hooks를 설정하고 관리합니다.

Hook 개요

이벤트	시점	용도
`PreToolUse`	도구 실행 전	검증, 경고, 자동 승인
`PostToolUse`	도구 실행 후	포맷팅, 린트, 체크
`UserPromptSubmit`	프롬프트 제출 시	컨텍스트 추가, 검증
`Stop`	응답 완료 시	최종 검증, 정리
`SessionStart`	세션 시작 시	환경 설정
`Notification`	알림 발생 시	알림 처리

Instructions

워크플로우 1: 프로젝트에 hooks 설정

프로젝트 분석

# 언어/프레임워크 감지
Read package.json      # Node.js
Read pyproject.toml    # Python
Read go.mod            # Go

적합한 레시피 선택

프로젝트 권장 레시피

TypeScript/JavaScript prettier, eslint, console-log-check

Python ruff, mypy

Go gofmt, golint

프로젝트	권장 레시피
TypeScript/JavaScript	prettier, eslint, console-log-check
Python	ruff, mypy
Go	gofmt, golint

설정 파일 생성

.claude/settings.json:

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

완료 안내

✅ Hooks 설정 완료: .claude/settings.json
/hooks 명령어로 확인 가능

워크플로우 2: 기존 hooks 수정

현재 설정 확인
```
Read .claude/settings.json
```
Edit으로 수정

설정 파일 위치

위치	경로	범위
글로벌	`~/.claude/settings.json`	모든 프로젝트
프로젝트	`.claude/settings.json`	현재 프로젝트 (커밋)
로컬	`.claude/settings.local.json`	현재 프로젝트 (비커밋)

Hook 레시피

prettier (TypeScript/JavaScript)

{
  "PostToolUse": [
    {
      "matcher": "Edit|Write",
      "hooks": [{ "type": "command", "command": "npx prettier --write \"${file_path}\"", "timeout": 30 }]
    }
  ]
}

eslint

{
  "PostToolUse": [
    {
      "matcher": "Edit|Write",
      "hooks": [{ "type": "command", "command": "npx eslint --fix \"${file_path}\"", "timeout": 30 }]
    }
  ]
}

ruff (Python)

{
  "PostToolUse": [
    {
      "matcher": "Edit|Write",
      "hooks": [{ "type": "command", "command": "ruff format \"${file_path}\" && ruff check --fix \"${file_path}\"" }]
    }
  ]
}

console.log 체크 (경고만 - exit 0, 차단 안함)

{
  "Stop": [
    {
      "hooks": [{ "type": "command", "command": "git diff --cached --name-only | xargs grep -l 'console.log' 2>/dev/null && echo '⚠️ console.log detected' || true" }]
    }
  ]
}

차단하려면 (exit 2 사용):

git diff --cached --name-only | xargs grep -l 'console.log' 2>/dev/null && { echo 'console.log found' >&2; exit 2; } || true

환경 변수

변수	설명
`$CLAUDE_PROJECT_DIR`	프로젝트 루트 경로
`$CLAUDE_ENV_FILE`	환경변수 저장 파일 (SessionStart)

Hook 출력 제어

Exit Code	동작
0	성공 (stdout → verbose 모드 표시)
2	블로킹 (stderr → 에러, 도구 차단)
기타	비블로킹 에러

JSON 제어 (PreToolUse)

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow|deny|ask",
    "permissionDecisionReason": "이유"
  }
}

중요 원칙

프로젝트별 설정 우선: .claude/settings.json 사용
timeout 설정: 장시간 명령어는 timeout 명시
경로 인용: 공백 포함 경로 대비 따옴표 사용

Examples

TypeScript 프로젝트

User: /hooks-setup → 분석 → prettier + eslint 설정

Python 프로젝트

User: /hooks-setup python → ruff 레시피 적용

커스텀 hook

User: "Stop 시 테스트 실행 hook" → Stop hook 설정

Technical Details

Matcher 패턴

패턴	매칭
`Edit`	Edit만
`Edit\|Write`	Edit 또는 Write
`*`	모든 도구
`mcp__memory__.*`	MCP 도구

변경 적용

hooks 변경 후 /hooks에서 리뷰 필요 (보안상 자동 미적용)