Claude Code hooks 활용 정리 — 안전성·로그·작업 시간을 전자동화하기

지난 기사(Claude Code 후크 설정 정리 — 음성 읽어주기 및 macOS/Windows 알림 자동화)에서는 작업 완료나 권한 확인을 음성으로 알리는 후크(hook)를 소개했습니다.

hooks의 편리함을 깨달아 버렸기에, 이번에는 더욱 실용적인 3가지 후크를 설정했습니다.

PreToolUse (Bash): 위험한 명령어를 자동으로 차단
PreToolUse (모든 도구): 도구 실행 로그를 자동으로 기록
Stop: 작업 시간을 자동으로 측정 및 기록

덤으로 "hooks는 토큰을 거의 소비하지 않는다"라는 이야기도 마지막에 정리해 두었습니다.

PreToolUse

• 후크로 rm -rf 등의 위험한 명령어를 Claude가 실행하기 전에 차단할 수 있음
• 모든 도구 실행을 타임스탬프와 함께 로그 파일에 기록할 수 있음

Stop

• 후크로 태스크 소요 시간을 자동으로 기록할 수 있음
• hooks는 기본적으로 토큰 및 컨텍스트(context)를 소비하지 않음 (async: true라면 완전히 제로)

~/.claude/settings.json (글로벌 설정)

후크 스크립트는 ~/.claude/hooks/ 디렉토리에 모아서 관리합니다.

mkdir -p ~/.claude/hooks

Claude가 rm -rf나 DROP TABLE 등의 위험한 명령어를 실행하려고 하는 순간 차단합니다. Claude 측에 에러가 반환되며, 실행되지 않습니다.

#!/usr/bin/env python3
import sys
import json
...

"PreToolUse": [
{
"matcher": "Bash",
...

• matcher: "Bash": Bash 도구 실행 시에만 발화
• 동기 실행: 차단을 위해서는 동기(synchronous) 방식이 필수. async: true라면 차단할 수 없음
• exit code 2: Claude Code의 사양으로, exit 2를 반환하면 해당 도구 실행을 차단하고 Claude에게 에러를 반환함

Claude에게 위험한 조작을 요청하면:

⛔ 위험한 명령어를 차단했습니다
패턴: rm -rf
명령어: rm -rf /tmp/...

Claude는 에러를 받고 다른 수단을 검토하거나 조작을 중지합니다.

Claude가 Bash, Read, Write, Edit, WebSearch 등을 실행할 때마다 타임스탬프와 함께 ~/.claude/tool_log.txt에 기록합니다. "오늘 Claude가 무엇을 했는지"를 나중에 확인할 수 있습니다.

#!/usr/bin/env python3
import sys
import json
...

"PreToolUse": [
{
"hooks": [
...

# 통상 확인
cat ~/.claude/tool_log.txt
# 실시간으로 출력
...

2026-06-04 22:35:06 [1aca92a7] [Bash] ls -la
2026-06-04 22:35:10 [1aca92a7] [Read] /Users/.../.claude/settings.json
2026-06-04 22:35:12 [1aca92a7] [Edit] /Users/.../.claude/settings.json
...

태스크 완료 시 소요 시간을 계산하여 ~/.claude/work_log.txt에 기록합니다. 로그 기록 스크립트(설정 ②)가 세션 시작 시각을 /tmp/claude_session_<id>에 저장하고 있으므로, 그것을 참조하여 경과 시간을 산출합니다.

#!/usr/bin/env python3
import sys
import json
...

"Stop": [
{
"hooks": [
...

cat ~/.claude/work_log.txt

2026-06-04 22:35:11 태스크 완료 | 소요 시간: 3분 42초
2026-06-04 22:58:30 태스크 완료 | 소요 시간: 12분 7초

3가지를 모두 설정했을 경우의 hooks 섹션입니다.

"hooks": {
"Stop": [
{
...

hooks는 Claude Code의 하네스(Harness, CLI 실행 기반) 측에서 동작하는 메커니즘으로, Claude API 호출과는 독립되어 있습니다.

후크 상태	토큰 소비
async: true 후크 전반	제로 (출력이 Claude로 반환되지 않음)
Stop 후크	제로 (Claude가 응답을 마친 후에 실행)
PreToolUse 통과 시 (exit 0)	제로
PreToolUse 차단 시 (exit 2)	수십~100 토큰 정도 (에러 메시지가 Claude로 반환됨)

이번에 설정한 3가지 중 토큰이 발생하는 경우는 위험한 명령어를 실제로 차단했을 때뿐입니다. 일반적인 사용 시에는 거의 제로에 가깝습니다.

마음껏 추가해도 API 비용이나 컨텍스트(Context)를 압박하지 않습니다.

후크	타이밍	효과
PreToolUse (Bash)	Bash 실행 전	위험한 명령어를 자동으로 차단
PreToolUse (모든 도구)	모든 도구 실행 전	~/.claude/tool_log.txt에 기록
Stop	태스크 완료 후	~/.claude/work_log.txt에 소요 시간을 기록

hooks의 가장 큰 강점은 "설정해 두면 신경 쓸 필요가 없다"는 점입니다. Claude Code를 안심하고 사용하기 위한 기반으로서 꼭 도입해 보시기 바랍니다.