클로드 코드가 파일을 수정할 때마다 직접 prettier를 돌리고, 타입을 확인하고, 테스트를 돌려야 한다면 번거롭습니다. 훅(hook)은 이런 반복을 없애 줍니다. '클로드가 파일을 수정하면 prettier 자동 실행', '세션이 끝나면 console.log 검사'처럼 특정 이벤트에 자동으로 실행될 명령을 미리 등록해 두는 방식입니다.
훅의 세 가지 종류
| 훅 이름 | 발동 시점 | 대표 활용 |
|---|---|---|
| PreToolUse | 클로드가 도구를 실행하기 직전 | 위험한 명령 차단, 파라미터 검증 |
| PostToolUse | 클로드가 도구를 실행한 직후 | 파일 수정 후 자동 포맷, 타입 체크 |
| Stop | 클로드 코드 세션이 종료될 때 | 최종 lint 검사, console.log 감사 |
settings.json으로 훅 설정하기
훅은 .claude/settings.json(프로젝트 전용) 또는 ~/.claude/settings.json(모든 프로젝트)의 hooks 항목에 등록합니다. 아래는 Prettier 자동 포맷과 세션 종료 시 타입 체크를 함께 설정하는 예시입니다.
.claude/settings.json — 실용 훅 설정 예시
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{
"type": "command",
"command": "npx prettier --write . --ignore-unknown 2>/dev/null || true"
}
]
}
],
"Stop": [
{
"hooks": [
{
"type": "command",
"command": "npx tsc --noEmit 2>&1 | head -20 || true"
}
]
}
]
}
}자주 쓰는 훅 레시피
- 파일 수정 후 Prettier 자동 포맷: PostToolUse + matcher 'Write|Edit' + prettier --write
- TS 파일 수정 후 타입 체크: PostToolUse + matcher 'Write|Edit' + tsc --noEmit (오류 상위 10줄만 출력)
- 세션 종료 전 console.log 감지: Stop + grep -r 'console.log' src/ 로 경고 출력
- git push 전 경고 알림: PreToolUse + matcher 'Bash' + push 명령어 감지 후 확인 요청
TypeScript 파일 수정 후 타입 체크 훅
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{
"type": "command",
"command": "npx tsc --noEmit 2>&1 | head -10 || true"
}
]
}
]
}
}훅이 동작하는지 테스트하는 프롬프트
src/test-hook.ts 파일에 일부러 타입 오류가 있는 코드를 작성해 줘. 훅이 자동으로 타입 오류를 감지해서 출력하는지 확인해 보고 싶어.훅 명령 끝에 || true를 붙이면 훅이 실패해도 클로드의 작업이 멈추지 않습니다. 포매터나 체크 도구가 아직 설치되지 않은 환경에서도 오류 없이 넘어가게 해 주는 안전장치입니다. 처음 훅을 설정할 때는 반드시 || true를 붙여 두세요.
훅은 파일이 수정될 때마다 실행되므로, 전체 테스트 실행이나 전체 빌드처럼 무거운 명령을 PostToolUse에 넣으면 작업 속도가 크게 떨어집니다. 가벼운 포맷·타입 체크는 PostToolUse에, 무거운 테스트는 Stop 훅이나 수동 실행으로 남겨 두는 것이 균형 잡힌 설정입니다.
훅을 잘 설계한 프로젝트는 클로드 코드가 마치 IDE처럼 동작합니다. 코드를 저장하는 순간 자동으로 정렬되고, 타입 오류가 즉시 피드백되고, 세션을 닫을 때 품질 점검이 완료됩니다. 처음에는 Prettier 훅 하나부터 추가해 보고, 효과를 확인하며 점차 확장하는 것을 추천합니다.