Claude Code Hooks 사용법: 코드 수정 후 자동 포맷과 테스트 돌리는 팁

TL;DR

오늘의 AI 활용 팁

Claude Code Hooks는 Claude Code가 파일을 고치거나, 권한을 요청하거나, 작업을 마쳤을 때 사용자가 정한 명령을 자동으로 실행하는 기능입니다.

Anthropic 공식 문서는 Hooks를 특정 시점에 실행되는 사용자 정의 명령, HTTP 엔드포인트, 프롬프트, 에이전트로 설명하며, 포맷팅, 알림, 보호 파일 차단, 설정 감사 같은 반복 작업에 쓸 수 있다고 안내합니다.

처음에는 자동 승인보다 파일 수정 후 포맷 실행, 민감 파일 보호, 작업 완료 알림처럼 되돌리기 쉬운 자동화부터 시작하는 것이 안전합니다.

핵심 3줄 요약

• 핵심 1
  Claude Code Hooks는 AI가 알아서 판단하길 기다리는 기능이 아니라, 정해진 이벤트에서 항상 실행되는 자동화 규칙입니다.
• 핵심 2
  가장 실용적인 시작점은 PostToolUse로 파일 수정 뒤 포맷터를 돌리고, PreToolUse로 .env 같은 민감 파일 수정을 막는 흐름입니다.
• 핵심 3
  Hooks는 강력하지만 잘못 쓰면 명령 실행과 권한 흐름이 자동화되므로, 작은 범위, 좁은 matcher, 명확한 로그부터 적용해야 합니다.

이 글에서 다룰 내용

Claude Code Hooks란 무엇인가

Claude Code Hooks는 Claude Code의 작업 흐름 중 특정 순간에 사용자가 정한 동작을 자동으로 실행하는 설정입니다. Anthropic 공식 문서는 Hooks가 Claude Code 생명주기의 특정 지점에서 실행되는 사용자 정의 셸 명령, HTTP 엔드포인트, LLM 프롬프트라고 설명합니다.

쉽게 말하면 Claude Code에게 "파일을 고친 뒤에는 항상 포맷터를 실행해", "특정 파일을 수정하려고 하면 막아", "권한 요청이 뜨면 알림을 보내" 같은 규칙을 붙이는 방식입니다.

한 문장 정의

Claude Code Hooks는 Claude Code의 파일 수정, 권한 요청, 작업 종료 같은 이벤트에 맞춰 사용자가 정한 자동화 규칙을 실행하는 기능입니다.

누가 쓰면 좋은가

이 팁은 Claude Code를 단순히 질문하는 도구가 아니라 실제 개발 흐름 안에서 반복적으로 쓰는 사람에게 잘 맞습니다.

1. Claude Code로 작은 코드 수정과 테스트를 자주 반복하는 개발자
2. 코드 포맷, 린트, 테스트 명령을 매번 잊지 않고 돌리고 싶은 사람
3. .env, package-lock.json, 설정 파일처럼 실수로 건드리면 곤란한 파일이 있는 팀
4. Claude Code가 권한 요청을 할 때 놓치지 않고 알림을 받고 싶은 사용자
5. 팀 프로젝트에서 Claude Code 사용 규칙을 설정 파일로 고정하고 싶은 운영자

감자나라ai님처럼 블로그 자동화, 발행 스크립트, 데이터 처리 파일을 함께 다루는 환경에서는 Hooks를 "AI 코딩 작업의 안전벨트"로 생각하면 쉽습니다. Claude Code가 빠르게 수정하더라도 포맷, 보호 파일, 알림 규칙은 사람이 매번 말하지 않아도 반복 적용할 수 있습니다.

핵심 인사이트

Hooks의 장점은 AI의 창의성을 높이는 것이 아니라, 반복 검증과 안전 규칙을 사람이 정한 방식으로 고정하는 데 있습니다.

언제 쓰면 좋은가

Claude Code Hooks는 아래 상황에서 특히 유용합니다.

• Claude Code가 파일을 수정한 뒤 포맷터를 자주 빼먹을 때
• 테스트나 타입 체크를 변경 후 자동으로 실행하고 싶을 때
• .env, 인증 키, 배포 설정 파일을 수정 대상에서 막고 싶을 때
• Claude Code가 권한 요청을 했는지 계속 터미널을 보고 있기 어려울 때
• 팀 규칙이나 프로젝트 컨벤션을 매번 프롬프트로 반복하기 싫을 때
• 설정 변경이나 자동화 실행 기록을 로그로 남기고 싶을 때

반대로 처음부터 배포, 파일 삭제, 외부 API 호출, 대량 리팩터링을 자동화하는 것은 위험합니다. Hooks는 "반복되는 작은 확인"부터 시작하고, 실제 서비스에 영향을 주는 동작은 사람이 승인하는 구조로 남기는 편이 좋습니다.

실전 팁

첫 Hooks는 생산성보다 안전성에 맞추세요. 포맷 실행, 보호 파일 차단, 알림처럼 결과를 바로 확인할 수 있는 작업이 가장 좋습니다.

Claude Code Hooks는 어떻게 작동하나

Anthropic 공식 레퍼런스는 Hooks가 이벤트, matcher, handler의 구조로 설정된다고 설명합니다.

첫째, 이벤트는 언제 실행할지 정합니다. 예를 들어 SessionStart는 세션이 시작될 때, PreToolUse는 도구 실행 전, PostToolUse는 도구 실행 후, Notification은 Claude Code가 알림을 보낼 때 실행됩니다.

둘째, matcher는 어떤 도구나 상황에만 반응할지 좁힙니다. 예를 들어 Edit 또는 Write 도구에만 반응하게 하면 파일 수정 뒤에만 포맷터를 실행할 수 있습니다.

셋째, handler는 실제로 실행할 명령입니다. 셸 명령, HTTP 요청, MCP 도구, 프롬프트 기반 평가, 에이전트 기반 평가 같은 방식이 가능합니다.

한 줄 정리

Hooks는 "언제", "어떤 경우에", "무엇을 실행할지"를 설정 파일에 적어 Claude Code의 반복 작업을 고정하는 구조입니다.

처음 만들기 좋은 Hooks 3가지

1. 파일 수정 후 자동 포맷

가장 쉬운 시작점은 Claude Code가 파일을 고친 뒤 Prettier, Black, Ruff, ESLint 같은 포맷터나 린터를 실행하는 것입니다. 공식 가이드는 PostToolUse 이벤트와 Edit 또는 Write matcher를 사용해 파일 편집 뒤 명령을 실행하는 예시를 제공합니다.

이 방식은 AI가 만든 코드의 모양을 프로젝트 규칙에 맞추는 데 좋습니다. 다만 전체 저장소 포맷보다 "수정된 파일만" 대상으로 잡는 편이 안전합니다.

2. 보호 파일 수정 차단

두 번째는 PreToolUse 이벤트로 민감 파일 수정을 막는 방식입니다. 공식 가이드는 .env, package-lock.json, .git 같은 보호 패턴을 검사하고, 해당 파일을 수정하려 하면 차단하는 예시를 제공합니다.

마케팅 자동화나 워드프레스 발행 스크립트를 다루는 폴더라면 .env, 인증 파일, 배포 설정, 원본 데이터 파일을 보호 목록에 넣는 식으로 응용할 수 있습니다.

3. 권한 요청 알림

세 번째는 Notification 이벤트로 Claude Code가 입력이나 권한 승인을 기다릴 때 알림을 받는 방식입니다. 공식 가이드는 macOS, Linux, Windows PowerShell 예시를 함께 제공합니다.

긴 작업을 맡겨 두고 다른 일을 할 때 유용합니다. 단, 알림은 작업을 대신 승인해 주는 기능이 아닙니다. Claude Code가 기다리고 있다는 사실만 알려주는 보조 장치로 이해해야 합니다.

따라 하는 순서

1단계: 자동화할 반복 작업을 하나만 고른다

처음부터 여러 Hooks를 한꺼번에 만들지 마세요. "파일 수정 후 포맷 실행", "민감 파일 보호", "작업 완료 알림" 중 하나만 고릅니다.

좋은 첫 목표는 아래처럼 작습니다.

• JavaScript 파일을 고친 뒤 Prettier 실행
• Python 파일을 고친 뒤 Ruff format 실행
• .env 파일 수정 차단
• Claude Code가 권한 요청을 기다릴 때 Windows 알림 띄우기

주의

처음 Hooks를 만들 때 배포, 삭제, 결제, 권한 변경, 외부 발송을 자동화하지 마세요. 자동화가 성공해도 되돌리기 어려운 작업은 사람이 승인해야 합니다.

2단계: 설정 파일 위치를 정한다

공식 레퍼런스에 따르면 Hooks는 여러 위치에 둘 수 있습니다. 개인 전체에 적용하려면 사용자 설정 파일, 특정 프로젝트에 공유하려면 프로젝트 설정 파일, 로컬에서만 쓰려면 로컬 설정 파일을 사용할 수 있습니다.

팀과 함께 쓸 규칙은 프로젝트 설정에 두고, 내 PC에서만 쓰는 알림이나 개인 편의 명령은 로컬 설정에 두는 편이 깔끔합니다.

3단계: 이벤트와 matcher를 좁게 잡는다

초보자가 가장 많이 하는 실수는 matcher를 너무 넓게 잡는 것입니다. 모든 도구에 반응하게 하면 예상하지 못한 명령이 자주 실행됩니다.

예를 들어 포맷터는 파일 수정 뒤에만 필요합니다. 이때는 PostToolUse 이벤트에서 Edit 또는 Write 도구에만 반응하도록 좁히는 편이 좋습니다.

핵심 인사이트

Hooks는 넓게 만들수록 편해 보이지만, 안전한 Hooks는 좁게 만들수록 오래 갑니다.

4단계: 먼저 로그만 남겨 테스트한다

처음에는 실제 포맷이나 차단보다 로그 기록으로 시작하는 것이 안전합니다. 예를 들어 "어떤 이벤트가 언제 실행되는지", "어떤 파일 경로가 들어오는지"를 로그로 남겨 흐름을 확인합니다.

이 과정을 거치면 Hooks가 내가 생각한 순간에만 실행되는지 확인할 수 있습니다. 예상보다 자주 실행된다면 matcher나 조건을 더 좁혀야 합니다.

5단계: 작은 자동 실행을 붙인다

로그가 정상이라면 포맷터, 린터, 알림처럼 작은 자동 실행을 붙입니다. 명령은 프로젝트에서 이미 쓰는 스크립트를 재사용하세요.

예를 들어 package.json에 format 명령이 있으면 Hooks 안에서 새 명령을 길게 만들기보다 기존 format 명령을 호출하는 편이 관리하기 쉽습니다.

6단계: 실패했을 때의 행동을 정한다

Hooks는 성공할 때보다 실패할 때 더 중요합니다. 포맷터가 실패하면 Claude Code에게 어떤 메시지를 보여줄지, 보호 파일 차단은 어떤 이유를 알려줄지, 로그 파일은 어디에 남길지 정해 두세요.

공식 문서는 Hooks가 출력과 종료 코드, JSON 응답을 통해 Claude Code의 다음 행동에 영향을 줄 수 있다고 설명합니다. 초보자는 복잡한 JSON 제어보다 명확한 오류 메시지와 수동 확인부터 시작하는 편이 안전합니다.

바로 쓰는 프롬프트 예시

포맷 Hooks 만들기

아래 프로젝트에서 Claude Code Hooks를 처음 설정하려고 해.

목표는 Claude Code가 파일을 수정한 뒤 프로젝트의 기존 포맷 명령을 실행하는 거야.

먼저 어떤 설정 파일에 넣을지, 어떤 이벤트와 matcher를 써야 하는지 계획을 보여줘.

바로 파일을 수정하지 말고, 위험한 점과 테스트 방법도 같이 정리해줘.

민감 파일 보호 Hooks 만들기

이 저장소에서 .env, 인증 파일, 배포 설정 파일은 Claude Code가 수정하지 못하게 막고 싶어.

PreToolUse Hooks로 보호할 수 있는 설계를 제안해줘.

보호 대상 패턴, 차단 메시지, 테스트 방법을 먼저 보여주고, 내가 승인하기 전에는 설정 파일을 바꾸지 마.

작업 완료 알림 만들기

Claude Code가 내 입력이나 권한 승인을 기다릴 때 Windows에서 알림을 받고 싶어.

Notification 이벤트로 만들 수 있는 가장 단순한 Hooks 설정을 제안해줘.

내 환경에서 실행 가능한 PowerShell 명령인지 먼저 설명하고, 실패했을 때 확인할 항목도 알려줘.

Hooks 점검 요청

아래 Claude Code Hooks 설정을 검토해줘.

1. 너무 넓은 matcher가 있는지

2. 자동 승인이나 위험한 명령이 있는지

3. 보호 파일이 빠져 있는지

4. 실패했을 때 사람이 확인할 수 있는 로그가 있는지

위 기준으로 문제점과 수정안을 나눠서 알려줘.

실전 팁

첫째, Hooks는 프롬프트가 아니라 규칙입니다. "가능하면 해줘"가 아니라 "이 이벤트가 발생하면 이 명령을 실행한다"에 가깝습니다. 그래서 애매한 자연어보다 좁은 이벤트와 명확한 명령이 중요합니다.

둘째, 팀 공유 규칙과 개인 편의 규칙을 분리하세요. 프로젝트 전체에 필요한 보호 파일 차단은 공유 설정에 둘 수 있지만, 개인 PC 알림이나 로컬 경로가 들어간 명령은 로컬 설정에 두는 편이 좋습니다.

셋째, 자동 포맷은 수정 파일 중심으로 시작하세요. 전체 저장소 포맷은 예상보다 많은 파일을 바꿀 수 있습니다. 처음에는 Claude Code가 실제로 수정한 파일만 대상으로 잡는 것이 안전합니다.

넷째, 자동 승인은 마지막에 검토하세요. 공식 가이드는 PermissionRequest Hooks로 특정 권한 요청을 승인하는 예시도 보여주지만, matcher를 넓게 잡으면 파일 쓰기나 셸 명령까지 과하게 허용할 수 있습니다. 초보자는 알림, 포맷, 차단부터 시작하세요.

다섯째, Hooks 자체도 코드 리뷰 대상입니다. 설정 파일과 스크립트는 프로젝트의 실행 규칙을 바꾸므로, 팀 저장소에 넣는다면 일반 코드처럼 리뷰해야 합니다.

주의할 점

첫째, Hooks는 Claude Code의 명령 실행 흐름과 연결됩니다. 잘못 만든 Hooks는 불필요한 명령을 반복 실행하거나, 너무 많은 파일을 수정하거나, 중요한 작업을 자동 승인할 수 있습니다.

둘째, 공식 문서는 Hooks가 결정적 제어를 제공한다고 설명하지만, 그만큼 설정 책임도 사용자에게 있습니다. AI가 알아서 안전하게 해줄 것이라고 기대하지 말고, matcher와 조건을 사람이 좁혀야 합니다.

셋째, 보안 파일을 보호한다고 해서 모든 위험이 사라지는 것은 아닙니다. 프롬프트 인젝션, 잘못된 명령, 외부 스크립트 실행, 넓은 권한은 여전히 문제가 될 수 있습니다.

넷째, 운영 프로젝트에서는 Hooks를 바로 적용하지 마세요. 복사본이나 작은 테스트 저장소에서 먼저 동작을 확인한 뒤 실제 저장소로 옮기는 편이 좋습니다.

주의

Hooks는 "반복 검증을 자동화하는 도구"이지 "검토 책임을 없애는 도구"가 아닙니다. 배포, 삭제, 외부 전송, 권한 변경은 사람이 마지막에 확인해야 합니다.

FAQ

Q1. Claude Code Hooks는 Skills와 같은 기능인가요?

다릅니다. Skills는 Claude Code가 특정 작업 지침과 절차를 참고하도록 만드는 확장 구조에 가깝고, Hooks는 특정 이벤트에서 명령이나 핸들러를 자동 실행하는 구조입니다. 반복 지침은 Skills, 반복 실행 규칙은 Hooks로 나눠 이해하면 쉽습니다.

Q2. Hooks를 쓰면 테스트가 자동으로 다 통과하나요?

아닙니다. Hooks는 테스트 명령을 실행하게 만들 수는 있지만, 테스트를 통과시키는 기능은 아닙니다. 실패 결과를 보고 Claude Code가 다시 수정할 수는 있어도, 최종 검증과 배포 판단은 사람이 확인해야 합니다.

Q3. 초보자는 어떤 Hooks부터 만들면 좋나요?

파일 수정 후 포맷 실행, 민감 파일 보호, 권한 요청 알림이 좋습니다. 이 세 가지는 효과가 바로 보이고, 배포나 삭제처럼 되돌리기 어려운 작업보다 위험이 낮습니다.

Q4. Windows에서도 Hooks를 쓸 수 있나요?

공식 가이드는 Notification 예시에서 Windows PowerShell 명령도 함께 보여줍니다. 다만 실제 명령은 사용자의 터미널, PowerShell 실행 정책, 설치된 도구에 따라 달라질 수 있으므로 작은 테스트부터 확인해야 합니다.

Q5. PermissionRequest Hooks로 자동 승인을 해도 되나요?

가능은 하지만 조심해야 합니다. 공식 가이드는 특정 도구에 한정해 승인하는 예시를 보여주며, matcher를 넓게 잡으면 파일 쓰기와 셸 명령까지 위험하게 허용될 수 있다고 설명합니다. 처음에는 자동 승인보다 알림과 차단부터 적용하세요.

Q6. 팀 저장소에 Hooks 설정을 커밋해도 되나요?

프로젝트 규칙으로 공유해야 하는 Hooks라면 가능하지만, 개인 경로, 개인 알림, 로컬 비밀 정보가 들어가면 안 됩니다. 팀원이 같은 환경에서 실행할 수 있는지, 보안상 문제가 없는지 리뷰한 뒤 공유해야 합니다.

출처

마무리

Claude Code Hooks는 코딩 에이전트를 더 빠르게 쓰기 위한 기능이기도 하지만, 더 중요한 역할은 반복 규칙을 고정하는 것입니다. 파일을 고친 뒤 포맷을 돌리고, 민감 파일을 막고, 권한 요청을 놓치지 않는 것만으로도 AI 코딩 작업의 품질이 꽤 안정됩니다.

오늘 바로 해볼 일은 하나입니다. 운영 저장소가 아니라 작은 테스트 폴더에서 "파일 수정 후 포맷 실행" Hooks 하나만 만들어 보세요. 그다음 로그, 실패 메시지, 변경 파일을 확인하고 나서 보호 파일 차단이나 알림으로 넓혀 가면 안전하게 익힐 수 있습니다.