Claude Code Hooks 사용법: 코드 수정 전후 자동 검증하기

AI에게 프로그램 수정을 맡겼는데 화면을 열어 보니 오타가 있거나 코드 문법이 깨져 있었던 경험이 있나요? 예를 들어 Claude Code에게 “버튼을 눌렀을 때 숫자가 하나 증가하게 해 줘”라고 요청했는데, 수정이 끝난 뒤에는 다른 코드에서 오류가 발생할 수 있습니다. 매번 사람이 파일을 열고 문법 검사를 직접 실행하면 번거롭습니다. Claude Code Hooks(훅)는 이런 상황에서 유용합니다.

Claude Code가 도구를 사용하기 전이나 후 같은 정해진 순간에, 미리 등록한 검사 명령을 자동으로 실행할 수 있습니다. 예를 들어 파일을 고친 직후 간단한 문법 검사를 돌리고, 실패하면 Claude에게 원인을 확인하라는 신호를 보낼 수 있습니다. 이번 글에서는 Hooks 이해하기 → 설정 파일 준비 → 코드 수정 후 자동 검사 → 위험한 수정 사전 차단 → 테스트 → 오류 해결 순서로 설명합니다.

코딩이 낯선 독자를 위해 하나의 작은 JavaScript 프로젝트를 예로 듭니다. 이 글의 기능 설명은 2026년 10월 16일 확인한 Anthropic의 Claude Code 공식 문서를 기준으로 합니다. 도구 버전과 사용 환경에 따라 동작이 달라질 수 있으며, 아래 예시는 작성자가 직접 실행에 성공했다는 실측 후기가 아닙니다.

이 글의 순서

• 1. Claude Code Hooks란 무엇인가요?
• 2. PreToolUse와 PostToolUse의 핵심 차이
• 3. 시작 전에 준비할 것
• 4. 훅 설정 파일은 어디에 있나요?
• 5. 첫 실습: 코드 수정 후 JavaScript 문법 검사 실행하기
• 6. 훅이 실제로 등록됐는지 확인하기
• 7. 정상 코드와 오류 코드로 검사하기
• 8. 검사 결과가 Claude에게 전달되는 원리
• 9. 코드 수정 전 검사가 필요하다면: PreToolUse
• 10. Hooks와 CLAUDE.md , GitHub Actions의 차이
• 11. 자주 발생하는 오류와 해결 방법
• 12. 처음 시작할 때 추천하는 안전한 운영 방식
• 자주 묻는 질문 (FAQ)
• 마무리: 'AI가 수정했다'보다 '무엇을 확인했는가'가 중요합니다

1. Claude Code Hooks란 무엇인가요?

훅은 특정 순간에 자동으로 실행되는 규칙입니다. 집에 들어가기 전에 신발을 벗는 규칙을 생각해 보세요. 사람이 그때마다 규칙을 외우지 않아도 출입구라는 장소에서 같은 행동을 하게 됩니다. Claude Code에서도 비슷한 방식을 만들 수 있습니다.

• 작업 전: AI가 위험한 도구 명령을 실행하려는 순간 해당 호출을 검사합니다.
• 작업 후: AI가 파일을 수정한 뒤 문법 검사나 코드 정리 명령을 실행합니다.
• 작업이 끝나려 할 때: 필요한 검토가 남았는지 확인하는 별도 훅을 구성할 수 있습니다. 단, 훅을 설치한다고 AI 코드가 자동으로 완벽해지는 것은 아닙니다. 무엇을 검사할지를 구체적으로 설정해야 하며, 훅 자체에도 오류가 생길 수 있습니다.

2. PreToolUse와 PostToolUse의 핵심 차이

처음에는 이름 두 개만 기억하면 됩니다.

구분	PreToolUse	PostToolUse
실행 시점	도구가 실제 실행되기 전	도구가 성공적으로 실행된 뒤
주요 용도	위험한 호출 확인·거부	파일 문법 검사·코드 포맷 검사
동작 제어	호출 차단 가능	이미 실행한 작업을 되돌릴 수 없음
쉬운 비유	문 앞 보안 검사	작업이 끝난 뒤 품질 검사

예를 들어 Claude가 파일을 수정하려고 할 때, PreToolUse에서 특정 비밀정보 파일에 대한 편집을 막는 규칙을 만들 수 있습니다. 파일이 이미 수정된 다음에 실행되는 PostToolUse는 변경을 막을 수 없지만, 오류를 발견해 Claude에게 알릴 수 있습니다. 이 차이를 놓치면 “검사 훅이 있으니 위험한 변경이 모두 예방된다”라고 잘못 생각할 수 있습니다. 사전 예방과 사후 점검은 별개의 단계입니다.

3. 시작 전에 준비할 것

이번 실습은 macOS·Linux 계열 터미널과 Bash 스크립트를 기준으로 작성했습니다. Windows에서는 WSL 같은 Bash 사용 환경을 갖추거나 PowerShell 방식으로 변경해야 합니다. 필요한 준비물은 다음과 같습니다.

1. 실행 가능한 Claude Code 및 연습용 프로젝트 폴더.
2. Node.js — JavaScript 문법을 검사할 도구.
3. jq — Claude Code가 훅에 전달하는 JSON에서 파일 경로를 읽을 도구.
4. 편집할 수 있는 프로젝트 설정 파일. 터미널에서 아래 두 명령으로 도구가 설치돼 있는지 확인할 수 있습니다.

node --version
jq --version

버전 번호가 표시되지 않으면 해당 도구를 먼저 설치하고 설정해야 합니다. 기존에 중요한 업무용 프로젝트가 있다면 그 프로젝트에 바로 적용하지 말고, 별도의 연습용 폴더에서 실습하세요. 또한 훅은 컴퓨터에서 명령을 실행할 수 있으므로, 인터넷에서 받은 설정을 이해하지 못한 채 복사해 넣지 않는 편이 안전합니다.

자체 제작 개념도 · EMFLS AI

4. 훅 설정 파일은 어디에 있나요?

Claude Code 공식 문서에 따르면 훅은 JSON 설정 파일에 정의할 수 있습니다.

설정 위치	적용 범위	언제 사용하나요?
\~/.claude/settings.json	내 사용자 환경의 프로젝트들	개인 공통 규칙
.claude/settings.json	해당 프로젝트	팀이 공유·검토할 규칙
.claude/settings.local.json	해당 프로젝트의 개인 설정	개인 실험용 설정

이 글에서는 프로젝트 폴더 안의 .claude/settings.json을 사용합니다. 연습용 폴더 이름을 my-project로 정했다면 구조는 다음과 같습니다.

my-project/
├─ .claude/
│  ├─ settings.json
│  └─ hooks/
│     └─ check-js-syntax.sh
└─ src/
   └─ sample.js

settings.json은 어떤 순간에 어떤 스크립트를 실행할지 알려 주는 파일이고, check-js-syntax.sh는 실제 검사를 담당하는 파일입니다. 주의: 이미 settings.json에 다른 설정이 있다면 파일 전체를 덮어쓰지 마세요. 기존 JSON의 설정을 보존하면서 hooks 항목을 추가해야 합니다. 조직에서 관리하는 프로젝트라면 저장소에 반영하기 전에 코드 리뷰를 받으세요.

5. 첫 실습: 코드 수정 후 JavaScript 문법 검사 실행하기

우리가 만들 규칙은 매우 단순합니다.

Claude Code가 JavaScript 파일을 수정하면, 그 파일의 문법을 자동으로 검사하고 오류가 있다면 알려 준다. 검사 대상은 .js, .mjs, .cjs 파일입니다. 다른 형식까지 무조건 검사하면 엉뚱한 명령이 실행될 수 있으므로 처음에는 범위를 좁혀 둡니다.

1단계 — 스크립트 만들기

프로젝트의 .claude/hooks/ 폴더 안에 check-js-syntax.sh 파일을 만든 다음 다음 내용을 넣습니다.

#!/usr/bin/env bash
# Claude가 수정한 JavaScript 파일의 문법만 확인합니다.
set -u

# Claude Code의 도구 이벤트 JSON은 표준 입력(stdin)으로 전달됩니다.
file="$(jq -r '.tool_input.file_path // empty')" || {
  echo "이벤트 JSON을 읽지 못했습니다." >&2
  exit 2
}

# 문법 검사를 지원하기로 한 파일 확장자만 처리합니다.
case "$file" in
  *.js|*.mjs|*.cjs) ;;
  *) exit 0 ;;
esac

if [ ! -f "$file" ]; then
  echo "검사할 파일을 찾지 못했습니다: $file" >&2
  exit 2
fi

# node --check는 코드를 실제로 실행하지 않고 문법을 확인합니다.
if ! node --check "$file" >/dev/null 2>&1; then
  echo "JavaScript 문법 검사 실패: $file" >&2
  echo "해당 파일에서 node --check를 직접 실행해 원인을 확인하세요." >&2
  exit 2
fi

exit 0

처음에는 길어 보이지만 핵심은 세 단계뿐입니다. ① Claude Code가 보내 준 파일 경로를 읽고, ② JavaScript 파일일 때만 검사하며, ③ 문법이 틀리면 오류 메시지를 반환하는 것입니다. 여기서 node --check는 JavaScript 문법만 검사합니다. 프로그램의 계산 결과가 맞는지, 로그인 기능이 안전한지, 버튼이 화면에서 실제로 눌리는지까지 검사하는 명령은 아닙니다.

2단계 — 실행 권한 설정하기

macOS나 Linux 터미널에서 프로젝트 폴더로 이동한 뒤 다음 명령을 사용합니다.

chmod +x .claude/hooks/check-js-syntax.sh

이는 앞에서 만든 스크립트를 실행 가능하게 하는 작업입니다. 프로젝트 경로가 다르면 자신의 위치를 확인하세요.

3단계 — Claude Code 설정에 훅 등록하기

.claude/settings.json에 다음 내용을 설정합니다.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/check-js-syntax.sh",
            "args": [],
            "timeout": 30
          }
        ]
      }
    ]
  }
}

이 설정에서 중요한 부분은 다음과 같습니다.

• PostToolUse: Claude Code의 도구가 성공적으로 실행된 뒤에 검사합니다.
• Edit|Write: Claude Code가 Edit 또는 Write라는 이름의 도구를 호출했을 때만 훅을 실행합니다.
• type: command: 등록한 셸 스크립트를 실행합니다.
• command: 검사 스크립트의 위치입니다.
• timeout: 검사에 허용할 시간(초)입니다. 프로젝트 루트를 가리키는 공식 경로 변수 덕분에 다른 폴더에서 작업하더라도 같은 스크립트를 찾을 수 있습니다. 이 예시는 파일 수정 도구만 대상으로 하므로, Bash 명령으로 직접 변경한 모든 파일이 자동 검사되는 것은 아닙니다.

6. 훅이 실제로 등록됐는지 확인하기

설정 파일을 저장한 뒤 Claude Code를 실행하고 /hooks를 입력합니다. 공식 문서에 따르면 현재 이 메뉴는 설정된 훅을 조회하는 읽기 전용 목록입니다. 확인할 내용은 다음과 같습니다.

• 이벤트 이름이 PostToolUse인지.
• Matcher가 Edit|Write인지.
• 검사 스크립트 경로가 맞는지.
• 설정 출처가 프로젝트 설정인지.
• 실행 명령과 시간 제한이 의도한 내용인지. 중요: 예전 안내에서는 /hooks 화면에서 새 훅을 직접 만든다고 소개하기도 하지만, 현재 공식 문서는 설정 파일을 편집하고 /hooks에서 결과를 확인하는 방식을 설명합니다. 목록에 나타나지 않으면 JSON 문법, 파일 경로, 실행 권한을 확인하세요. 변경 사항이 자동으로 반영되지 않으면 Claude Code 세션을 다시 시작해 확인할 수 있습니다.

7. 정상 코드와 오류 코드로 검사하기

훅이 준비되었다고 해서 실제로 검사까지 성공했다는 뜻은 아닙니다. 정상 사례와 실패 사례를 각각 시도해야 합니다. 연습용 src/sample.js 파일을 만들고 다음처럼 적어 보세요.

function add(a, b) {
  return a + b;
}

console.log(add(2, 3));

이제 Claude Code에게 다음처럼 요청할 수 있습니다.

src/sample.js 파일을 읽어 줘.
기존 함수는 유지하고 설명용 주석 한 줄만 추가해 줘.
수정한 뒤 PostToolUse Hooks가 어떤 검사를 수행했는지
결과와 근거를 설명해 줘.

예상되는 정상 흐름은 파일 편집 → PostToolUse 훅 실행 → JavaScript 문법 검사 → 정상 종료입니다. 실패 사례는 테스트용 파일에 일부러 문법 오류를 만들거나, AI가 수정 과정에서 잘못된 괄호를 넣도록 하는 등 안전한 연습용 파일에서만 수행합니다. 예를 들어 다음 코드는 닫는 괄호가 빠져 문법 검사에서 오류가 발생할 수 있습니다.

function add(a, b) {
  return a + b;

console.log(add(2, 3));

이 경우 node --check가 실패하면 훅이 오류 메시지를 Claude Code에 전달하도록 설계했습니다. 여기서 알아야 할 점은 PostToolUse 훅이 이미 이루어진 파일 수정을 되돌려 주지는 않는다는 것입니다. 오류를 발견한 뒤에는 Claude 또는 사용자가 파일을 고치고 다시 검증해야 합니다. 이 글은 이런 테스트를 어떻게 하는지 안내하는 자료이지, 작성자가 실제 기기에서 테스트를 돌려 PASS를 확인한 기록은 아닙니다.

8. 검사 결과가 Claude에게 전달되는 원리

Claude Code의 명령형 훅은 보통 표준 입력으로 JSON 데이터를 받습니다. 그 안에 현재 호출한 도구 이름과 인수 등이 들어 있을 수 있습니다. 예를 들어 다음은 구조 이해를 위한 단순화된 이벤트 예시입니다.

{
  "hook_event_name": "PostToolUse",
  "tool_name": "Write",
  "tool_input": {
    "file_path": "src/sample.js"
  }
}

이렇게 받은 경로를 스크립트가 읽어 검사를 실행합니다. 반환 방식에도 차이가 있습니다.

종료 상태	일반적인 의미	알아야 할 점
0	훅 정상 종료	아무 출력이 없으면 보통 추가 조치 없이 진행
2	훅이 차단·오류 신호 전달	PreToolUse는 사전 차단, PostToolUse는 실행 후 오류 알림
1 등 기타	훅 자체 오류로 처리될 수 있음	일부 이벤트에서 호출 차단 없이 계속 진행 가능

특히 일반 프로그램의 실패 코드 1을 반환하면 AI 작업이 반드시 차단된다고 생각하면 안 됩니다. 공식 문서는 이벤트별 처리 규칙과 코드 2의 의미를 구분합니다. 검증이 실패한 사실을 Claude에게 보여 주고 싶다면 stderr(오류 출력)와 종료 코드 2를 올바르게 사용해야 합니다.