Claude Code의 hooks로 작업 자동화하기

{

명령어로 파일을 덮어쓸 때는 작동하지 않습니다. 이 점은 공식 문서에 명시되어 있습니다.

어떻게 덮어쓰여도 대응하고 싶을 때는, 파일의 변경 자체를 감지하는 `FileChanged`
이벤트를 사용하도록 공식에서 안내하고 있습니다. 본 기사에서는 다루지 않습니다.

## hooks가 필요 없는 경우와 금지에 사용할 때 주의할 점

### 알림만 목적일 때

Claude의 작업 완료 신호만 받는 것이라면, hooks는 불필요합니다. Ghostty・Kitty・iTerm2에서는 기본적으로 데스크톱 알림이 도착하며, 다른 터미널에서도 `~/.claude/settings.json`에 `preferredNotifChannel`을 `terminal_bell`로 설정하면 벨이 울립니다. 알림 소리나 명령어를 직접 정하고 싶을 때 hooks를 사용합니다.

### '만지게 하지 않기' 기능을 만들 때

공식 문서는 `PreToolUse` hook으로 조작을 차단할 수 있다고 설명합니다. 이 차단은 `--dangerously-skip-permissions`로 실행하더라도 유효합니다.

다만, 허점(抜け道)을 의식해야 합니다.

- **Bash는 별도 취급**: `Edit|Write`를 대상으로 하는 hook은 Bash에서의 덮어쓰기를 감지하지 못합니다. 모든 변경을 보고 싶다면, `Bash`도 대상으로 추가하는 방법이 공식적으로 소개되어 있습니다. - : hook에는 `if`로 필터링할 수 있으며, 베스트 에포트(best effort) `if`로 '이 명령어일 때만 작동'이라는 조건을 붙일 수 있습니다. 다만, 명령어 내용을 분석할 수 없는 경우에는 조건과 관계없이 hook이 작동합니다. 확실하게 허용/거부하고 싶을 때는 권한 설정(permissions)을 사용하도록 공식에서 안내하고 있습니다.

본 기사에서는 금지 기능을 만드는 방법은 다루지 않습니다.

## 설정은 어디에 적나요?

hooks를 어디에 작성하느냐에 따라 적용 범위가 달라집니다.

| 위치 | 적용 범위 | 팀과 공유 가능 여부 |
|---|---|---|
| `~/.claude/settings.json` | 자신의 모든 프로젝트 | 불가능 (자신의 PC만) |
| `.claude/settings.json` | 해당 프로젝트만 | 가능 (리포지토리에 커밋 가능) |
| `.claude/settings.local.json` | 해당 프로젝트만 | 불가능 (Claude Code가 저장한 설정은 gitignore됨) |

자동 정렬처럼 팀원들이 통일하고 싶은 규칙은 프로젝트 설정에 둡니다. 자신의 취향만을 위한 설정은 사용자 설정, 일시적인 테스트는 로컬 설정입니다.

## hooks와 CLAUDE.md의 차이점

| hooks | CLAUDE.md |
|---|---|
| 실행하는 것 | 셸 명령어 | Claude에 대한 지시(문맥) |
| ... | 

## 요약

- hooks는 정해진 타이밍에, Claude의 판단을 거치지 않고 셸 명령어를 실행하는 메커니즘입니다.
- 설정 파일의 `hooks`에 추가하기만 하면 사용할 수 있습니다. `/hooks`에서 목록을 확인할 수 있습니다. - 자동 정렬과 같은 '매번 규칙적으로 수행하는 처리'에 능합니다. Bash를 경유한 덮어쓰기에는 효과가 없습니다.
- 알림은 표준 설정으로 충분할 때가 많습니다. 금지 기능에 사용할 때는 Bash를 경유한 허점에 주의해야 합니다.

이벤트 종류는 본 기사에서 소개된 것 외에도 수없이 많습니다. 자세한 내용은 참고 문헌의 리فرنس(reference)를 참조해 주십시오.

## 참고 문헌

- Automate actions with hooks — hooks의 기본, 설정 절차, 자동 정렬 예시
- Hooks reference — 모든 이벤트 사양, `if` 필드, `FileChanged` 상세 - How Claude remembers your project — '특정 타이밍에 실행하고 싶은 지시는 hook으로 작성한다'는 안내
- Configure your terminal for Claude Code — `preferredNotifChannel` 등 표준 알림 설정 - Configure permissions — 권한 설정(허용/거부 규칙) 공식 문서
- Prettier CLI — `--ignore-unknown` 설명

*본 기사 작성에는 AI 도구를 활용했습니다. 정보의 정확성에는 주의를 기울였으나, 최신 정보는 공식 문서를 함께 확인해 주십시오.*

### Discussion