훅

Claude Code에서 파일 수정이나 명령 실행 같은 이벤트가 일어날 때 자동으로 실행되는 셸 명령이다. 모델이 읽고 해석하는 지침이 아니라 Claude Code가 직접 돌리는 스크립트라서, 포맷팅·검사·위험한 명령 차단처럼 매번 반드시 해야 하는 일을 걸어 둘 때 쓴다.

부탁이 아니라 강제다

CLAUDE.md에 "수정 후 prettier 돌려줘"라고 적으면 모델이 잊을 수도 있다. 훅으로 걸어 두면 파일이 수정될 때마다 prettier가 무조건 돌아간다. 하네스 엔지니어링 관점에서 훅은 에이전트의 행동을 감싸는 가드레일이다.

settings.json에 이벤트별로 등록한다

모든 프로젝트에 쓸 훅은 ~/.claude/settings.json에, 팀과 공유할 훅은 프로젝트의 .claude/settings.json에 넣는다. 이벤트 이름, 어떤 도구에 반응할지 정하는 matcher(예: Edit|Write), 실행할 명령을 적는다. 등록된 훅은 Claude Code 안에서 /hooks로 확인할 수 있다.

종료 코드로 막거나 통과시킨다

훅은 어떤 도구가 어떤 입력으로 불렸는지를 JSON으로 표준입력에서 받는다. 스크립트가 0으로 끝나면 그대로 진행하고, 2로 끝나면 해당 동작을 막고 표준에러에 쓴 메시지를 Claude에게 돌려준다. 그래서 PreToolUse 훅에서 rm -rf나 DROP TABLE이 든 명령을 걸러 내면, Claude가 차단 이유를 보고 다른 방법을 찾는다.

여러 에이전트가 동시에 코드를 건드릴 때도 훅이 매번 린트와 타입 체크를 돌려 코드 스타일이 깨지지 않게 지켜 준다.

내 권한으로 그대로 실행된다

훅은 사용자 계정 권한으로 실행되므로 내용을 확인하지 않은 스크립트는 등록하지 않는다. 프로젝트 설정에 넣은 훅은 저장소를 받은 모든 사람에게 적용된다는 점도 기억한다. 도구를 부를 때마다 도는 훅이 느리면 작업 전체가 느려지니, 무거운 테스트는 PostToolUse보다 Stop에 거는 편이 낫다.

포맷은 자동으로, 위험한 명령은 차단으로

가장 흔한 건 파일을 고칠 때마다 포맷터와 린트를 돌리는 PostToolUse 훅이다. 여기에 위험한 명령을 막는 PreToolUse 훅과, 작업이 끝날 때 알림을 띄우거나 테스트를 돌리는 Stop 훅을 함께 거는 경우가 많다.