클로드 코드 훅, 규칙 건너뛰기를 코드로 막는다

카파시의 LLM 코딩 지적, CLAUDE.md 한 장으로 정리됐다 기사에서 다뤘듯, CLAUDE.md는 가정 금지·최소 코드·최소 수정·성공 기준 같은 원칙을 한 파일에 정리해 클로드 코드에 지시하는 방식이에요. 다만 이 파일은 어디까지나 클로드가 참고하는 지침이라, 상황에 따라 클로드가 규칙을 놓치거나 우회할 여지가 남아 있었어요. 이번 5강은 바로 그 빈틈을 훅으로 메우는 방법을 다뤘어요.

풀어서 설명하면, CLAUDE.md는 개발자가 클로드 코드에게 지켜야 할 규칙을 적어두는 파일인데, 클로드가 이 규칙을 실제로 따를지는 상황에 따라 달랐어요. 훅은 이 규칙 중 반드시 지켜야 하는 부분을 코드로 못박아, 클로드가 규칙을 어기려는 순간 자동으로 막거나 고치는 장치예요.

훅이란 무엇인가

훅은 클로드 코드가 도는 반복 실행 루프에서 정해진 지점마다 실행되는 결정론적 코드예요. 결정론적이라는 말은 같은 조건이면 언제나 같은 동작을 한다는 뜻이라, 사람이 지켜보지 않는 실행에서도 정해둔 규칙을 놓치지 않고 강제할 수 있어요.

자주 쓰는 7가지 이벤트

이벤트	발화 시점	주로 쓰는 용도
pre_tool_use	도구 호출 직전	위험한 명령 허용·거부·확인
post_tool_use	도구 호출 성공 직후	자동 포맷팅·린트
stop	클로드가 작업을 끝내려 할 때	조건 미충족 시 종료 거부
subagent_stop	서브에이전트 종료 시	stop과 같은 신호를 서브에이전트에 적용
pre_compact / post_compact	압축 전후	압축 과정 점검
instructions_loaded	CLAUDE.md 등 규칙 파일 로드 시	실제로 맥락에 들어간 내용 감사
session_start	세션 시작 시	환경 준비, 압축 후 맥락 재주입

압축 후 맥락을 다시 넣고 싶을 땐 post_compact가 아니라 compact 매처를 붙인 session_start를 써야 한다는 점을 영상은 따로 짚었어요.

결과를 가르는 exit code

코드	의미	비고
0	성공	표준출력이 JSON이면 파싱, 평문은 대부분 무시되지만 session_start·user_prompt_submit·user_prompt_expansion에서는 맥락에 추가
1	오류처럼 보이지만 차단 안 함	클로드는 명령을 그대로 실행
2	차단 오류	표준에러가 클로드에 맥락으로 전달되며 거의 모든 이벤트에서 차단 코드로 작동(worktree_create만 예외: 0이 아닌 모든 코드가 중단)

pre_tool_use 훅은 JSON을 반환해 permission decision 필드에 allow·deny·ask 중 하나를 담아요. defer라는 네 번째 값도 있지만 비대화형 -p 실행에서 호출 프로세스가 도구를 잠시 멈췄다 나중에 재개하는 특수한 경우에만 쓰여요.

실전 예시 두 가지

비밀값을 가리는 경우, pre_tool_use 훅에서 매처로 bash 도구를 지정하고 if절로 특정 명령만 좁힌 뒤 deny 대신 updated_input을 반환해요. 이렇게 하면 명령을 차단하지 않으면서도 비밀번호가 담긴 부분만 지운 채 실행을 이어갈 수 있어요. 다만 updated_input은 입력 객체 전체를 교체하기 때문에, 바꾸지 않는 필드도 그대로 다시 담아 반환해야 해요.

대화가 길어져 클로드가 압축을 수행하면 세부 정보가 많이 사라지는데, compact 매처를 붙인 session_start 훅이 압축 직후 바로 실행되며 작업 중이던 파일의 짧은 요약을 다시 맥락에 넣어줘요. 이 요약 덕분에 클로드는 압축 이전 상태에서 다시 시작하는 대신 하던 작업을 이어갈 수 있어요.

에디터의 시선

오토 모드가 매번 승인받지 않고 움직이게 만든 변화였다면, 훅은 그렇게 넓어진 자율성이 특정 규칙만큼은 절대 건드리지 못하게 막는 짝을 이루는 장치예요. 앤스로픽은 클로드 코드를 빠르게 움직이게 하면서도, 지켜야 할 선은 사람의 감시가 아니라 코드로 그어두는 방향으로 다듬고 있는 셈이에요.

CLAUDE.md 한 장으로 규칙을 정리하는 방식이 트렌드에 오른 지 얼마 안 돼, 이번엔 그 규칙을 지키면 좋은 수준에서 반드시 지켜야 하는 수준으로 끌어올리는 장치가 나왔어요. CLAUDE.md 규칙 파일만 갖춘 팀이라면 pre_tool_use 하나만 붙여도 위험한 명령이 실행되기 전에 걸러지는 걸 바로 체감할 수 있어요.

국내 개발팀이 클로드 코드를 도입할 때 자주 부딪히는 불만이 "가끔 규칙을 건너뛴다"는 건데, 이번 강좌는 그 답을 pre_tool_use와 stop 두 이벤트에서 시작하라고 짚어줘요. 30개에 달하는 이벤트를 한 번에 다 쓰려 하지 말고, 위험한 명령을 막는 pre_tool_use, 작업 완료 조건을 검사하는 stop, 압축 후 맥락을 복원하는 session_start 세 가지만 먼저 설정해도 실질적인 사고를 줄일 수 있어요.