AI에게 일을 시켜 놓고 모니터 앞에서 기다리는 건 본말전도다. 끝났을 때, 내가 필요할 때, 고장 났을 때만 주머니 속 폰이 울리게 만들었다.
내 행동이 필요한 순간에만 울린다. 그 외엔 침묵이다.
시킨 작업의 응답이 완성됐다. 돌아와서 결과를 확인하면 된다. 완료 전용 효과음이 따로 있어 소리만 듣고도 구분된다.
AI가 권한 승인을 기다리며 멈춰 있다. 이걸 놓치면 "20분 일 시켰는데 19분을 내 대답만 기다리고 있었다"가 된다. 가장 아까운 낭비.
API 에러·인증 만료·정책 차단 등으로 작업이 비정상 중단됐다. 모르고 있으면 "다 됐겠지" 하고 돌아왔을 때 아무것도 안 돼 있다.
Claude Code에는 정해진 순간(응답 완료, 권한 질문, 실패, 세션 종료)에 외부 스크립트를 실행해 주는 hook 기능이 있다. 알림은 이 훅 4개가 1차로 만들고, 훅이 놓치는 빈틈은 별도의 감시 데몬이 메운다. 어느 경로든 공통 발송 함수 하나로 모인다.
응답이 정상 완료됨 → "끝났다" 알림
권한 승인 대기 등 → "네가 필요하다" 알림. 이 종류만 골라 받고 나머지 잡음은 버린다
API 5xx·rate limit·인증·네트워크 실패 → "고장 났다" 알림
세션 종료 → 알림 없음, 기록만 (3번 섹션 참조)
컴퓨터 앞에 있을 때
효과음 (완료음 / 호출음)
자리를 비웠을 때
폰·태블릿 푸시
훅과 별개로 OS 스케줄러가 30초마다 깨우는 독립 스크립트. 모든 세션의 대화 기록 파일에서 에러 표식이 붙은 줄을 증분 스캔해 분류(정책 차단, rate limit, 인증, 타임아웃 등)하고 같은 관문으로 보낸다. 훅은 Claude Code가 살아서 불러 줄 때만 작동한다. 응답 생성 자체가 차단되는 경우처럼 훅이 못 잡는 실패는 이 백스톱이 잡는다. 파일별로 어디까지 읽었는지 위치를 기억해 두기 때문에 매번 처음부터 다시 읽지 않고, 파일이 교체돼도 꼬이지 않는다.
훅은 빠르고 정확하지만 호출되는 순간이 정해져 있다. 실패의 일부는 그 순간 바깥에서 일어난다. 응답이 만들어지다 중간에 차단되거나, 훅 자체가 실행되지 못하거나. 알림 시스템이 잡지 못하는 실패 모드가 반드시 있다고 가정하고, 이벤트 방식(훅)과 폴링 방식(기록 파일 스캔)이라는 서로 다른 원리의 감지를 겹쳐 빈틈을 줄였다. 같은 사건을 둘 다 잡아도 관문의 중복 제거 덕에 한 번만 울린다.
처음엔 세션이 비정상 종료될 때의 알림도 만들었다. 지금은 꺼져 있고 기록만 남긴다. 이 결정에서 배운 게 제일 많았다.
세션 종료 이벤트가 주는 정보로는 내가 일부러 닫은 것(창 닫기, 정리, 강제 종료)과 진짜 사고(메모리 부족 등으로 죽음)를 구별할 수 없었다. 둘 다 같은 값으로 온다. 이대로 알림을 켜면 정상 종료 때마다 가짜 경보가 울린다.
"또 그 알림이네"가 몇 번 반복되면 진짜 경보까지 무시하게 된다. 늑대소년이다. 그래서 알림은 끄고 종료 사유 기록만 남겼다. 진짜 사고는 어차피 실패 훅과 감시 데몬이라는 더 정확한 2계층이 잡는다. 그 둘로도 못 잡는 경우, 그러니까 기록조차 안 남는 죽음은 여기선 못 잡는다고 명시하고 포기했다. 어설픈 감지를 하나 더 다는 것보다 낫다.
에러는 한 번에 수십 건씩 몰려온다. 그대로 흘려보내면 폰이 사이렌 소리로 도배되고, 결국 알림 자체를 꺼 버리게 된다. 그래서 발송 관문에 세 가지 장치를 달았다.
| 알림 종류 | 우선순위 | 재알림 간격 (쿨다운) | 비고 |
|---|---|---|---|
| 작업 완료 | 보통 | — | 완료음. 가장 흔하고 가장 평화로운 알림 |
| 입력 필요 | 보통 | — | 호출음. 놓치면 시간 낭비가 가장 큰 알림 |
| 정책 차단 | 높음 | 10분 | 사이렌. 작업 설계를 바꿔야 하는 신호 |
| 인증 만료 · 한도 소진 | 높음 | 30분 | 사이렌. 사람이 가서 조치해야 풀림 |
| 일시 에러 (5xx·rate limit 등) | 보통 | 5분 | 대개 저절로 회복되므로 우선순위 낮게 |
이 표의 원본은 발송 라이브러리 맨 위 주석에 있다. 문서 따로 코드 따로면 반드시 어긋나기 때문에, 정책표를 코드 바로 옆 한 곳에만 두고 다른 모든 문서에는 그 표를 보라고만 적는다.
모든 알림은 사건 고유 키와 함께 관문에 들어오고, 이미 보낸 키는 다시 울리지 않는다. 훅과 감시 데몬이 같은 에러를 동시에 잡아도 알림은 한 번이다. 키 장부는 여러 프로세스가 동시에 만져도 깨지지 않게 잠금으로 보호하고, 무한히 자라지 않게 오래된 줄부터 잘라낸다.
같은 종류의 알림은 간격 안에 다시 울리지 않는다. 대신 억제된 N건은 다음 알림 본문 앞에 "[직전 N건 억제됨]"으로 합산 표시된다. 조용하게 만드는 장치가 정보까지 조용히 증발시키면 안 되니까.
푸시 서비스 토큰은 코드, 로그, OS 등록 파일 어디에도 박지 않는다. 본인만 읽을 수 있게 권한을 잠근 별도 비밀 파일 한 곳에만 두고, 스크립트가 실행 시점에 읽는다. 비밀 파일이 없으면 푸시만 건너뛰고 컴퓨터 효과음은 그대로 동작한다. 일부가 빠져도 전체가 죽지는 않게 해 뒀다.
제일 무서운 고장은 알림 시스템이 죽어서 알림이 안 오는 것이다. 안 울리는 게 정상인 시스템이라 죽어도 겉보기가 똑같다. 그래서 감시 데몬 자신을 외부에서 감시한다.
30초마다 한 바퀴 돌고, 끝까지 성공했을 때만 신호를 보낸다.
healthchecks.io(무료) — "1분마다 신호가 와야 정상"이라고 등록해 둔다.
유예 시간이 지나도 신호가 없으면 그 서비스가 거꾸로 나에게 알린다.
신호를 사이클 시작이 아니라 끝, 그러니까 성공 시점에 보내는 게 요점이다. 시작에 보내면 신호를 보내자마자 죽는 데몬이 영원히 정상으로 보인다. heartbeat가 보고해야 하는 건 살아 있음이 아니라 일을 끝까지 해냈음이다.
도구나 스크립트보다는 판단 기준 쪽이 옮겨 심을 만하다.
끝났다, 네가 필요하다, 고장 났다. 이 셋 밖의 알림은 전부 잡음이다. 알림 설계는 더하는 일이 아니라 빼는 일이었다.
정상 종료와 사고를 구별 못 하는 신호로 경보를 만들면 늑대소년이 된다. 가짜 경보를 섞느니 그 알림을 기록 전용으로 내리고, 못 잡는 영역은 못 잡는다고 적어 두는 편이 낫다.
에러는 몰려온다. 폭주 방지 없는 알림 시스템은 결국 사람 손에 꺼진다. 억제한 건수는 다음 알림에 합산 표시해서 조용함이 정보 손실이 되지 않게 했다.
이벤트 훅이 못 잡는 실패 모드는 반드시 있다. 폴링 방식의 독립 백스톱 하나가 그 빈틈을 메우고, 중복은 관문에서 걸러진다.
안 울리는 게 정상인 시스템은 죽음과 정상이 똑같이 보인다. 외부 heartbeat에 사이클을 완주한 시점에만 신호를 보내게 하면 침묵 고장이 알림으로 바뀐다.