Claude Code 훅 3개로 만든 작업 알림과 업무일지, 한 달 37번 돌려 본 기록

먼저 결론

• 훅은 응답 완료·입력 대기·세션 종료 세 시점에 걸어 텔레그램으로 알림을 받습니다.
• 세션이 끝나면 그날 대화 기록을 모아 claude -p로 일지를 쓰고, 텔레그램 업무일지봇으로 보냅니다.
• 봇은 업무별로 나누고, 텔레그램에서 지시를 받는 봇만 PC별로 나눴습니다.
• 여러 세션이 한꺼번에 끝나면 같은 일지가 동시에 여러 번 만들어지는 문제가 남아 있습니다.

1. 훅이 실패해도 작업은 멈추지 않아야 했다

목표는 세 가지였습니다.

• 작업 알림: Claude가 응답을 마칠 때마다 마지막 답의 앞부분을 텔레그램으로 받는다.
• 업무일지: 하루 작업이 끝나면 그날 세션을 종합한 일지를 받는다.
• 양방향 지시: 텔레그램에서 지시하면 PC의 Claude Code가 실행하고 결과를 회신한다.

여기에 조건을 두 개 붙였습니다. 하나는 훅이 실패해도 Claude 작업은 멈추지 않아야 한다는 것입니다. 다른 하나는 집 PC와 회사 PC에 같은 설정을 그대로 복사해 쓸 수 있어야 한다는 것입니다.

이 글은 앞의 두 가지(알림, 일지)를 다룹니다. 양방향 지시는 9월 설치 기록 기준으로 봇 연결과 승인 절차가 남아 있습니다.

예약 실행 자체는 에이전트로 업무 효율 높이기 ③에서 다뤘습니다. 이 글은 시각이 아니라 작업이 끝나는 순간에 반응하는 훅 설계에 초점을 둡니다.

2. 훅은 그 시점의 세션 정보를 JSON으로 넘겨 준다

훅은 Claude Code가 특정 시점에 내 스크립트를 실행하게 하는 기능입니다. 설정 파일(~/.claude/settings.json)에 "이 시점에 이 명령을 실행하라"고 적어 둡니다.

Claude Code는 그 시점이 오면 명령을 실행합니다. 이때 세션 정보(세션 번호, 작업 폴더, 대화 기록 파일 위치)를 JSON으로 넘겨 줍니다.

스크립트는 두 개입니다. 알림 스크립트는 훅이 넘겨 준 대화 기록 파일 끝에서 마지막 답을 꺼내 보냅니다.

일지 스크립트는 오늘 수정된 대화 기록을 모두 모읍니다. 그중 요청·최종 답·수정한 파일만 뽑아 요약본을 만듭니다. 이를 claude -p(화면 없이 한 번 실행하는 방식)에 넘겨 개조식 일지를 받습니다.

일지는 PC 안 폴더에 파일로 저장하고 텔레그램으로도 보냅니다.

세션 종료 훅이 놓치는 날도 있습니다. 그래서 작업 스케줄러에 매일 22시 실행을 보조로 걸었습니다. 그 시각에 PC가 꺼져 있었으면 다음에 켜질 때 실행됩니다.

3. 받는 봇을 두 PC가 같이 쓰면 메시지를 서로 가져간다

봇은 처음부터 용도별로 나눴습니다.

업무별로 나눈 이유는 알림의 양입니다. 작업알림봇은 응답이 끝날 때마다 오니 하루에도 여러 번 쌓입니다.

일지가 같은 대화방에 섞이면 묻혀 버립니다. 알림을 꺼 두면 일지까지 못 봅니다. 대화방을 나누면 알림은 무음으로 두고 일지만 챙겨 볼 수 있습니다.

PC별로 나눈 것은 지시봇뿐입니다. 보내기만 하는 봇은 두 PC가 같은 토큰을 써도 문제가 없습니다.

지시를 받는 봇은 다릅니다. PC가 텔레그램 서버에 새 메시지를 계속 물어보는 방식이라, 두 PC가 같은 봇을 물으면 메시지를 서로 가져가 충돌합니다. 그래서 받는 봇만 PC마다 따로 둡니다.

대신 모든 메시지 앞에 [집/프로젝트명] 같은 접두어를 붙였습니다. 공유 봇에서도 어느 PC의 일인지 구분됩니다.

설정 파일은 둘로 나눴습니다. "봇 이름 → 토큰·대화방" 목록과 "어느 알림을 어느 봇으로" 경로표입니다. 봇을 하나 더 만들면 목록에 한 줄만 추가하면 됩니다.

4. 훅이 작업을 막지 않게 규칙부터 정했다

훅은 Claude Code가 실행하는 명령입니다. 잘못 만들면 Claude 작업을 멈추게 할 수 있어서 규칙을 먼저 정했습니다.

• 오류는 삼킨다. 설정 파일이 없거나 JSON이 깨져도 기록 파일에 한 줄 남기고 조용히 끝냅니다.
• 오래 걸리는 일은 떼어 낸다. 일지 작성은 몇 분이 걸리므로, 훅은 일지 스크립트를 별도 프로세스로 띄우고 바로 끝납니다.
• 스스로를 부르지 않는다. 일지 스크립트가 실행하는 claude -p도 세션이라 훅이 다시 걸립니다. 환경 변수 표시를 붙여, 그 안에서는 알림 스크립트가 아무것도 하지 않게 했습니다.
• 큰 기록은 끝만 읽는다. 대화 기록 파일은 수십 MB까지 커지므로, 마지막 답은 파일 끝 3MB만 읽어 찾습니다.
• 비밀값은 가린다. 보내기 전에 봇 토큰, API 키, password= 같은 패턴을 정규식으로 가립니다.
• 같은 날 일지는 고쳐 쓴다. 하루에 세션이 여러 번 끝나도 새 메시지를 보내지 않고, 처음 보낸 일지 메시지를 수정합니다. 30분 안에 다시 불리면 건너뜁니다.

5. 첫날 오류 세 개는 다시 나오지 않았다

설치한 9월 23일 기록에는 오류가 세 번 남았습니다. 설정 파일이 없다는 오류, 설정 파일에 "허용되지 않는 제어 문자"가 있다는 오류, 텔레그램이 돌려준 "chat not found"입니다.

저는 첫 번째를 설정 파일을 만들기 전에 훅이 먼저 불린 것으로 봤습니다. 두 번째는 토큰이나 대화방 번호를 붙여 넣을 때 줄바꿈 같은 보이지 않는 문자가 섞인 것으로 봤습니다. 세 번째는 대화방 번호가 틀렸거나, 봇에게 먼저 말을 걸지 않은 상태로 봤습니다.

원인을 하나씩 확인한 기록은 남아 있지 않습니다. 확인한 것은 결과뿐입니다.

같은 날 17시 18분부터 일지 작성 비용이 정상으로 기록됐습니다. 이후 한 달 동안 세 오류는 다시 나오지 않았습니다. 설정 파일 문제는 설치 첫날 한 번 겪으면 끝나는 종류였습니다.

6. 같은 일지가 1초 안에 네 번 만들어졌다

10월 26일 22시 53분, 1초 안에 일지 작성이 네 번 끝났습니다. 비용도 네 번(약 1.46달러) 나갔습니다. 9월 26일과 10월 27일에도 같은 일이 있었습니다(각 4번, 2번).

여러 세션이 한꺼번에 끝나면 세션마다 종료 훅이 불리고, 각각 일지 스크립트를 띄웁니다. 30분 중복 방지는 "일지를 다 만든 시각"을 보고 판단합니다.

저는 동시에 시작한 프로세스들이 모두 이 검사를 통과한다고 봤습니다. 시작하는 순간에는 아직 아무도 일지를 다 만들지 않은 상태이기 때문입니다.

기록 파일을 보니 맞았습니다. 22시 53분 11초에 일지 스크립트가 같은 초에 네 번 실행됐고, 38초 뒤 네 번의 작성이 끝났습니다.

반면 22시 54분 5초에 한 번 더 불린 것은 건너뛰었습니다. 앞의 일지가 이미 끝난 뒤였습니다. 코드에서도 완료 시각을 작성이 끝난 다음에 기록하고 있었습니다.

고칠 방법은 시작할 때 잠금 파일을 먼저 만드는 것입니다. 그러면 두 번째부터는 바로 끝납니다.

9월 26일의 네 번은 비용 없이 6~8초 만에 강제 종료 코드로 끝났습니다. 세션을 닫으면서 함께 꺼진 것으로 보이지만, 확인하지는 못했습니다.

7. 9월 30일 시간 초과는 인터넷 끊김과 같은 초에 났다

9월 28일 새벽과 9월 30일 저녁에 claude -p가 정해 둔 300초를 넘겨 끊겼습니다. 9월 30일에는 같은 시각에 텔레그램 전송도 "주소를 찾을 수 없음"으로 실패했습니다. 10월 16~17일에는 텔레그램 전송이 응답 시간 초과로 두 번 실패했습니다.

저는 9월 30일은 PC의 인터넷 연결이 끊겼던 것으로 봤습니다. 같은 시각 텔레그램 주소 조회까지 실패했기 때문입니다. claude -p도 인터넷이 있어야 일하니, 시간 초과도 같은 원인으로 설명됩니다.

9월 30일은 두 오류가 같은 초에 남아 가설과 맞습니다. 9월 28일 새벽은 네트워크 오류 기록이 함께 없어 원인을 확인하지 못했습니다.

AI 작성이 실패하면 요약본 원문을 대신 보내도록 만들어 뒀습니다. 하지만 9월 30일처럼 인터넷이 끊기면 그것도 보내지 못합니다.

요약본이 앞서 보낸 것과 같으면 텔레그램이 "내용이 같아 수정하지 않음" 오류를 돌려주기도 합니다. 해가 없는 오류지만 기록에는 남습니다.

8. 1번 평균 비용은 설계 때 잡은 0.15달러보다 높았다

9월 23일부터 10월 27일까지 집 PC 기록입니다.

세션 종료 훅이 일지 스크립트를 띄운 것은 52번입니다. 22시 예약 실행까지 합쳐 AI 작성이 끝까지 된 것은 37번입니다. 나머지는 중복 방지로 건너뛰었거나 앞의 실패로 끝났습니다.

AI 작성 비용은 모두 8.76달러였습니다. 1번에 평균 0.24달러(최소 0.10, 최대 0.37)로, 설계할 때 잡은 0.15달러보다 높았습니다.

일지 파일은 17일치가 쌓였습니다. 그중 22시 예약 실행으로 만들어진 것이 16번입니다.

회사 PC는 설치 안내 문서까지 만들었습니다. 다만 이 글을 쓰는 시점에 회사 PC에서 돌고 있는지는 확인하지 못했습니다.

코드는 그대로 두었고, 잠금 파일은 아직이다

설치 뒤 코드는 고치지 않았습니다. 처음 정한 규칙(오류 삼키기, 떼어 내기, 재귀 막기) 덕분에 위의 실패는 모두 기록 파일에 한 줄씩 남는 것으로 끝났습니다.

아직 못 한 것은 네 가지입니다.

• 동시 실행을 막는 잠금 파일
• 텔레그램 지시봇 연결(설치는 했고 봇 연결과 승인 절차가 남음)
• 회사 PC 동작 확인
• 두 PC 일지를 하루 한 건으로 합치는 중계 서버

훅으로 만든 자동화는 한 번 설치하면 매일 신경 쓰지 않아도 돕니다. 그래서 실패가 눈에 잘 띄지 않았습니다. 저는 기록 파일을 다시 열어 보고서야 같은 일지가 동시에 여러 번 만들어지고 있었다는 걸 알았습니다.

자동화를 오래 쓰려면 실패가 남는 기록을 만들고, 그 기록을 주기적으로 읽어야 했습니다. 정해진 시각에 돌리는 예약 실행은 에이전트로 업무 효율 높이기 ③에 정리했습니다.