목록 · 가이드
훅(Hooks)은 뭔가요?
훅(Hooks)은 Claude Code가 특정 시점 — 도구를 쓰기 전·후, 세션이 끝날 때 같은 — 에 자동으로 실행하는 셸 명령입니다. 스킬이 "이 상황이면 이렇게 하라"고 Claude에게 알려주는 지침이라면, 훅은 Claude가 어떻게 판단하든 상관없이 정해진 규칙을 무조건 실행시킵니다.
훅은 무엇인가요
훅은 설정 파일에 등록해 두는 셸 명령 하나입니다. "파일을 편집하기 직전", "세션이 시작될 때"처럼 정해진 이벤트가 일어나면 Claude Code가 그 명령을 대신 실행합니다. 명령의 실행 여부는 Claude의 판단을 거치지 않습니다 — 조건만 맞으면 매번 돕니다.
언제 씁니까
스킬로 "이렇게 해 주세요"라고 부탁해도 매번 지켜진다는 보장은 없습니다. 반드시 지켜져야 하는 규칙이라면 훅으로 만드는 편이 맞습니다.
- 위험한 명령을 막고 싶을 때
rm -rf나 프로덕션 데이터베이스 접근 같은 명령을 Claude가 실수로라도 실행하지 못하게 하고 싶을 때, 도구를 쓰기 직전에 걸리는 훅으로 차단합니다. 프롬프트로 "이런 명령은 쓰지 마세요"라고 적는 것보다 확실합니다. - 편집 후 자동으로 뭔가 실행하고 싶을 때파일을 고칠 때마다 매번 "포매터 돌려줘"라고 말하는 대신, 파일 편집이 끝난 직후 자동으로 포매터나 린터가 돌게 합니다.
- 작업이 끝났을 때 알림을 받고 싶을 때Claude가 응답을 마치면 데스크톱 알림을 보내거나 로그를 남기게 해서, 옆에서 계속 화면을 보고 있지 않아도 진행 상황을 압니다.
어떻게 설정하나요
1단계. 설정 파일 위치를 정합니다
이 프로젝트에서만 쓸 것이면 프로젝트 폴더 안에, 여러 프로젝트에 공통으로 쓸 것이면 내 계정 폴더에 둡니다.
.claude/settings.json~/.claude/settings.json프로젝트용은 저장소에 함께 커밋해서 팀과 공유할 수 있습니다. 다만 팀원 전체의 셸에서 실행되는 명령이니, 커밋하기 전에 내용을 한 번 더 확인하십시오.
2단계. 이벤트와 명령을 적습니다
도구를 쓰기 직전(PreToolUse)이나 직후(PostToolUse)처럼 이벤트 이름과, 그때 실행할 셸 명령을 짝지어 적습니다. 아래는 파일을 편집한 직후 자동으로 포매터를 돌리는 예시입니다.
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{ "type": "command", "command": "npx prettier --write ." }
]
}
]
}
}이벤트가 일어나면 도구 이름, 대상 파일 경로 같은 상세 정보가 명령 쪽으로 전달됩니다. 정확한 이벤트 이름과 전달 형식은 버전마다 조금씩 달라질 수 있어, 등록 전에 공식 문서에서 현재 지원 목록을 한 번 확인하는 편이 안전합니다.
3단계. 확인합니다
Claude Code 안에서 /hooks 명령으로 등록된 훅 목록을 볼 수 있습니다. 이벤트를 실제로 한 번 발생시켜 보고(예: 파일 하나를 고쳐 보고) 의도한 명령이 도는지 확인하십시오.
실행 권한을 그대로 물려받습니다
훅은 지금 로그인한 사용자의 셸 권한으로 그대로 실행됩니다. 출처를 모르는 훅 설정을 그대로 복사해 쓰지 마십시오. 팀 저장소에 커밋된 훅이라도, 내용을 읽지 않고 그대로 신뢰하지 않는 편이 안전합니다.
훅과 스킬은 뭐가 다른가요
| 구분 | 스킬 | 훅 |
|---|---|---|
| 형식 | 자연어 지침 (SKILL.md) | 셸 명령 |
| 실행 주체 | Claude가 상황을 보고 스스로 선택 | 이벤트가 맞으면 무조건 실행 |
| 우회 가능성 | 맥락에 안 맞다고 판단하면 안 쓸 수 있음 | 예외 없이 항상 실행됨 |
| 맞는 일 | 판단이 필요한 작업 방법 | 결과가 항상 같아야 하는 규칙 |