[Claude Hooks] 저장 전 검사와 테스트 자동화 설정법

안녕하세요. 재아군의 관찰인생입니다.

오늘은 Claude Hooks을 현업 개발자 관점에서 정리해보겠습니다. 최근 AI 코딩 도구는 단순히 코드를 제안하는 수준을 넘어, 코드베이스를 읽고 작업을 나누고 테스트까지 돌리는 방향으로 빠르게 이동하고 있습니다.

Claude Code를 실무에 넣을 때 가장 먼저 부딪히는 질문은 “AI가 파일을 고치기 전에 무엇을 검사할 것인가?”입니다. Hooks는 이 질문에 대한 꽤 실용적인 답입니다.

Claude Hooks는 Claude Code의 특정 이벤트 전후에 명령을 실행해 권한, 품질, 테스트, 알림 흐름을 자동화하는 설정입니다.

---

1. Claude Hooks을 먼저 이해해야 하는 이유

AI 코딩 도구는 빠릅니다. 하지만 빠르다는 것은 잘못된 명령, 깨진 테스트, 의도하지 않은 파일 변경도 빠르게 만들 수 있다는 뜻입니다.

Hooks는 이 속도에 안전장치를 붙입니다. 파일 수정 전 확인, 수정 후 포맷 검사, 세션 종료 전 테스트 요구 같은 규칙을 자동으로 실행할 수 있습니다.

• 위험한 Bash 명령을 실행 전에 차단할 수 있습니다.
• 파일 수정 후 lint, typecheck, test 같은 검증을 자동 실행할 수 있습니다.
• 사용자 입력이 들어왔을 때 프로젝트 규칙을 추가 컨텍스트로 넣을 수 있습니다.
• AI가 너무 일찍 종료하려 할 때 추가 검증을 요구할 수 있습니다.

구분	기존 방식	Claude Hooks 적용 후
검사 방식	사람이 매번 “테스트 돌려줘”라고 요청	PostToolUse나 Stop 단계에서 자동 검사
보안	위험 명령을 사후에 발견	PreToolUse 단계에서 차단
팀 규칙	개인 프롬프트에 의존	프로젝트 설정 파일로 공유

---

2. 핵심 구조와 동작 원리

Hooks는 이벤트 이름과 matcher, 그리고 실행할 command의 조합으로 구성됩니다. 핵심은 모든 상황에 훅을 거는 것이 아니라, 위험도가 높은 지점에만 얇게 붙이는 것입니다.

레이어	역할	실무에서 확인할 것
Event	PreToolUse, PostToolUse, Stop 등 실행 시점	검사가 너무 자주 실행되지 않는지
Matcher	Bash, Edit, Write, Grep 같은 대상 도구	검사할 도구 범위가 명확한지
Command	실행할 스크립트 또는 검증 명령	실패 메시지가 Claude에게 도움이 되는지

이 구조를 이해하면 AI 도구를 “똑똑한 채팅창”으로만 쓰지 않고, 팀의 개발 프로세스 안에 넣을 수 있습니다. 중요한 것은 모델 성능보다 작업 단위, 권한, 검증 루프를 먼저 설계하는 것입니다.

Claude proposes tool call
  -> PreToolUse hook checks command
  -> Tool runs if allowed
  -> PostToolUse hook validates result
  -> Stop hook can require final checks

---

3. 실무 설정 예시

가장 단순한 시작은 프로젝트 `.claude/settings.json`에 Bash 명령 사전 검사를 추가하는 것입니다. 아래 예시는 위험한 삭제 명령을 별도 스크립트로 검사하는 형태입니다.

{ "hooks": { "PreToolUse": [{ "matcher": "Bash", "hooks": [{ "type": "command", "command": "node scripts/claude-guard.js" }] }] } }

검사 스크립트는 입력 JSON을 읽고 허용 여부를 판단하는 식으로 만들 수 있습니다. 팀 환경에서는 메시지를 짧고 명확하게 주는 것이 중요합니다.

// scripts/claude-guard.js
const command = input.tool_input?.command ?? '';
if (/rm\s+-rf|git\s+reset\s+--hard/.test(command)) {
  console.error('Dangerous command blocked. Ask for explicit approval.');
  process.exit(2);
}

작게 시작하는 적용 순서

1. PreToolUse에서 위험 명령만 먼저 막습니다.
2. PostToolUse에서 변경 파일 규모를 확인합니다.
3. Stop에서 테스트 미실행 상태를 감지합니다.
4. 검사 실패 메시지는 Claude가 다음 행동을 알 수 있게 작성합니다.
5. 프로젝트 공통 설정과 개인 로컬 설정을 분리합니다.

---

4. 팀 워크플로우에 넣는 방법

실무에서는 Hooks를 CI 대체제로 쓰기보다 로컬 작업 중간 점검 장치로 쓰는 편이 좋습니다. 최종 검증은 여전히 CI가 맡고, Hooks는 AI가 나쁜 방향으로 너무 멀리 가기 전에 브레이크를 거는 역할입니다.

예를 들어 TypeScript 프로젝트라면 Edit 이후 `npx tsc --noEmit`을 항상 돌리는 대신, Stop 단계에서 한 번 요구하는 방식이 비용 대비 효율적입니다.

상황	추천 역할	주의점
파일 쓰기 전	PreToolUse Write/Edit	금지 경로와 대용량 변경 차단
명령 실행 전	PreToolUse Bash	삭제, reset, secret 출력 명령 차단
작업 종료 전	Stop	테스트 또는 타입체크 실행 여부 확인

• 훅은 적을수록 유지보수하기 쉽습니다.
• 명령 실패가 Claude에게 복구 가능한 정보로 전달되어야 합니다.
• 로컬 개발 속도를 심하게 늦추는 검사는 CI로 보냅니다.
• 팀 공통 정책과 개인 편의 훅을 분리합니다.

---

5. 경쟁 도구와 비교해서 보는 포인트

Claude Hooks는 Claude Code 내부 이벤트에 붙는다는 점에서 Git hooks나 CI와 다릅니다. 세 도구는 경쟁 관계가 아니라 서로 다른 시점의 안전망입니다.

도구	강점	아쉬운 점	추천 사용처
Claude Hooks	AI 도구 사용 순간에 즉시 개입	Claude Code 밖에서는 동작하지 않음	AI 작업 중 위험 명령 차단
Git Hooks	커밋, 푸시 시점에 표준 검사 가능	AI 대화 맥락은 모름	커밋 전 포맷과 린트
CI	가장 신뢰할 수 있는 최종 검증	피드백이 늦고 비용이 큼	PR 병합 전 테스트와 배포 검증

비교의 핵심은 “어떤 도구가 최고인가”가 아니라 “어떤 작업을 맡길 때 실패 비용이 낮은가”입니다. 같은 기능 구현이라도 로컬 탐색, 클라우드 병렬 작업, GitHub 중심 PR 자동화는 운영 방식이 꽤 다릅니다.

---

6. 도입 전 체크리스트와 흔한 실수

Hooks를 처음 만들 때 모든 검사를 다 넣고 싶어집니다. 하지만 훅이 너무 무거우면 개발자는 우회하고 싶어지고, AI도 반복 실패에 갇힐 수 있습니다.

체크 항목	좋은 기준	실패 신호
성능	수 초 안에 끝나는 검사 중심	매 도구 호출마다 전체 테스트 실행
정확도	명확한 차단 조건 사용	모호한 정규식으로 정상 명령까지 차단
운영	실패 메시지에 해결 방향 포함	에러 코드만 반환

자주 생기는 실수

• PostToolUse마다 전체 테스트를 실행하는 실수
• 로컬 전용 경로를 프로젝트 설정에 하드코딩하는 실수
• 훅 실패 메시지를 사람만 이해하게 작성하는 실수
• CI가 해야 할 보안 검사를 Hooks에만 의존하는 실수

---

7. 앞으로의 발전 방향

AI 코딩 도구가 강해질수록 Hooks 같은 실행 전후 제어 장치는 더 중요해집니다. 모델이 똑똑해져도 권한과 검증은 별도 레이어로 두는 것이 운영상 안전합니다.

앞으로는 Hooks가 MCP, 권한 정책, 팀 감사 로그와 결합해 “AI 개발 거버넌스”의 일부가 될 가능성이 큽니다.

• 프로젝트 정책 자동 주입
• 위험 명령 승인 워크플로우
• 테스트 미실행 작업 자동 차단
• AI 세션 로그와 코드 변경 감사

---

마무리

정리하면 Claude Hooks은 AI 코딩 도구를 실무 프로세스에 넣기 위한 중요한 퍼즐입니다. 처음부터 거창한 자동화를 목표로 하기보다, 반복되는 작은 작업 하나를 안정적으로 맡기는 쪽이 성공 확률이 높습니다.

Hooks는 화려한 기능은 아니지만, AI 코딩을 팀에서 오래 쓰게 만드는 기반입니다. 작은 guard 하나만 잘 만들어도 실수 비용이 꽤 줄어듭니다.

이 글이 도움이 되셨다면 댓글로 현재 사용 중인 AI 코딩 도구와 가장 자동화하고 싶은 작업을 남겨주세요. 다음 글에서 더 실전적인 예제로 이어가겠습니다.