Claude Code가 답변을 끝마칠 때마다 작은 알림음이 났으면 했습니다. 그래서 훅을 하나 만들어 봤습니다.

답변을 끝내면 알림음으로 알려주는 훅을 만들어줘.

시험 삼아 간단히 입력했습니다. Claude Code는 응답을 마치는 시점인 Stop 이벤트에 Windows 알림음을 연결했습니다. 모든 프로젝트에 적용할지, 지금 열려 있는 프로젝트에만 쓸지도 먼저 물어보더군요. 설정을 마친 뒤에는 답변이 끝날 때마다 실제로 소리가 났고, 지금도 사용하고 있습니다.

공식 문서에도 “원하는 동작을 CLI에서 설명해 Claude에게 훅을 작성하게 할 수 있다”고 적혀 있습니다. 복잡한 규칙보다 먼저 정할 것은, 이 훅으로 무엇을 하고 싶은지입니다.

You can also ask Claude to write the hook for you by describing what you want in the CLI.

(원하는 것을 터미널에서 설명하면 Claude에게 훅을 작성하게 할 수도 있습니다.)

굳이 손으로 직접 쓰자면 이렇습니다

비교를 위해 방금 만든 알림음 훅을 설정 파일에 수동으로 적는다면 대략 이런 모습입니다. 운영체제마다 소리를 내는 명령이 달라 핵심 구조만 남겼습니다.

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          { "type": "command", "command": "..." }
        ]
      }
    ]
  }
}

직접 설정하려면 알아야 할 게 은근히 많습니다. 응답이 끝나는 순간을 Stop이라고 부른다는 사실, 명령을 어떤 괄호 안에 넣어야 하는지, 내 컴퓨터에서 소리를 내는 명령은 무엇인지 찾아봐야 합니다.

Claude Code에 말로 부탁하면 이런 기술적인 고민을 건너뛸 수 있습니다. 제 Windows 환경에서는 소리를 낼 명령까지 Claude Code가 골라줬습니다. 다른 운영체제에서는 명령이 달라질 수 있으므로, Claude Code가 무엇을 쓰려는지 보여달라고 한 뒤 확인하면 됩니다.

한 번에 성공하는 다섯 가지 지시 요령

처음 적었던 짧은 한 문장으로도 훅은 만들어집니다. 하지만 시행착오 없이 원하는 결과를 한 번에 얻고 싶다면 다음 다섯 가지를 포함하는 편이 좋습니다.

말할 내용알림음 훅에서는
언제Claude Code가 응답을 마칠 때
조건매번 실행(생략 가능)
무엇을알림음 재생
적용 범위현재 프로젝트에만
확인 방법설정할 파일과 명령을 보여주고 실제로 한 번 울려보기

자연스러운 한 문장으로 합치면 이렇게 됩니다.

Claude Code가 응답을 마칠 때마다 알림음을 울리는 훅을 만들어줘. 이 프로젝트에만 넣고, 설정을 쓰기 전에 네가 만들 파일과 실행할 명령을 먼저 보여줘. 만든 뒤에는 제대로 소리가 나는지 한 번 확인해줘.

어떤 설정 파일(.claude/settings.json)을 건드려야 하는지 몰라도 됩니다. 언제, 어디에, 무엇을 할지만 잘 짚어주면 나머지는 Claude Code가 채워 넣습니다.

“다 끝나면”보다 “응답을 마칠 때”가 낫습니다

명령을 내릴 때 흔히 “할 일을 다 끝내면 알려줘”라고 뭉뚱그려 말하기 쉽습니다. 그런데 여기서 주의할 점이 있습니다.

Claude Code의 Stop 이벤트는 내가 맡긴 큰 작업 전체가 끝났을 때 한 번만 실행되는 것이 아닙니다. Claude Code의 답변이 끝날 때마다 실행됩니다.

제가 만든 훅도 매 응답이 끝날 때마다 울립니다. 이 동작을 원한다면 “응답을 마칠 때마다”라고 명확히 적는 편이 좋습니다. 반대로 내 승인을 기다릴 때만 알림을 받고 싶다면 그 상황을 구체적으로 설명해야 합니다. 단어 하나 차이가 Claude Code가 설정하는 작동 방식을 바꿀 수 있습니다.

훅을 만든 다음 거쳐야 할 세 가지 확인

말로 쉽게 만들었다고 확인을 건너뛰면 안 됩니다. 훅은 내 컴퓨터 안에서 실제 명령을 실행하는 기능이기 때문입니다.

1. 명령 눈으로 확인하기

Claude Code가 설정을 저장하기 전에 보여달라고 한 명령을 한 번 읽어보세요. 알림음처럼 단순한 요청이라도 엉뚱한 프로그램을 실행하거나 예상하지 않은 파일을 보내는 명령이 섞이지 않았는지 확인하는 습관이 필요합니다.

2. /hooks로 등록 확인하기

터미널에 /hooks를 입력하면 현재 등록된 훅이 이벤트별로 나옵니다. 제대로 등록됐는지 확인하는 읽기 전용 화면입니다. 여기서 훅을 새로 만들거나 수정하지는 못합니다.

3. 실제로 작동하는지 시험하기

가벼운 질문을 던져 Claude Code가 짧게 답하게 한 뒤, 정말로 소리가 나는지 직접 들어보세요. 목록에 잘 떠 있어도 내 귀에 들리지 않을 수 있습니다. 실제로 사운드가 어떻게 들리지는 Claude Code가 확인을 못합니다.

고치고 지울 때도 프롬프트로 말씀 해주세요

쓰다가 소리를 바꾸고 싶다면 “지금 알림음 대신 다른 소리로 바꿔줘”라고 하면 됩니다. 다른 프로젝트에서도 이 훅을 쓰고 싶다면 “이 알림 훅을 사용자 설정으로 옮겨줘”라고 지시하면 됩니다.

지우고 싶을 때도 간단합니다.

방금 만든 알림음 훅만 제거해줘. 다른 훅은 건드리지 마.

조건이 복잡한 훅은 한 번에 모든 것을 지시하기보다, 하나씩 만들고 시험하며 살을 붙이는 편이 안전합니다.

첫 시작은 이 공식 하나면 됩니다.

[언제] [어떤 조건이면] [무엇을 해줘]. [어디에 적용하고] [어떻게 확인해줘].

참고한 문서