훅(Hooks)으로 편집 후 자동 검증 | 클로드 코드 에이전틱 자동화

Hooks — 편집 이후를 자동으로 처리하기

Claude Code가 파일을 편집하고 나면 그 다음은 어떻게 됩니까? 기존 방식이라면 개발자가 직접 eslint를 돌리고, prettier를 돌리고, 타입 체크를 합니다. Hooks는 이 "편집 후 작업"을 자동화합니다. 특정 이벤트 발생 시 지정한 셸 명령을 자동 실행하는 이벤트 기반 자동화 계층입니다.

Hooks 설정 위치

Hooks는 Claude Code 설정 파일에 등록합니다. 프로젝트별 또는 전역으로 설정할 수 있습니다.

// .claude/settings.json (프로젝트 전용)
// ~/.claude/settings.json (전역 기본값)
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx eslint --fix $FILE 2>&1 || true"
          }
        ]
      }
    ]
  }
}

$FILE은 편집된 파일의 경로로 자동 치환됩니다. || true를 붙이면 린트 오류가 있어도 훅이 실패로 처리되지 않고 계속 진행합니다.

지원되는 이벤트 타입

PostToolUse: 도구 실행 후 — Edit, Write, Bash 등 모든 도구 실행 직후
PreToolUse: 도구 실행 전 — 위험한 명령 차단, 사전 검증에 사용
Notification: Claude가 알림을 보낼 때 — 데스크톱 알림, Slack 메시지 연동
Stop: 작업 완료 후 — 최종 검증, 요약 생성, 정리 작업

실전 훅 예시

TypeScript 파일 자동 포맷 + 타입 체크

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "if [[ '$FILE' == *.ts || '$FILE' == *.tsx ]]; then npx prettier --write '$FILE' && npx tsc --noEmit 2>&1 | head -20; fi"
          }
        ]
      }
    ]
  }
}

SQL 파일 저장 시 마이그레이션 자동 검증

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "if [[ '$FILE' == */migrations/*.sql ]]; then echo '마이그레이션 파일 저장됨: $FILE'; npx supabase db lint '$FILE' 2>&1 || true; fi"
          }
        ]
      }
    ]
  }
}

위험 명령 사전 차단 (PreToolUse)

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "if echo '$COMMAND' | grep -qE 'rm -rf|DROP TABLE|git push --force'; then echo 'BLOCKED: 위험 명령 차단됨' >&2; exit 1; fi"
          }
        ]
      }
    ]
  }
}

exit 1을 반환하면 Claude Code가 해당 도구 호출을 중단합니다. 이를 이용해 팀에서 절대 실행하면 안 되는 명령을 코드 레벨에서 막을 수 있습니다.

작업 완료 시 데스크톱 알림

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code 작업 완료\" with title \"NUGUNA-HRD\"' 2>/dev/null || notify-send 'Claude Code' '작업 완료' 2>/dev/null || true"
          }
        ]
      }
    ]
  }
}

Mac(osascript)과 Linux(notify-send) 모두 지원하며, 지원되지 않는 환경에서는 조용히 넘어갑니다.

훅 환경 변수

$FILE        — 편집된 파일의 절대 경로 (Edit/Write 이벤트)
$COMMAND     — 실행되는 bash 명령 (Bash 이벤트)
$TOOL        — 실행된 도구 이름 (Edit, Write, Bash 등)
$EXIT_CODE   — 이전 명령의 종료 코드 (PostToolUse에서 사용)

훅 vs settings.json 권한 — 언제 무엇을 쓸까

권한(allow/deny): Claude가 특정 도구/명령을 실행할 수 있는지 여부를 제어. "할 수 있는가"의 문제.
훅(Hooks): 도구 실행 전후에 추가 작업 자동 실행. "하고 나서 또 뭘 할까"의 문제.

// 좋은 조합 예시
// settings.json 권한: npm run test*는 자동 허용
// 훅: 테스트 실행 후 결과를 test-results.log에 기록
{
  "permissions": {
    "allow": ["Bash(npm run test*)"]
  },
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "if echo '$COMMAND' | grep -q 'npm run test'; then echo '$(date): $EXIT_CODE' >> test-results.log; fi"
          }
        ]
      }
    ]
  }
}

훅은 "개발자가 항상 하는 반복 작업"을 자동화하는 도구입니다. "저장 후 린트 돌려야지"를 매번 기억하지 않아도 됩니다. 특히 팀 프로젝트에서 코드 스타일과 품질 기준을 자동으로 강제할 수 있어, 리뷰에서 형식 문제 지적이 사라집니다.

핵심 정리

PostToolUse + Edit/Write matcher — 파일 수정 직후 린트·포맷·타입 체크 자동 실행, 품질 게이트를 수동 없이 강제
PreToolUse + 종료코드 1 — 위험 명령(rm -rf, 강제 push) 차단 게이트, 설정 파일로 팀 전체 적용
Stop 이벤트 — 작업 완료 시 데스크톱 알림·슬랙 메시지 연동, 장시간 자동화 작업의 완료 감지에 활용

관련 검색어 · 클로드 코드 · Claude Code · Hooks 자동화 · PostToolUse · PreToolUse · 파일 저장 자동 검증 · 자동 린트 · 코드 품질 자동화