Claude Code 훅으로 커밋 전 자동 점검을 걸었더니 되돌린 커밋이 사라졌다

지난달 나는 같은 실수를 세 번 반복했다. 디버깅용으로 넣은 console.log 한 줄을 그대로 커밋하고, PR 리뷰에서 지적받고, 다시 커밋해 되돌리는 흐름이었다. 한 번 정리하는 데 평균 12분이 들었다. 사소해 보이지만 하루에 20번 넘게 커밋하는 나에게는 매주 새어 나가는 시간이 만만치 않았다. 결국 나는 내 기억력을 믿는 대신, 커밋 직전에 자동으로 도는 점검 장치를 붙이기로 했다.

커밋하고 나서야 발견하는 실수들

문제는 실수의 종류가 늘 비슷하다는 데 있었다. 디버그 출력, 임시로 주석 처리해 둔 테스트, 설정 파일에 잠깐 넣어둔 실제 키 값. 이 세 가지가 내 커밋 사고의 90% 이상을 차지했다. 사람이 매번 눈으로 잡기에는 반복 빈도가 너무 높았고, 집중력이 떨어지는 늦은 오후에 특히 자주 놓쳤다. 실수를 줄이겠다는 다짐만으로는 3일을 넘기지 못했다. 며칠 지나면 다시 원래 습관으로 돌아왔고, 되돌린 커밋 기록만 조용히 쌓였다. 나중에 로그를 세어 보니 한 달에 되돌린 커밋이 스무 건에 가까웠고, 그중 열에 아홉은 위의 세 유형이었다.

훅이 정확히 무엇을 가로채는가

Claude Code의 훅은 특정 동작 직전이나 직후에 내가 지정한 명령을 끼워 넣는 장치다. 파일을 수정하기 전, 명령을 실행한 뒤처럼 정해진 시점마다 스크립트가 자동으로 돈다. 나는 이 중에서 변경을 확정하기 직전 단계에 점검 스크립트를 물렸다. 핵심은 사람이 기억해서 실행하는 게 아니라, 잊어버려도 시스템이 대신 걸러준다는 점이다. 의지가 아니라 구조로 막는 방식이라, 컨디션이 나쁜 날에도 똑같이 작동했다. 나는 이 점이 체크리스트나 알림보다 훨씬 든든하다고 느꼈다.

내가 실제로 건 세 가지 점검

첫째, 스테이징된 파일에서 console.log와 print( 같은 디버그 흔적을 정규식으로 훑어 하나라도 있으면 커밋을 멈추게 했다. 둘째, 임시로 꺼둔 test.skip과 .only가 남아 있으면 경고와 함께 중단시켰다. 셋째, 이름이 .env로 시작하는 파일이 스테이징에 올라오면 무조건 거부했다. 세 검사를 합쳐도 스크립트는 40줄을 넘지 않았고, 실행에 0.3초 남짓 걸렸다. 중요한 건 규칙 하나하나가 내가 실제로 저질렀던 사고에서 나왔다는 점이다. 남의 모범 사례를 베낀 게 아니라 내 되돌린 기록을 그대로 규칙으로 옮겼다.

3주 동안 바뀐 숫자

훅을 걸기 전 2주 동안 되돌린 커밋은 11건이었다. 건 뒤 3주 동안은 단 1건으로 줄었다. 그 1건마저 훅이 잡도록 설계하지 않은 오타여서, 내가 정의한 세 패턴에 한해서는 사고가 0으로 떨어졌다. 커밋당 0.3초의 지연은 손끝에 느껴지지도 않았고, 오히려 통과했다는 신호 자체가 심리적 안전판이 됐다. 되돌리는 데 쓰던 주당 두 시간 남짓이 그대로 남았고, 그 시간을 리뷰 코멘트에 답하는 데 돌릴 수 있었다.

훅을 걸 때 주의한 점

처음에는 검사를 지나치게 촘촘하게 짜서 정상 코드까지 막히는 오탐이 하루 5번씩 났다. 규칙을 넓게 잡을수록 신뢰가 떨어졌고, 나중에는 경고창을 습관적으로 무시하게 됐다. 그래서 확실히 사고인 패턴 세 개만 남기고 나머지는 과감히 뺐다. 훅은 완벽한 감시자가 아니라, 내가 자주 저지르는 실수 딱 그만큼만 대신 기억해 주는 장치로 두는 편이 오래갔다. 감시 범위를 좁힐수록 오히려 더 믿고 맡기게 됐다. 자동화는 많이 걸수록 좋은 게 아니라, 반복되는 실수 위에 정확히 겹칠 때만 힘을 냈다.