복사해서 바로 사용할 수 있는 Claude Code hook 최소 템플릿 — PreToolUse/PostToolUse/Stop

hook을 작성하고 싶다. 하지만 무엇부터 시작해야 할지 모르겠다.

공식 문서(Official documentation)는 읽었다. 구조는 이해했다. 하지만 "그럼 실제로 파일을 만들어서 실행하기까지"의 과정이 멀게 느껴진다.

이 기사에서는 복사해서 바로 실행할 수 있는 최소 템플릿 3종류를 준비했다. PreToolUse(도구 실행 전), PostToolUse(도구 실행 후), Stop(세션 종료 시). 전부 bash 스크립트이며, 전부 10줄 내외다.

어떤 hook도 동일한 패턴으로 동작한다.

• Claude Code가 stdin에 JSON을 흘려보낸다 - hook이 JSON을 읽고 판단한다
• **종료 코드 (exit code)**로 결과를 반환한다

종료 코드의 의미:

exit code	의미
0	문제 없음. 그대로 계속 진행
1	경고. stderr의 내용을 Claude에게 피드백
2	차단. 도구 실행을 중단 (PreToolUse만 해당)

stdout에 JSON({"decision":"approve"} 등)을 출력하면 허가 판정을 덮어쓸 수 있다. stderr에 작성한 문자열은 Claude에 대한 피드백이 된다.

도구 실행 전에 실행된다. 위험한 조작을 막고 싶을 때 사용한다.

~/.claude/hooks/block-template.sh:

#!/bin/bash
# PreToolUse: 특정 명령어를 차단하는 템플릿
INPUT=$(cat)
...

exit 2가 차단, exit 0이 허가다. stderr에 작성한 이유는 Claude에게 전달되므로, Claude가 대안을 생각해낼 수 있다.

응용 예시: git push --force 차단

if echo "$COMMAND" | grep -qE 'git\s+push\s+.*--force'; then
echo "BLOCKED: force-push detected. Use --force-with-lease instead." >&2
exit 2
...

안전하다고 판단되는 명령어의 허가 프롬프트를 없앤다. Auto Mode가 아니더라도 특정 명령어만 자동으로 통과시키고 싶을 때 편리하다.

~/.claude/hooks/approve-template.sh:

#!/bin/bash
# PreToolUse: 안전한 명령어를 자동 승인하는 템플릿
INPUT=$(cat)
...

stdout에 {"decision":"approve"}를 출력하는 것이 포인트다. 이를 통해 Claude Code의 허가 프롬프트를 스킵할 수 있다.

도구 실행 후에 실행된다. 결과를 검증하여 문제가 있으면 Claude에게 전달한다.

~/.claude/hooks/post-check-template.sh:

#!/bin/bash
# PostToolUse: 실행 결과를 검증하는 템플릿
INPUT=$(cat)
...

exit 1로 경고를 반환한다. 차단은 하지 않는다 (PostToolUse에서는 exit 2를 사용할 수 없다. 실행은 이미 끝났기 때문이다). stderr의 내용이 Claude에게 피드백되어 자동으로 수정을 시도하게 된다.

세션 종료 시에 실행된다. 로그 기록이나 클린업(Cleanup)에 사용한다.

~/.claude/hooks/stop-template.sh:

#!/bin/bash
# Stop: 세션 종료 시의 처리 템플릿
INPUT=$(cat)
...

Stop hook에서는 종료 코드의 의미가 바뀐다. 무엇을 반환하더라도 세션 종료는 멈추지 않는다. stderr에 작성한 내용은 로그로 남는다.

hook 파일을 작성했다면 ~/.claude/settings.json에 등록한다.

{
  "hooks": {
    "PreToolUse": [
      ...
    ]
  }
}

matcher는 도구 이름으로 필터링한다. "Bash"라면 Bash 도구만, "" (빈 문자열)라면 모든 도구에 반응한다. Edit, Write, Read 등 임의의 도구 이름을 지정할 수 있다.

hook을 등록하기 전에 터미널에서 단독 테스트를 할 수 있다.

# PreToolUse 테스트 (rm -rf를 차단하는가?)
echo '{"tool_input":{"command":"rm -rf /"}}' | bash ~/.claude/hooks/block-template.sh
echo $?
...

echo JSON | bash hook.sh; echo $?

이 패턴을 기억해 두면 어떤 hook이든 테스트할 수 있습니다.

템플릿 복사만으로 부족할 때, "하고 싶은 일"을 일본어(또는 자연어)로 전달하면 hook을 자동으로 생성해 주는 도구가 있습니다.

npx cc-safe-setup --create "git commit하기 전에 lint 실행"

442개의 샘플 hook 중에서 유사한 것을 찾아 설치할 수도 있습니다:

# 샘플 목록
npx cc-safe-setup --examples
# 특정 샘플 설치
...

hook의 설계 사상부터 실전 패턴까지 체계적으로 정리한 책: Claude Code 실전 가이드

템플릿은 4가지입니다. PreToolUse 블록, PreToolUse 자동 승인, PostToolUse 검증, Stop 로그 기록. 이 4가지 패턴을 파악하고 있으면 대부분의 요구사항을 충족할 수 있습니다. 우선 하나를 복사해서 붙여넣고 실행해 보시기 바랍니다.