사내 Claude Code 세미나 3주차 회고: Hooks로 만드는 자동화와 안전장치

{
  "hookSpecificOutput": {
    "permissionDecision": "allow" | "deny" | "ask",
    "permissionDecisionReason": "이유 설명",
    "updatedInput": { "command": "수정된 명령어" },
    "additionalContext": "Claude에게 전달할 추가 컨텍스트"
  }
}

{
  "type": "command",
  "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/spotless-apply.sh",
  "timeout": 600,
  "shell": "bash",
  "async": false
}

{
  "type": "http",
  "url": "https://dev-portal.company.com/api/claude/validate",
  "headers": { "Authorization": "Bearer $DEVPORTAL_TOKEN" }
}

{
  "type": "prompt",
  "prompt": "Does this diff break @Transactional boundaries? $ARGUMENTS",
  "model": "fast-model"
}
// LLM 응답: { "ok": true, "reason": "..." }

{
  "type": "agent",
  "prompt": "Run Checkstyle + SpotBugs on $ARGUMENTS and report blocking issues",
  "model": "claude-3-5-sonnet-20241022"
}

{
  "hooks": {
    "PreToolUse": [               // 이벤트
      {
        "matcher": "Bash",         // 어떤 도구에 적용할지
        "hooks": [                 // 실제 실행할 hook 목록
          { "type": "command", "command": "./hooks/pre-bash.sh" },
          { "type": "command", "command": "./hooks/transform.sh" }
        ]
      },
      {
        "matcher": "Edit|Write",   // 정규식 가능
        "hooks": [{ "type": "command", "command": "./hooks/pre-edit.sh" }]
      }
    ]
  }
}

#!/bin/bash
# .claude/hooks/session-start.sh
 
INPUT=$(cat)
if [ -n "$CLAUDE_ENV_FILE" ]; then
  echo "export SPRING_PROFILES_ACTIVE=local" >> "$CLAUDE_ENV_FILE"
  [ -n "$JAVA_HOME" ] && echo "export JAVA_HOME=$JAVA_HOME" >> "$CLAUDE_ENV_FILE"
fi
 
# Gradle 빌드 캐시 없으면 Claude에게 알림
if [ -f "$CLAUDE_PROJECT_DIR/build.gradle" ] && [ ! -d "$CLAUDE_PROJECT_DIR/build/classes" ]; then
  echo '{"hookSpecificOutput":{"additionalContext":"Spring Boot build 캐시 없음. ./gradlew build 먼저 필요"}}'
fi
exit 0

#!/bin/bash
# .claude/hooks/pre-tool-use-bash.sh
 
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
 
# prod 프로파일로 직접 실행하는 모든 명령 차단
if echo "$COMMAND" | grep -qiE '(bootRun|spring-boot:run|flyway.*migrate).*(prod|production)'; then
  echo "prod 프로파일 실행 차단됨. staging에서 먼저 검증하세요." >&2
  exit 2
fi
 
# clean build는 시간이 오래 걸리므로 사용자에게 확인
if echo "$COMMAND" | grep -qE '(gradlew|gradle)\s+.*clean.*build'; then
  jq -n '{hookSpecificOutput:{permissionDecision:"ask",permissionDecisionReason:"clean build는 오래 걸립니다."}}'
fi
exit 0

#!/bin/bash
# .claude/hooks/post-tool-spotless.sh
 
INPUT=$(cat); TOOL=$(echo "$INPUT" | jq -r '.tool_name')
FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
 
if [ "$TOOL" = "Edit" ] || [ "$TOOL" = "Write" ]; then
  cd "$CLAUDE_PROJECT_DIR" || exit 0
  case "${FILE##*.}" in
    java)    ./gradlew spotlessApply -PspotlessFiles="$FILE" --quiet 2>/dev/null ;;
    kt|kts)  ./gradlew ktlintFormat --quiet 2>/dev/null ;;
    sql)     sqlfluff fix --dialect postgres "$FILE" 2>/dev/null ;;
    xml)     xmllint --format "$FILE" --output "$FILE" 2>/dev/null ;;
  esac
fi
exit 0

#!/bin/bash
# .claude/hooks/stop-verify-gradle.sh
 
CHANGED=$(git diff --name-only 2>/dev/null | grep -E '\.(java|kt|sql)$|pom\.xml|build\.gradle')
 
if [ -n "$CHANGED" ]; then
  TRANSCRIPT=$(echo "$(cat)" | jq -r '.transcript_path // empty')
  if [ -n "$TRANSCRIPT" ] && ! grep -qE '(gradlew|mvnw?)\s+(test|check|verify)' "$TRANSCRIPT" 2>/dev/null; then
    echo "Java 소스 변경됨 but ./gradlew test 미실행!" >&2
    exit 2  # Claude를 멈추지 않게 강제
  fi
fi
exit 0

#!/bin/bash
# .claude/hooks/notification.sh  (async: true 권장)
 
MESSAGE=$(echo "$(cat)" | jq -r '.message // "Claude Code 알림"')
 
# macOS 네이티브 알림
[[ "$OSTYPE" == "darwin"* ]] && osascript -e "display notification \"$MESSAGE\" with title \"Claude Code\""
 
# Slack Webhook
[ -n "$SLACK_WEBHOOK_URL" ] && curl -s -X POST "$SLACK_WEBHOOK_URL" \
  -H 'Content-Type: application/json' -d "{\"text\":\"$MESSAGE\"}" &>/dev/null &
 
exit 0

#!/bin/bash
INPUT=$(cat); FILE=$(echo "$INPUT" | jq -r '.file_path // empty')
 
case "$FILE" in
  */application*.yml|*/application*.yaml|*/application*.properties)
    PROFILE=$(basename "$FILE" | sed -E 's/application-?([^.]*)\..*/\1/')
    jq -n --arg p "${PROFILE:-default}" \
      '{hookSpecificOutput:{additionalContext:("Spring 설정 변경(profile=" + $p + "). @ConfigurationProperties 리바인딩 필요")}}'
    ;;
  */src/main/resources/db/migration/V*__*.sql)
    jq -n --arg f "$FILE" \
      '{hookSpecificOutput:{additionalContext:("Flyway 마이그레이션 변경: " + $f)}}'
    ;;
esac
exit 0