Hooks 와 Settings — 도구 실행에 외부 동작 끼우기

LLM 에이전트가 도구를 호출하기 전·후에 외부 동작을 끼우고 싶어지는 자리가 있습니다. 자동 포매터 실행, 변경 감시, 로깅, 정책 검증, 비밀 누출 차단 같은 작업입니다.

1. Claude Code Hooks 에 대한 이야기

Claude Code 가 제공하는 후크 시스템. 모델이 도구를 호출하는 라이프사이클의 정해진 시점에 사용자가 정의한 셸 명령을 실행. 정책 차단·자동 작업·외부 알림 같은 자리.

자주 거론되는 이벤트:

이벤트	시점
PreToolUse	도구 실행 직전.
PostToolUse	도구 실행 직후.
UserPromptSubmit	사용자 입력이 모델로 전달되기 전.
Stop	모델이 응답을 마칠 때.
SessionStart	세션이 시작될 때.
Notification	도구 사용 등 알림 시점.

후크는 셸 명령으로 정의되며, JSON 으로 입력을 받고 종료 코드·표준 출력으로 결과를 돌려줍니다. 종료 코드 0 이면 통과, 다른 값이면 차단·경고.

2. settings.json 의 계층

계층	위치
사용자 전역	~/.claude/settings.json
프로젝트 (공유)	<project>/.claude/settings.json
프로젝트 (개인)	<project>/.claude/settings.local.json
엔터프라이즈	OS·조직별 정해진 자리.

같은 키가 여러 계층에 있으면 정해진 우선순위로 합쳐집니다.

3. 권한 모델

{
  "permissions": {
    "allow": ["Bash(git status)", "Read"],
    "ask":   ["Bash(*)"],
    "deny":  ["Bash(rm -rf *)"]
  }
}

• allow — 자동 허용.
• ask — 호출 시 사용자에게 물음.
• deny — 차단.

도구·인자 패턴 매칭이 가능합니다. 너무 넓으면 (예: Bash(*) 자동 허용) 보안이 약해지고, 너무 좁으면 매번 묻는 피로가 쌓입니다.

4. 후크 정의

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{ "type": "command", "command": "scripts/check-bash.sh" }]
    }],
    "PostToolUse": [{
      "matcher": "Edit",
      "hooks": [{ "type": "command", "command": "scripts/format.sh" }]
    }]
  }
}

스크립트는 이벤트의 JSON 입력 (stdin) 을 받아 처리한 뒤 종료 코드를 반환합니다. 정확한 입력·출력 스키마와 매칭 문법은 공식 문서를 그대로 따르는 것이 안전.

환경 변수 — settings 또는 후크에서 환경 변수를 추가·변경할 수 있습니다. 자격증명은 평문 파일에 두지 않고 OS 시크릿 매니저·환경 변수 외부 로딩과 결합하는 모양이 권장.

5. 다른 도구의 유사 개념

Git pre-commit · pre-push 훅 — .git/hooks/ 또는 husky · lefthook · pre-commit 같은 도구로 관리. 차이는 Git 액션에 묶임.

husky — Node 생태계에서 git 훅 관리에 자주 쓰이는 라이브러리.

pre-commit (Python · 범용) — 다국어 git 훅 도구. 다양한 lint · format 도구와 결합.

lint-staged — 스테이지된 파일에만 lint · format. husky 와 자주 결합.

Cursor · Continue — 다른 AI 코딩 도구도 작업 전·후에 외부 명령을 실행할 수 있는 옵션을 점차 도입.

CI 측 가드 — GitHub Actions · GitLab CI 등에서 PR 단계의 검사. 후크가 빠뜨린 자리를 CI 가 한 번 더 잡는 모양.

6. 보호 스크립트의 예

후크에서 자주 거론되는 자리:

• 비밀 누출 차단 — 코드 변경에 .env · 자격증명 패턴이 들어가면 차단.
• 금지 명령 차단 — rm -rf · DB 의 DROP 같은 비가역 명령.
• 자동 포맷 — Edit 후 prettier · ruff · gofmt · clang-format.
• 테스트 자동 실행 — 특정 디렉터리 변경 시 단위 테스트 호출.
• 알림 — 작업 완료 시 데스크톱 알림 · 메신저 메시지.

7. 이식성 · 디버깅

이식성:

• Windows · Unix — Windows 에서는 .cmd/.ps1, Unix 에서는 .sh. 셔뱅 (#!/usr/bin/env bash) 과 권한 (chmod +x) 일치.
• PATH — 후크에서 호출하는 명령 (prettier · ruff) 이 PATH 에 있어야 함. 가상환경 · nvm 사용 시 주의.
• 인코딩 — Windows 의 기본 콘솔 인코딩과 스크립트 출력 인코딩이 어긋나면 깨짐.

디버깅:

• 후크 스크립트의 표준 출력·에러를 어디서 볼 수 있는지 도구의 로그 위치 확인.
• 시작 시 set -e 같은 옵션과 명확한 에러 메시지.
• 종료 코드의 의미를 확인 후 차단·통과 결정.

8. 자주 걸리는 자리

무한 후크 루프 — 후크가 다시 도구를 호출하는 식의 순환. 매칭 조건을 좁힘.

실수로 모든 명령 자동 허용 — Bash(*) 를 allow 에 두는 식의 실수. 권한 폭이 넓어짐.

신뢰되지 않는 후크 소스 — 다른 사람의 settings 를 그대로 받으면 자기 환경에서 임의 명령이 실행됩니다. 코드 리뷰 후 적용.

민감 정보 로깅 — 후크가 명령 인자 · 파일 내용을 로그에 남기면 비밀이 흘러나감. 마스킹·필터링.

OS 차이 무시 — Unix 만 가정한 셸 스크립트를 그대로 두면 Windows 에서 실패.

계층 우선순위 혼동 — 사용자 · 프로젝트 · 엔터프라이즈 settings 가 합쳐질 때 어느 쪽이 이기는지 헷갈림.

차단 메시지 부재 — 차단 결과만 두고 이유를 비우면 사용자가 디버깅하기 어려움. 친절한 에러.

버전 호환 — 후크 이벤트 이름·입력 스키마가 바뀔 수 있습니다. 도구 업데이트 시 동작 확인.

하고픈 말

Hooks 는 자동 포맷 · 비밀 누출 차단 · 정책 검증의 자리에서 강력합니다. 다만 권한이 너무 넓어지면 보안이 약해지고, 신뢰되지 않은 source 의 settings 를 그대로 받으면 임의 명령이 실행될 수 있어 위험합니다. 작은 운영은 git 측 훅 + CI 측 가드 두 층이면 충분합니다.

Next

• claude-md-pattern
• ai-coding-ides

Claude Code Settings · Claude Code Hooks · Git githooks · pre-commit · husky · lint-staged · GitHub Actions 를 참고합니다.