드디어 Claude Code 훅 설정 완료, Opus 5에 딱 맞춰서. 몇 달 동안 안 쓴 게 아깝네.

진작에 정리해서 올리려고 했던 내용임. Claude Code 쓰다가 하지 말라고 한 짓을 기어이 저지르는 꼴을 본 적 있을 텐데, 그럴 때 'hooks'가 해결책임. 설정하기 귀찮아서 몇 달 미뤘는데, 막상 해보니 설정 지옥 같은 거 없고 그냥 셸 스크립트 하나면 끝남.

간단히 말해서, Claude Code가 루프를 돌 때 특정 시점마다 이벤트를 쏘는데, 거기에 스크립트를 갖다 붙이는 방식임. 제일 중요한 건 PreToolUse인데, 이건 툴을 실행하기 직전에 가로채서 아예 막아버릴 수 있음. 그냥 하지 말라고 타이르는 수준이 아니라, 아예 차단함. 스크립트가 툴 이름이랑 실제 명령어를 JSON 형태로 stdin을 통해 받으니까, 그걸 보고 판단하면 됨.

이게 진짜 물건인 이유는 그냥 씹는 게 아니라서임. 거절 사유를 반환하면 그게 그대로 Claude의 컨텍스트로 들어가서, AI가 그걸 보고 알아서 수정함. 내 경우엔 pnpm 쓰는 프로젝트에서 npm 명령어를 쓰려고 하면 이렇게 뱉어냄:

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "this repo is managed by pnpm (found pnpm-lock.yaml), re-run with pnpm"
  }
}

그러면 내가 뭘 치기도 전에 알아서 pnpm으로 바꿔서 다시 실행함. JSON 파싱하기 귀찮으면 그냥 exit 2 때리고 stderr로 이유만 출력해도 똑같이 작동함.

내가 실제로 쓰는 것들:

• secrets: API 키나 토큰 패턴이 들어간 명령어 혹은 파일 쓰기 시도 전부 차단
• destructive: rm -rf /, 메인 브랜치 강제 푸시, DROP DATABASE 같은 뻔한 사고 방지
• package manager: 락파일 읽어서 엉뚱한 패키지 매니저 쓰면 컷
• typecheck gate: 이건 PreToolUse가 아니라 Stop 훅임. 에이전트가 작업 다 끝났다고 할 때 tsc 돌려서 에러 있으면 결과 제출 못 하게 막아버림

지금 당장 제일 추천하는 건 Stop 훅임. 특히 Opus 5 나오면서 더더욱. 모델이 승인받으러 오기 전까지 훨씬 긴 작업을 한 번에 처리하다 보니, 멈췄을 때 검토 안 된 작업물이 너무 많이 쌓여 있음. 일단 스스로 타입 체크 한 번 돌리게 하는 것만으로도 꽤 많은 실수를 잡아냄. 만들 때 주의할 점 하나: 무조건 차단만 하는 Stop 훅을 짜면 무한 루프 도니까, 첫 번째 시도 이후에는 그냥 통과시키게 만들어야 함.

settings.json 설정까지 포함해서 다 올려놨음. 사실 스크립트 짜는 것보다 이 설정 파일 만지는 게 더 귀찮음: https://techpotions.com/products/claude-code-hooks MIT 라이선스고 가입 같은 거 없음.

혹시 Stop 훅으로 더 기깔나게 쓰는 사람 있음? PreToolUse에 비해 활용도가 너무 낮은 것 같은데, 나도 아직 겉핥기 수준이라 궁금함.