# Claude Code가 이제 훅(hooks)을 지원함

> Clean Markdown view of GeekNews topic #21772. Use the original source for factual precision when an external source URL is present.

## Metadata

- GeekNews HTML: [https://news.hada.io/topic?id=21772](https://news.hada.io/topic?id=21772)
- GeekNews Markdown: [https://news.hada.io/topic/21772.md](https://news.hada.io/topic/21772.md)
- Type: GN+
- Author: [neo](https://news.hada.io/@neo)
- Published: 2025-07-02T09:53:23+09:00
- Updated: 2025-07-02T09:53:23+09:00
- Original source: [docs.anthropic.com](https://docs.anthropic.com/en/docs/claude-code/hooks)
- Points: 20
- Comments: 4

## Summary

Claude Code에 **사용자 정의 훅** 기능이 추가되어, 이제 LLM의 개입 없이 앱의 행동을 **정확하게 반복적으로 제어**할 수 있습니다. **알림 자동화, 코드 포맷팅, 명령 로그 추적** 등 다양한 자동화 작업을 지원하며, **명령 실행 전후 등 특정 이벤트 지점**에서 작동하도록 **설정 파일**로 세밀하게 관리합니다. 모든 훅은 **셸 명령어를 전체 권한으로 실행**하므로, 안전성과 **입력값 검증**은 필수입니다.

## Topic Body

- **Claude Code에 사용자 정의 훅** 기능이 도입. LLM의 선택에 의존하지 않고, 앱의 행동을 더욱 **정확하고 반복적으로 제어**할 수 있음  
- 알림 커스터마이징, 코드 자동 포맷팅, **명령 로그 추적**과 같은 다양한 자동화가 가능  
- **명령어 실행 전/후, 알림 발생, 응답 완료 시점** 등에서 동작하며, **설정 파일을 통해 프로젝트·사용자·엔터프라이즈 레벨로 관리**할 수 있음  
- 설정 파일 구조와 매처(matcher) 방식을 통해, **특정 도구 호출 시점**에 특정 훅만 실행할 수 있음  
- **입력은 JSON 포맷으로 전달**되고, **출력은 exit code 또는 JSON**으로 결과·피드백을 제어함  
- 훅은 **셸 명령어를 사용자의 전체 권한**으로 자동 실행하므로, 보안 및 안전에 대한 주의 필요함  
  
---  
  
### 소개  
  
- Claude Code의 훅(hook)은 **코드 실행 라이프사이클 각 단계에서 자동으로 실행되는 사용자 지정 쉘 명령어**  
- 이를 통해 LLM이 선택적으로 실행하는 것 대신 매번 **일관된 자동화**가 가능해짐  
- # 주요 활용 예시  
  - **알림**: 입력 대기 시 사용자에게 맞춤형 알림 제공  
  - **자동 포맷팅**: 파일 편집 후 `prettier` 또는 `gofmt` 자동 실행  
  - **로깅**: 실행된 명령을 기록하고 집계하여 추적이나 디버깅에 활용  
  - **피드백**: 코드베이스 규칙에 맞지 않는 코드 생성 시 자동 피드백 제공  
  - **커스텀 권한**: 민감 디렉터리나 프로덕션 파일에 대한 변경 차단  
- 프롬프트가 아닌 시스템 코드로 동작하므로, **매번 확정적으로 실행됨** → 자동화의 신뢰성 증가  
- 훅은 **사용자 전체 권한으로 셸 명령**을 직접 실행하므로, 안전성 검증 필요함.   
  
### 구성 예제   
- 예: Claude가 Bash 명령 실행 전마다 로그를 남기도록 후크 등록  
  1\. `/hooks` 명령어로 후크 설정 메뉴 진입, PreToolUse 이벤트 선택  
  2\. `Bash` 매처 추가 (Bash 명령에만 적용)  
  3\. 후크 커맨드 등록 및 저장 (User settings 위치 선택 시 전체 프로젝트에 적용)  
  4\. `/hooks`로 설정 확인 또는 `~/.claude/settings.json`에서 파일 직접 확인 가능  
  
### 설정 구조  
- 후크는 **매처(matcher) 기준으로 그룹화**하며, 매처별로 여러 후크를 배열로 가질 수 있음  
  - 예: 단일 문자열(정확 매칭), 정규식, 비워두면 모든 이벤트에 적용  
- 설정 파일 종류  
  - `~/.claude/settings.json`: 사용자 전체 설정  
  - `.claude/settings.json`: 프로젝트 설정  
  - `.claude/settings.local.json`: 로컬(비공유) 설정  
  - 엔터프라이즈 정책 설정  
  
### 주요 후크 이벤트  
- **PreToolUse**: 툴 호출 전 실행, 필요시 실행 차단 가능 (주요 매처: Bash, Write, Edit, Grep 등)  
- **PostToolUse**: 툴 실행 직후, 동일 매처 지원  
- **Notification**: 알림 전송 시 실행  
- **Stop**: 응답 완료 후 실행  
  
### 매처 예시  
  
- `Task`: 에이전트 작업  
- `Bash`: 셸 명령  
- `Glob`: 파일 패턴 매칭  
- `Grep`: 내용 검색  
- `Read`: 파일 읽기  
- `Edit`, `MultiEdit`: 파일 수정  
- `Write`: 파일 작성  
- `WebFetch`, `WebSearch`: 웹 작업  
  
### 입력 및 출력 형식  
- **입력**: stdin으로 JSON 전달 (세션 정보, 이벤트별 데이터 포함)  
  - 예: PreToolUse에는 tool_input 포함, PostToolUse에는 tool_response 추가  
- **출력**:   
  - **exit code 0**: 정상 실행, stdout은 유저에게 표시  
  - **exit code 2**: 차단, stderr가 Claude에게 피드백으로 전달 (PreToolUse에서는 툴 실행 차단)  
  - **기타 코드**: 오류, stderr만 유저에게 표시  
  - **고급 제어**: stdout에 JSON 반환 시, "continue" false나 "decision": "block" 등 세부 흐름 제어 가능  
  
### MCP 도구와 통합  
- Model Context Protocol(MCP) 기반 툴도 지원하며, 특수 네이밍 패턴(`mcp____`)을 통해 선택적으로 타깃팅 가능  
  
### 보안 권고사항  
- **후크는 시스템 임의 명령 실행의 위험**이 있으므로, 입력값 검증, 경로 체크, 민감 파일 제외, 절대 경로 사용 등 안전 규칙 필수  
- 설정 변경 시 즉시 반영되지 않으며, 세션 시작 시 스냅샷을 사용하고 외부 변경 시 경고 표시  
  
### 실행 환경 및 디버깅  
  
- 각 후크는 **최대 60초 제한, 병렬 실행, 현재 작업 디렉토리·환경에서 동작**  
- `/hooks`에서 설정 확인, 명령 직접 테스트, exit code·출력 체크 등으로 디버깅 가능  
- 실행 과정과 결과는 transcript 모드(Ctrl-R)에서 확인

## Comments



### Comment 40873

- Author: shakespeare
- Created: 2025-07-02T11:36:55+09:00
- Points: 1

윈도우 버전 좀 만들어주세요 ㅠㅠ

### Comment 41005

- Author: nalbam
- Created: 2025-07-06T06:18:17+09:00
- Points: 1
- Parent comment: 40873
- Depth: 1

wsl 사용하세요

### Comment 41101

- Author: slowmo
- Created: 2025-07-08T14:56:37+09:00
- Points: 1
- Parent comment: 41005
- Depth: 2

제 PC 사양이 낮아서인지 윈도우 WSL에서는 클로드 코드를 활용한 일부 작업(예: 프로젝트 빌드, 로컬 웹 서버 실행 등)이 너무 느리네요.   
해당 작업만 수동으로 WSL 외부에서 실행하는 방법도 있지만 귀찮고 제약이 있다보니 Gemini CLI가 나온 후로는 윈도우에선 클로드 코드 대신 Gemini CLI 위주로 사용 중입니다.

### Comment 40862

- Author: neo
- Created: 2025-07-02T09:53:23+09:00
- Points: 1

###### [Hacker News 의견](https://news.ycombinator.com/item?id=44429225) 
- Claude Code Opus 4가 파일 끝에 리턴을 붙이지 않는 버릇 탓에 답답함을 느꼈음  
  새로운 후크를 테스트할 땐 claude를 재시작해야 하므로, 세션 내에서 계속 편집할 수 있는 스크립트를 활용한 편이 훨씬 효율적임  
  이 스크립트는 C 파일과 쉘 스크립트엔 포매터를 적용하고, 기타 파일엔 누락된 리턴만 보정함  
  Claude 같은 AI는 문제를 적절히 쪼개는 데 약하고, 이상한 방식으로 일을 시도하기도 해서, 위의 후크 예제처럼 JSON 파일을 디스크에 저장 후 경로만 빼서 다시 저장해두고, 해당 경로를 save-hook.sh로 넘기는 식으로 여러 번 고쳤음  
  10분 만에 원하는 걸 해냈지만, 한 번에 큰 스텝을 시키느라 낭비한 시간이 더 많았음

- AI가 개발자를 대체할 거란 말들을 듣지만, 이런 후크를 누가 설정하고 새 기능을 제안할지는 여전히 사람의 몫임  
  이런 툴링과 관련된 작업은 AI가 스스로 이 아이디어를 생각해내서 다른 AI에 적용할 수준으로 진화하기 전까진 계속 존재할 상황임

  - 목공 비유를 빗대자면, 지금은 수공구에서 전동공구 시대로 넘어가는 전환점이라고 봄  
    기본기를 이해한 사람이 도구를 잘 다룰 수 있지만, 이제는 손으로 섬세하게 만들던 대신 테이블쏘로 빠르게 작업하는 단계라 효율은 높지만 더 위험할 수도 있다는 이야기임

  - 콤바인 하베스터 같은 농기계가 등장해 농업 일자리를 대체할 거란 주장과 유사함  
    모든 인력이 단순히 기계 조작자로 전환될 거란 게 말이 됨?  
    자동화 도구든, 그게 농업이든 AI든, 단순 전환만이 가치가 아니라는 시각임

  - 유명한 "거북이 등 위의 지구" 이야기처럼, AI 출현 뒤엔 "그럼 그 AI를 누가 관리하지?"라는 논의로 무한반복할 수 있음  
    이미 Claude Code에게 스스로 CLAUDE.md를 업데이트하도록 맡기는 사례도 있어서 자기 후크까지 수정하게 하는 일도 아예 불가능하지 않음  
    하지만 쥬라기 공원처럼 "과연 해야 하는가"에 대한 고민이 빠지기 쉽다는 점이 흥미로움

  - AI가 개발 직업을 줄일 거란 의견과, 그럼 누가 후크를 설정하냐는 의문 모두 맞는 말임  
    기술 발전이 일자리 수 증감 문제로만 단순화되지 않고, 일자리를 없애면서 동시에 새 일자리를 창출한다는 사실을 강조함

  - 사실 대다수 사람에게 이런 작업은 개발이 아니라 유지관리, DevOps 같은 일이라는 생각임  
    SaaS 제품에서도 코드라기보다는 운영과 관련된 작업이 많고, HN 이용자들이 생각하는 본격적 개발과는 차이가 큼

- 이번 기능 도입이 정말 기대됨  
  후크는 에이전트의 맥락 엔지니어링과 런타임 성능 검증에 중요한 역할을 할 전망임  
  엔터프라이즈 컴플라이언스나 행위 감시 등 다양한 상황에 확장 가능함  
  Anthropic이 깃허브 이슈 제안에서 바로 지원한 것도 인상적임  
  [관련 이슈 링크](https://github.com/anthropics/claude-code/issues/712)

  - 실제로 나는 Claude Code대신 cline.bot이라는 VS Code 익스텐션을 쓰고 있음  
    이런 기능은 앞으로 모든 코딩 에이전트에 보급될 필살기라고 생각함

- 이 기능이 좋다고 느끼는 이유는, CLAUDE.md로 우회하지 않고 바로 복잡한 커맨드 실행 제어룰을 작성할 수 있기 때문임  
  예를 들어,  
    docker compose exec django python manage.py test  
  같은 명령은 허용하고  
    docker compose exec django python manage.py makemigrations  
  같은 명령은 차단 가능함

  - 이미 .Claude/settings.json에서 이 정도는 구현 가능함

- 이 기능이 MCP 서버 자체로 동작했다면 더 좋았을 것으로 생각함  
  후크를 미리 약속된 이름의 mcp 툴로 만들어두고, 에이전트가 자동으로 후크를 발견해서 내부 구현을 몰라도 mcp 서버를 재사용하거나 다른 에이전트에서 재활용하는 그림을 상상할 수 있음

- Claude Code가 CLAUDE.md 파일의 지침과 코드베이스의 주요 내용을 자주 까먹어서, 수시로 리마인드 시킬 필요가 있음  
  이번 업데이트가 이 문제를 고칠 수 있을지 기대 중임

  - 예를 들면, "void 함수에서 일찍 리턴 쓰지 마! CLAUDE.md에 그런 패턴 금지라고 되어 있잖아!"  
    Claude가 CLAUDE.md 읽고 "22초, 2.6k 토큰…"  
    "당신 말이 맞음!"이라는 반응임

- 예제 후크 몇 개 공유  
  [후크 작성 및 워크플로 자동화 예시 글](https://cameronwestland.com/building-my-first-claude-code-hooks-automating-the-workflow-i-actually-want)  
  Claude Code가 Cursor와 동등한 수준으로 코드 수정 후 린팅/타입 체크 지원을 갖춘 점이 반가움

- Cursor에도 이런 기능이 들어갔으면 함  
  지금은 임시 방편으로 여러 규칙 조합해서 어느 정도 해결 중임

  - Cursor를 안 쓰는 나로서는 아직도 이걸 쓰는 이유가 있나 궁금함

- 이번 기능이 그동안 존재하던 큰 기능 격차를 해소한다고 봄  
  Claude Code가 커밋을 생성하는 방식 때문에 일반 Git hooks가 대부분 동작하지 않아서, CLAUDE.md를 통해 Qlty CLI로 코드 형식을 자동화하도록 지시하는 편법을 썼는데, Claude가 이를 일관되게 잘 수행하지 못해서 아쉬웠음  
  이번 변화로 더 결정적인 결과를 얻을 수 있음  
  현재 hook 가능한 이벤트가 제한적이긴 하지만, 앞으로 Git commit과 push 이벤트도 쉽게 훅킹 가능해질지 기대됨  
  [Qlty CLI GitHub 링크](https://github.com/qltysh/qlty)

  - 참고로 Claude는 Java를 매우 잘 다룸  
    내 스타일가이드, 들여쓰기 선호까지 정확히 파악해서 자바코드 리포매팅이 필요없는 수준으로 완벽하게 맞춤  
    JavaDoc까지 정교하게 잘 맞춰줘서 놀람  
    아마도 대형 엔터프라이즈 자바 코드 학습량이 어마어마했던 듯함

  - 일반 git hooks가 왜 claude code에서 제대로 동작하지 않는지 궁금함

  - Husky와 lint-staged는 정상적으로 작동했지만, Pre Commit Hooks는 작동하지 않았음

- 내 짧은 이해로, 이 기능은 context를 소모하지 않고, MCP처럼 언제 실행할지 Claude가 결정하는 구조가 아니라 각 툴 사용에 대해 사용자가 직접 지정하는 자동 동작 구조임