Claude Code Hooks란? 파일 저장 시 자동 실행 원리

Claude Code 입문

Claude Code Hooks는 "이런 일이 생기면 → 이 명령을 실행해"라는 규칙을 미리 정해두는 자동화 장치입니다. 이 글에서는 Hooks의 개념부터 설정 파일 구조, 파일 저장 시 자동 포맷이 동작하는 원리, 그리고 처음 설정할 때 알아둘 실전 팁까지 순서대로 정리합니다.

📌 3줄 요약

• Hook은 특정 이벤트가 발생하면 자동으로 명령을 실행하는 장치이며, Claude Code에서도 같은 원리로 동작한다.
• settings.json에 이벤트와 명령어를 등록해두면, 파일 저장 직후 포맷터·테스트가 자동 실행된다.
• 훅 명령이 실패하면 Claude Code가 피드백으로 받아 자동 수정을 시도하는 것이 일반 에디터와의 핵심 차이다.

📑 목차

• Hooks가 뭔지 한마디로 이해하기
• Hooks 설정 파일의 구조와 위치
• 파일 저장 시 자동 포맷이 동작하는 원리
• 처음 훅을 설정할 때 알아둘 실전 팁

Hooks가 뭔지 한마디로 이해하기

프로그래밍에서 훅(Hook)이란 특정 이벤트가 발생했을 때 자동으로 실행되는 명령을 뜻합니다. 낚시 바늘(hook)이 물고기를 자동으로 잡아채듯, 어떤 동작에 "걸어두는" 코드라고 생각하면 됩니다.

🔍  일상에서 비유하면, 현관문을 열 때 자동으로 켜지는 센서 조명과 같은 원리입니다. 사람이 매번 스위치를 누르지 않아도, 문이 열리는 이벤트에 조명이 반응하도록 미리 설정해둔 것입니다.

Claude Code에서도 이 개념을 그대로 씁니다. 예를 들어 "파일을 저장할 때마다 코드 정리를 자동으로 해줘"라고 설정해두면, 매번 직접 명령을 입력하지 않아도 알아서 실행됩니다.

코드를 작성하다 보면 저장, 검사, 정리 같은 반복 작업이 생기는데, 훅은 이런 반복을 대신 처리해주는 자동화 장치입니다. 개발자가 본래 해야 할 창의적인 작업에만 집중할 수 있도록 단순 반복을 줄여주는 셈입니다.

비슷한 예로 Git에도 커밋 전에 자동으로 코드 검사를 하는 Git Hooks가 있습니다. Claude Code Hooks는 이 개념을 Claude Code의 작업 흐름에 맞게 적용한 것입니다.

구분	Git Hooks	Claude Code Hooks
반응 대상	커밋, 푸시 등 Git 이벤트	파일 편집, 도구 사용 등 Claude Code 이벤트
활용 범위	Git 작업 흐름 내	Claude Code 작업 흐름 전체

처음 들으면 복잡해 보이지만, 핵심은 단순합니다. "이런 일이 생기면 → 이 명령을 실행해"라는 규칙을 미리 정해두는 것뿐입니다.

프로그래밍 경험이 없어도 이 if-then 구조만 이해하면 훅의 본질을 파악한 것입니다.

💬  제가 직접 써보니, 훅을 모를 때는 매번 수동으로 포맷 명령을 쳤습니다. 훅을 설정한 뒤로는 그 반복 작업이 완전히 사라져서, 왜 진작 안 썼나 싶었습니다.

특히 하루에 여러 파일을 수정하는 날이면, 훅 하나로 아끼는 시간이 꽤 체감됩니다.

Hooks 설정 파일의 구조와 위치

Claude Code의 훅 설정은 settings.json 파일 안에 작성합니다. 이 파일은 프로젝트 루트의 .claude/ 폴더 안에 위치합니다.

🔍  프로젝트 루트란 여러분이 작업 중인 프로젝트의 최상위 폴더를 말합니다. 만약 my-project라는 폴더에서 작업한다면, my-project/.claude/settings.json 경로에 해당 파일이 있습니다.

이 파일이 없다면 .claude 폴더를 만들고 settings.json을 새로 생성하면 됩니다.

설정 파일을 열면 "hooks"라는 항목이 있고, 그 안에 이벤트 이름과 실행할 명령을 적는 구조입니다. JSON이라는 형식을 쓰는데, 중괄호 {}와 쌍따옴표 ""로 이루어진 텍스트 파일이라고 보면 됩니다.

🔍  JSON은 사람이 읽을 수 있으면서도 컴퓨터가 정확히 해석할 수 있는 데이터 표기법입니다. 처음 보면 괄호가 많아서 어려워 보이지만, 구조 자체는 "이름: 값"의 반복이라 금방 익숙해집니다.

기본 구조는 이렇게 생겼습니다. 이벤트 종류를 지정하고, 그 이벤트가 발생하면 실행할 셸(shell) 명령어를 적어둡니다.

🔍  셸 명령어란 터미널(명령 프롬프트)에서 직접 입력하는 명령어를 의미합니다. 평소 터미널에서 실행하던 명령어를 그대로 적으면 되기 때문에, 새로운 문법을 배울 필요가 없습니다.

 

Claude Code에서 지원하는 주요 이벤트는 몇 가지로 나뉩니다. PostToolUse는 도구 사용 직후, PreToolUse는 도구 사용 직전에 실행됩니다.

이 외에도 Notification 이벤트는 Claude Code가 알림을 보낼 때 반응하고, Stop 이벤트는 Claude Code가 응답을 마칠 때 실행됩니다. 어떤 시점에 자동화를 걸고 싶은지에 따라 적절한 이벤트를 골라 사용하면 됩니다.

파일 저장 시 자동 포맷을 걸고 싶다면, PostToolUse 이벤트에서 Write나 Edit 도구를 감지하도록 설정합니다. 도구 이름을 "matcher" 필드에 적어서, 특정 도구가 쓰일 때만 훅이 작동하게 필터링하는 방식입니다.

⚠️  matcher를 지정하지 않으면 모든 도구 사용에 훅이 반응하기 때문에, 원하는 도구만 정확히 지정하는 것이 중요합니다.

💬  제가 처음 설정할 때 JSON 형식에서 쉼표 하나를 빠뜨려서 오류가 났습니다. settings.json을 수정할 때는 VS Code 같은 편집기를 사용하면 JSON 문법 오류를 자동으로 표시해주기 때문에 실수를 줄일 수 있습니다.

💡  JSON 문법 검사기를 한 번 돌려보는 것도 좋은 습관입니다.

 

파일 저장 시 자동 포맷이 동작하는 원리

실제 동작 흐름을 순서대로 따라가 보겠습니다. Claude Code가 Edit 도구로 파일을 수정하면, 시스템이 PostToolUse 이벤트를 감지합니다.

이 감지는 Claude Code 내부에서 자동으로 이루어지기 때문에, 사용자가 별도로 트리거를 누를 필요가 없습니다. 파일이 수정되는 순간 즉시 이벤트가 발생합니다.

이벤트가 감지되면, 미리 등록해둔 명령어가 자동으로 실행됩니다. 예를 들어 prettier --write 같은 코드 포맷터(formatter)를 등록해두면, 저장 직후 코드 스타일이 자동 정리됩니다.

전체 흐름을 정리하면 아래와 같습니다.

1

Claude Code가 파일 수정

2

PostToolUse 이벤트 발생

3

matcher가 Edit 도구인지 확인

4

등록된 명령어 실행

🔍  포맷터란 코드의 들여쓰기, 줄바꿈, 따옴표 스타일 등을 일관되게 맞춰주는 도구입니다. 사람이 일일이 정렬하지 않아도, 규칙에 맞게 코드를 깔끔하게 다듬어줍니다.

팀 프로젝트에서 여러 사람이 각자 다른 스타일로 코드를 작성하면 읽기 어려워지는데, 포맷터가 이런 문제를 자동으로 해결해줍니다. 대표적인 포맷터로는 JavaScript의 Prettier, Python의 Black 등이 있습니다.

 

테스트 자동 실행도 같은 원리입니다. 포맷터 대신 pytest나 npm test 같은 테스트 명령어를 등록해두면, 파일이 수정될 때마다 테스트가 돌아갑니다.

이렇게 하면 코드를 고친 직후 바로 문제가 있는지 확인할 수 있어서, 버그를 초기에 잡을 수 있습니다. 나중에 한꺼번에 테스트를 돌리는 것보다, 수정할 때마다 바로 확인하는 편이 디버깅 시간을 크게 줄여줍니다.

⚠️  훅 명령어가 실패하면(종료 코드가 0이 아니면) Claude Code가 해당 결과를 피드백으로 받습니다. 즉 테스트가 깨지면 Claude Code가 알아서 수정을 시도할 수 있다는 뜻입니다.

🔍  종료 코드란 프로그램이 끝날 때 반환하는 숫자인데, 0은 성공, 그 외는 실패를 의미합니다.

이 부분이 단순한 자동 포맷과 다른 점입니다. 일반 에디터의 저장 시 포맷 기능은 포맷만 하고 끝나지만, Claude Code 훅은 실패 시 AI가 직접 대응할 수 있습니다.

예를 들어 테스트가 실패하면 Claude Code가 실패 원인을 분석하고, 코드를 수정한 뒤 다시 테스트를 실행하는 자동 복구 루프가 만들어집니다. 이것이 Claude Code Hooks만의 가장 강력한 장점입니다.

💬  제가 직접 써보니, 테스트 훅을 걸어두면 코드를 고칠 때마다 바로 결과가 나와서 편리합니다. 다만 테스트가 무거우면 매번 느려지니, 가벼운 단위 테스트만 거는 것이 실용적이었습니다.

💡  전체 테스트는 커밋 전에 한 번만 돌리고, 훅에는 변경된 파일과 관련된 빠른 테스트만 등록하는 것을 추천합니다.

처음 훅을 설정할 때 알아둘 실전 팁

가장 먼저 추천하는 훅은 코드 포맷터 자동 실행입니다. 설정이 간단하고, 효과가 즉시 눈에 보이기 때문입니다.

코드를 저장할 때마다 들여쓰기와 줄바꿈이 자동으로 정리되는 것을 보면, 훅이 제대로 작동하는지 바로 확인할 수 있습니다. 처음부터 복잡한 훅을 설정하기보다, 이렇게 결과가 눈에 보이는 간단한 훅부터 시작하는 것이 학습에도 효과적입니다.

⚠️  settings.json에 훅을 추가한 뒤에는 Claude Code를 재시작해야 적용됩니다. 설정을 바꿨는데 동작하지 않으면, 재시작을 먼저 시도해 보십시오.

터미널에서 Claude Code를 종료한 뒤 다시 실행하면 됩니다. 설정 파일은 Claude Code가 시작할 때 한 번 읽기 때문에, 중간에 바꾼 내용은 재시작 전까지 반영되지 않습니다.

 

훅 명령어는 프로젝트 루트 디렉토리를 기준으로 실행됩니다. 경로를 적을 때 상대 경로를 쓰면 프로젝트 루트부터 시작한다는 점을 기억하십시오. 예를 들어 "scripts/format.sh"라고 적으면, 프로젝트 최상위 폴더의 scripts 폴더 안에 있는 format.sh를 실행합니다.

💡  절대 경로를 쓸 수도 있지만, 프로젝트를 다른 컴퓨터로 옮길 때 깨질 수 있으므로 상대 경로를 쓰는 것이 안전합니다.

여러 명령을 순서대로 실행하고 싶다면 &&로 연결하면 됩니다. 예를 들어 "prettier --write && pytest" 처럼 적으면 포맷을 먼저 하고, 성공하면 테스트를 실행합니다.

🔍  &&는 앞의 명령이 성공했을 때만 뒤의 명령을 실행한다는 뜻입니다. 만약 포맷에서 오류가 나면 테스트는 실행되지 않으므로, 불필요한 테스트 실행을 방지할 수 있습니다.

⚠️  한 가지 흔한 실수가 있습니다. matcher 필드를 빼먹으면 모든 도구 사용에 훅이 걸립니다. 파일 수정과 관련 없는 Read 도구에도 반응하게 되니, 반드시 "Edit", "Write" 등 원하는 도구를 지정해야 합니다.

불필요한 실행을 막아야 작업 속도가 느려지지 않습니다. 예를 들어 Claude Code가 파일을 읽기만 할 때도 포맷터가 돌아가면, 아무 변경도 없는데 시간만 낭비하게 됩니다.

 

💬  제가 직접 써보니, 처음에는 포맷터 하나만 걸어보는 것이 좋았습니다. 한꺼번에 여러 훅을 설정하면 어디서 문제가 생겼는지 파악하기 어렵고, 하나씩 추가하면서 동작을 확인하는 방식이 훨씬 안정적이었습니다.

훅이 정상 작동하는 것을 확인한 뒤 테스트 자동 실행, 린트 검사 등을 하나씩 추가해 나가면, 점점 강력한 자동화 환경을 구축할 수 있습니다.

✍️ 마치며

Claude Code Hooks는 "이벤트 → 자동 명령 실행"이라는 단순한 구조 위에 만들어진 자동화 도구입니다. settings.json에 이벤트와 명령어를 적어두기만 하면, 파일 저장 시 포맷 정리부터 테스트 자동 실행까지 반복 작업을 줄일 수 있습니다. 특히 훅 명령이 실패하면 Claude Code가 직접 피드백을 받아 수정을 시도하는 자동 복구 루프는, 일반 에디터에서는 경험할 수 없는 Claude Code만의 강점입니다. 포맷터 하나부터 시작해서 점차 확장해 보세요.

#ClaudeCode #Hooks #자동포맷 #settingsjson #PostToolUse #코드자동화 #개발생산성