Claude Code, Hook으로 스타일 강제

Claude Code에서 코드 스타일을 강제하기 위해 CLAUDE.md에 지시문을 넣는 방식은 모델이 기억할 때만 적용되며 매 세션마다 컨텍스트 비용을 소모하는 한계가 있다. 이에 따라 모델이 작업을 마칠 때마다 명령어를 실행하는 Stop Hook을 사용하는 방식이 대안으로 제시됐다.

Stop Hook의 작동 원리

Stop Hook은 Claude가 코드를 작성한 후 지정된 명령어를 실행하며, 해당 명령어가 exit status 2로 종료되면 stderr 내용을 모델에게 전달한다. 이를 통해 Claude는 자신의 린트 오류를 읽고 사용자가 diff를 보기 전에 스스로 수정할 수 있다. 단일 포매터 사용 시 prettier --write . || exit 2 한 줄로 설정이 완료된다.

stagelint를 활용한 파일 라우팅

다양한 파일 유형에 따라 다른 도구(eslint, tsc, ruff 등)를 적용해야 할 경우, 파일 글롭(glob)을 명령어에 매핑하는 stagelint를 활용할 수 있다. stagelint는 git pre-commit 실행 도구와 동일한 설정 파일(.stagelint.yml)을 공유하므로, 커밋 훅과 Claude Hook 모두를 하나의 설정으로 관리할 수 있다.

설정 예시 및 주의사항

.claude/settings.json의 Stop Hook에 stagelint --unstaged --quiet || exit 2를 등록하여 Claude가 방금 수정한 unstaged 변경 사항만 검사하도록 설정한다. --quiet 플래그는 토큰 절약을 위해 CLI 출력을 최소화한다. 또한 PostToolUse Hook을 통해 파일 작성 시마다 즉시 피드백을 주는 방식도 가능하지만, 프로젝트 전체 검사(tsc 등)의 경우 Stop Hook이 더 적합할 수 있다.