Hooks — 자동 검수

파일을 고칠 때마다 포맷터를 돌렸는지, 테스트를 통과했는지 매번 손으로 확인하고 있지 않나요?

정해 둔 검수가 저절로 울립니다

Skill로 절차를 정리해 두어도, 그 절차 끝에 항상 붙는 검사(포맷·테스트·오탈자)는 여전히 사람이 기억해서 실행해야 합니다. 파일을 여러 개 고치는 세션에서는 마지막에 검사를 깜빡하기 쉽고, 깜빡한 검사는 결과물에 그대로 남습니다.

Hooks는 PreToolUse(도구 실행 전)·PostToolUse(도구 실행 후)·SessionStart(세션 시작) 같은 정해진 시점에 지정한 명령을 자동으로 실행하는 장치입니다. .claude/settings.json에 등록해 두면 그 시점이 올 때마다 사람이 매번 확인 요청을 하지 않아도 등록해 둔 명령이 실행됩니다. 등록한 목록은 /hooks 명령으로 볼 수 있지만 이 명령은 읽기 전용 브라우징이고, 수정은 설정 파일을 직접 고치거나 Claude에게 요청해서 합니다.

개발 직군만 쓰는 기능은 아닙니다. 문서를 작성하는 직군이라면 파일을 저장할 때마다 포맷·오탈자 검사 스크립트가 자동 실행되게 걸어 둘 수 있고, 기획서를 다루는 직군이라면 필수 항목이 빠졌는지 확인하는 검사를 같은 방식으로 걸 수 있습니다. Hook을 검수가 아니라 실행 자체에 쓰는 방식은 안티패턴입니다. 커밋 직후 배포까지 자동으로 이어지는 Hook을 걸어 두면, 검수를 통과하지 못한 변경도 그대로 나갑니다. Hook은 확인 절차를 자동화하는 데 쓰고, 실행 여부의 최종 판단은 사람에게 남겨 둡니다.

아래 연습을 그대로 붙여넣어, 파일을 고칠 때마다 맞춤법 검사가 자동으로 돌게 hook을 걸어 보세요.

순서

자동화할 검사를 하나 고릅니다 — 포맷터·문서 검사처럼 되돌리기 쉬운 것부터 시작합니다.
.claude/settings.json에 Hook을 등록합니다.
실행 시점(이벤트)을 지정합니다 — 도구 실행 전(PreToolUse), 도구 실행 후(PostToolUse), 세션 시작 시(SessionStart) 등입니다.
파일을 하나 고쳐 등록한 검사가 자동으로 실행되는지 확인합니다.
/hooks 명령으로 등록된 Hook 목록을 확인합니다 — 읽기 전용 브라우징이며, 수정은 설정 파일에서 합니다.

연습

기본

지금 프로젝트에 파일을 고칠 때마다 자동으로 맞춤법 검사를 돌리는 hook을 걸어 줘. PostToolUse 이벤트로 등록하고, 어떤 파일이 바뀌면 무슨 명령이 실행되는 건지 나한테 설명해 줘.

내 일로

내가 파일을 고칠 때마다 항상 직접 확인하는 게 있어: [여기에 검사 내용]. 이걸 hook으로 자동화하려면 어떤 이벤트에 걸어야 할지 물어보고, 등록까지 해 줘.

hook을 건 뒤 파일을 실제로 하나 고쳐, 검사가 자동으로 실행되는지 확인해 보세요.

파일을 고친 직후 검사가 사람 개입 없이 자동으로 실행되면 통과입니다.

막히는 지점

Hook 스크립트에 실행 권한이 없거나 명령이 실패로 끝나면 command not found 또는 에러로 다음 작업 흐름이 막힙니다. 이때는 스크립트에 실행 권한을 주고 절대경로로 지정하며, 실패해도 안전한 가벼운 검수만 Hook에 올립니다. 배포·삭제처럼 되돌리기 어려운 작업을 Hook에 걸면 검토 없이 실행되어 되돌릴 수 없는 상태가 되고, Stop 이벤트를 반복 차단하는 Hook은 무한루프에 빠질 위험이 있어 Claude Code가 8회 연속 차단 시 강제로 진행시킵니다. 되돌리기 어려운 작업은 Hook에 걸지 않고, Stop Hook은 반복 여부를 스스로 확인해 멈추도록 만듭니다.