일이 끝나면 폰으로 알림 받기 — 클로드가 끝나거나 막히면 폰이 울리게 (ntfy)

오래 걸리는 일을 시켜 놓고 자리를 뜨면 「끝났나?」가 계속 궁금합니다. ntfy는 주소 한 줄에 글자를 보내면 그 글자가 내 폰 알림으로 오는 무료 서비스입니다. 가입이 없습니다. 그래서 이 편에서 가장 중요한 것이 추측하기 어려운 주제 이름입니다. 주제 이름이 곧 비밀번호입니다. (예시 자료는 가짜 이름입니다.)

이 편에서는 실제로 알림을 보내지 않았습니다. 2·4·6단계의 🤖 은 제가 클로드로 실제로 돌려 받은 답이고, 4단계에서 만든 알림 프로그램은 바깥으로 나가는 부분을 가짜로 바꿔서만 돌려 봤습니다. 5·7단계의 🤖 은 **「예시 답」**입니다.

시작 전에

• 빈 폴더 하나를 만들고(영문 이름, 예: alert-test), 그 폴더에서 클로드(Claude Code)를 엽니다. 여는 법과 승인 방식(처음에는 Manual)은 02편 시작 전에와 같습니다.
• Node.js가 깔려 있어야 합니다. 4단계에서 클로드가 만드는 알림 프로그램이 Node.js 로 돕니다. 확인하는 법은 09편 시작 전에와 같습니다.
• 폰(안드로이드 또는 아이폰)이 필요합니다. 앱은 1단계에서 깝니다.
• 알림은 **공개 서버(ntfy.sh)**를 지나갑니다. 공식 FAQ 는 서버 운영자의 기록에 주제 이름과 접속 주소(IP)가 남고, 모든 메시지가 구글의 푸시 서비스(FCM)에도 올라간다고 적고 있습니다. 민감한 내용이면 직접 서버를 돌리라는 안내입니다. 그래서 알림에는 비밀번호·개인 정보·고객 자료를 넣지 않습니다. (FAQ)
• 공용 서버의 한도: 하루 메시지 250개, 한 통은 4,096바이트(한글은 한 글자가 3바이트라 한글만이면 1,300자 남짓)까지입니다. (발행 안내의 한도 절)

1단계 · 폰에 ntfy 앱 깔기 (내가 직접)

이 단계는 클로드에게 말하지 않고 내가 직접 합니다. 공식 문서는 구글 플레이, 앱 스토어(아이폰), F-Droid 에서 받을 수 있다고 안내합니다. 스토어에서 ntfy 를 검색해 설치하세요. (폰 안내)

✅ 이렇게 나오면 성공 — 폰에 ntfy 앱이 깔리면 됩니다. 아직 주제를 등록하지 마세요. 3단계에서 합니다.

2단계 · 추측하기 어려운 주제 이름 만들기

주제 이름을 .env 파일에 적고, 그 파일이 저장소에 올라가지 않게 합니다. 이름 뒤에 명령으로 만든 난수를 붙이게 합니다. 클로드가 명령 실행을 허락하라고 하면 무슨 명령인지 읽고 허락하세요.

✅ 이렇게 나오면 성공 — 폴더에 .env 와 .gitignore 가 생기고, .env 안에 NTFY_TOPIC= 다음에 긴 글자가 있으면 다음 단계로. 난수를 만드는 명령은 PC 마다 다를 수 있습니다(제 PC 에서는 openssl 이었습니다). 난수를 만들 명령이 없다고 하면 클로드가 「제가 지어낸 글자」라고 솔직히 말합니다(제가 처음 시험에서 명령을 막아 두었더니 실제로 그랬습니다). 그때는 이렇게 말하세요: "Node.js 로 진짜 난수를 만들어서 다시 적어 줘." .gitignore 는 이 폴더를 git 저장소로 만든 뒤부터 효과가 있습니다(클로드도 같은 말을 했습니다).

3단계 · 폰에서 그 주제 구독하기 (내가 직접)

폰의 ntfy 앱에서 주제를 추가합니다. 앱의 단추 이름과 모양은 판에 따라 다르니, 「주제(topic)를 더하는 단추」(보통 + 모양)를 찾으세요. (폰 안내) 주제 이름 칸에 .env 에 적힌 이름 전체를 한 글자도 틀리지 않게 넣습니다. 서버는 기본값(ntfy.sh)을 그대로 둡니다. 이름이 길어 옮기기 불편하면 메모 앱이나 비밀번호 관리 앱에 적어 폰으로 옮기세요. 단체 채팅방이나 공개 게시판에는 붙여 넣지 마세요.

✅ 이렇게 나오면 성공 — 앱의 목록에 방금 넣은 주제가 보이면 됩니다. 아직 알림은 오지 않습니다.

4단계 · 알림을 보내는 작은 프로그램 만들기

이 주제로 글자를 보내는 프로그램을 만듭니다. 아직 보내 보지는 않습니다. 만들어진 것을 먼저 읽어 본 다음 5단계에서 보냅니다.

✅ 이렇게 나오면 성공 — 폴더에 notify.js 가 생기고, 클로드가 쓰는 법(node notify.js "글자")을 알려 주면 다음 단계로. 파일 이름·쓰는 법은 클로드마다 조금 달라도 괜찮습니다. (시험 환경에서는 클로드의 명령 실행을 꺼 두어, 위 답에서 「문법 검사를 못 했다」는 줄을 뺐습니다. 내 PC 에서는 클로드가 직접 확인해 줄 수 있습니다.)

5단계 · 시험 알림 한 번 보내기 (예시 답)

✅ 이렇게 나오면 성공 — 몇 초 안에 폰에 「시험 알림입니다」 알림이 뜨면 됩니다. 안 오면 아래 「막히면」 첫 항목을 보세요.

6단계 · 일이 끝나거나 막히면 알리라고 규칙 심기

매번 「알림도 보내 줘」라고 말하지 않아도 되도록, 이 폴더의 규칙 파일 CLAUDE.md 에 적어 둡니다. 여기에 알림에 넣지 말 것도 같이 적게 합니다.

✅ 이렇게 나오면 성공 — CLAUDE.md 가 생기고 「언제」「무엇을 뺀다」「안 알리는 경우」가 적혀 있으면 됩니다. 「안 알리는 경우」 줄이 중요합니다. 매번 울리면 곧 아무도 안 봅니다. (이 답에서도 시험 환경이라 알림을 못 보낸다는 줄을 뺐습니다.)

7단계 · 진짜로 써 보기 (예시 답)

✅ 이렇게 나오면 성공 — 일이 끝날 때 폰에 「목차 만들기 끝」 알림이 뜨면 됩니다. 이제 긴 일을 시켜 놓고 자리를 떠도 됩니다. 알림 글은 한 줄로, 무슨 일인지만 담게 하세요.

다 됐습니다 — 이제 이렇게 말하면 됩니다

항상 이 폴더에서 클로드를 열고 이야기합니다.

• 「이 일은 오래 걸릴 거야. 끝나거나 막히면 알림 보내 줘.」
• 「이번 일은 짧으니까 알림 보내지 마.」
• 「지금 알림 규칙이 뭔지 CLAUDE.md 를 읽고 말해 줘.」
• 「알림 제목에 [긴급] 을 붙이는 옵션을 notify.js 에 더해 줘. 한글이 들어가도 되게.」

막히면

• 폰에 알림이 안 온다 → 가장 흔한 원인은 주제 이름이 한 글자라도 다른 것입니다(대소문자·하이픈 포함). 그다음은 폰에서 ntfy 앱의 알림이 꺼져 있거나 방해 금지 모드인 경우입니다(안드로이드 공식 안내는 알림 우선순위마다 채널이 따로 있고 방해 금지를 무시하게 정할 수 있다고 적습니다). 이렇게 다시 말하세요: "notify.js 가 보낸 주소와 응답 상태 번호를 알려 줘. 주제 이름은 가리고 보여 줘."
• 프로그램이 한글 제목을 넣다가 오류를 내거나 글자가 ? 로 나온다 → 알림 제목을 HTTP 머리말(헤더)에 한글로 넣어서 생기는 문제입니다. 공식 문서도 헤더의 UTF-8 은 「모든 라이브러리가 지원하는 것은 아니다」라고 적고, 제 시험에서 Node.js 는 글자 코드 오류(TypeError)를 냈습니다. 이렇게 다시 말하세요: "제목과 본문은 헤더 말고 JSON 으로 보내게 고쳐 줘. 한글이 들어가도 되게." 공식 문서에 JSON 으로 보내는 방법이 있고, 이때는 서버 맨 위 주소(주제 주소가 아님)로 보내며 주제 이름은 JSON 안의 topic 칸에 적습니다.
• 클로드가 일이 끝나도 알림을 안 보낸다 → CLAUDE.md 의 규칙은 부탁이지 강제가 아닙니다(02편). 이렇게 다시 말하세요: "방금 일이 끝났는데 알림을 안 보냈어. CLAUDE.md 의 알림 규칙을 읽고 지금 보내 줘." 클로드를 연 폴더가 이 폴더인지도 확인하세요. 규칙 파일은 클로드를 연 폴더(와 그 위쪽 폴더)의 것만 처음에 읽힙니다.
• 주제 이름이 새어 나갔을지 모른다 → 이름을 아는 사람은 누구나 받고 보낼 수 있습니다. 이렇게 말하세요: "새 주제 이름을 만들어 .env 를 바꿔 주고, 폰에서 바꿔야 할 일을 알려 줘." 그리고 폰에서 옛 주제를 지우고 새 주제를 구독합니다.
• 하루 한도(250개)에 걸린다 → 공용 서버는 하루 메시지가 250개입니다. 진행 상황마다 보내지 말고 「끝났을 때·막혔을 때」만 보내게 하세요.
• 알림에 회사 자료나 개인 정보를 넣었다 → 공용 서버를 지나간 글은 되돌릴 수 없습니다. 앞으로는 「무슨 일이 끝났는지」만 적게 하세요. 민감한 내용이 꼭 필요하면 이 편의 범위를 벗어납니다(공식 FAQ 는 직접 서버를 돌리라고 합니다).
• 클로드가 영어로 답한다 → 이렇게 다시 말하세요: "한국어로 답해 줘. 앞으로도 계속 한국어로 답하게 CLAUDE.md 에 한 줄 적어 줘."

한 번에 맡기기 (익숙해진 다음에)

역할: 너는 내 PC 에서 일하는 도우미다. 내 폰으로 알림(ntfy)을 보내는 작은 프로그램을 만들고, 앞으로 오래 걸리는 일이 끝나거나 막히면 알림을 보내도록 이 폴더의 규칙(CLAUDE.md)을 세워 준다. 나는 초보자이니 어려운 말은 풀어서, 한 단계씩 말해 줘.

맥락: 지금 열려 있는 폴더가 작업 폴더다. ntfy 는 가입 없이 주소 한 줄에 글자를 보내면 폰 알림이 오는 서비스이고, 공용 서버 ntfy.sh 를 쓴다. 주제(topic) 이름이 곧 비밀번호라서 이름을 아는 사람은 누구나 받고 보낼 수 있다. 주제 이름은 영문·숫자·밑줄·하이픈만, 64자 이하다. 공용 서버는 하루 메시지 250개, 한 통 4,096바이트까지다. 글자는 HTTP 머리말(헤더)보다 요청 본문이나 JSON 으로 보내야 한글이 안전하다. 알림 내용은 공용 서버를 지나 밖으로 나간다.

입력: <운영체제>, <쓰는 클로드: Claude Code 터미널 / 데스크톱 앱의 Code 탭>, <주제 이름 앞부분: 예 claude-alerts>

작업:
① 확인 — 지금 폴더의 전체 경로를 말해 준다. Node.js 가 있는지(node --version) 본다. .env·.gitignore·notify.js·CLAUDE.md 가 이미 있으면 덮어쓰지 말고 멈춰서 묻는다.
② 주제 이름 — 앞부분 뒤에 명령으로 만든 진짜 난수(예: 16진수 32자리)를 붙여 .env 에 NTFY_TOPIC 으로 적는다. 네가 글자를 지어내지 말고, 난수를 만들 명령이 없으면 멈춰서 말해 준다. .gitignore 에 .env 를 넣는다. 주제 이름은 이 대화에서 화면에 다시 출력하지 않는다(내가 .env 를 열어 폰에 옮긴다).
③ 프로그램 — notify.js 를 만든다. 같은 폴더의 .env 에서 NTFY_TOPIC 을 읽고, 인자나 표준입력으로 받은 한 줄을 https://ntfy.sh/<주제> 로 POST 한다(Node.js 내장 fetch, 설치할 패키지 없음, 10초 시간 제한). 한글이 안전하도록 제목은 헤더에 넣지 않는다. 주제가 없거나 메시지가 비면 보내지 않고 안내한 뒤 오류 코드로 끝낸다. 성공하면 「알림을 보냈습니다.」, 실패하면 상태 코드를 보여 주되 주제 이름은 화면에 쓰지 않는다. 아직 실행하지 말고 코드가 맞는지만 node --check 로 확인한다.
④ 규칙 — CLAUDE.md 를 만든다. 오래 걸리는 일이 끝났을 때, 또는 확인·권한·오류 때문에 막혔을 때만 notify.js 로 한 줄 알린다. 짧은 작업이나 대화 중 바로 답하는 경우에는 알리지 않는다. 비밀번호·키·토큰·.env 내용(주제 이름 포함)·개인 정보·고객 자료는 알림에 넣지 않는다. 알림이 실패해도 일은 계속하고 실패한 사실을 알린다.
⑤ 사람이 할 일 안내 — 내가 직접 할 두 가지를 말해 주고 멈춰서 기다린다. 가) 폰에 ntfy 앱을 깔고(공식 스토어에서 ntfy 검색), 앱에서 .env 의 주제 이름 전체를 구독한다. 나) 다 했으면 내가 「예」라고 말한다.
⑥ 시험 — 내가 「예」라고 하면 node notify.js "시험 알림입니다" 를 한 번만 실행하고, 폰에 알림이 오는지 내게 묻는다. 안 오면 주제 이름 한 글자 차이·폰 알림 설정을 먼저 안내한다.
⑦ 마무리 — 초보자 눈높이로 무엇이 만들어졌고 앞으로 어떻게 말하면 되는지(예: 「이 일 끝나면 알림 보내 줘」) 설명한다. 주제 이름이 새면 새 이름으로 바꾸는 법도 알려 준다.

제약: 비밀키·토큰·비밀번호를 출력하거나 파일에 쓰지 않기(주제 이름은 .env 에만). 오류를 건너뛰지 않기. 기존 파일을 지우지 않기(덮어쓰지도 않기). 이 폴더 밖의 파일을 읽지도 쓰지도 않기. 내가 「예」라고 하기 전에는 알림을 보내지 않기. 알림에 회사 자료·개인 정보를 넣지 않기. 프로그램을 대신 설치하지 않기.

출력: 한 일, 확인된 것(Node.js 버전), 만든 파일 목록, 검증 결과, 내가 해야 할 두 가지(⑤ 그대로), 남은 문제와 다음 조치.

검증: 아래를 파일을 다시 열어서 확인하고, 하나라도 실패하면 완료로 보고하지 말 것. 폰 구독과 알림 도착은 네가 확인할 수 없으므로 「남은 일」로 적는다.
 (가) .env 에 NTFY_TOPIC 이 있고 값이 영문·숫자·밑줄·하이픈 64자 이하이며 난수 부분이 길다.
 (나) .gitignore 에 .env 가 있다.
 (다) notify.js 가 node --check 를 통과하고, 안에 주제 이름이 글자로 적혀 있지 않다(.env 에서 읽는다).
 (라) CLAUDE.md 에 「언제 알린다」「알림에 넣지 않는 것」「알리지 않는 경우」가 모두 있다.
 (마) 주제 이름 글자가 .env 말고 다른 어떤 파일에도 없다(글자 검색으로 확인).

내가 만들 때는

처음엔 이렇게 시켰습니다. 2026-08-03 14:27, 개인 비서 AI(파이스)를 키우던 날 이렇게 말했습니다. 「…나는 이걸 아이폰, 맥북, 아이패드 등에 연결해서 진짜 개인 비서처럼 쓰고 싶어.」 세 시간 가까이 뒤(17:13)에는 이렇게 덧붙였습니다. 「…나중에 내가 나가서 핸드폰으로 확인할 테니 반응형으로 아이폰 17 새 화면에서도 잘 나오게 해 줘. 그런 다음 phase 2 시작해.」 폰으로 밖에서 쓰려면 문제가 하나 있었습니다. 창을 닫거나 폰 화면이 잠기면 연결이 끊기고 작업도 같이 멈췄습니다. 연결이 닫히면 중단하는 코드였기 때문입니다. 「시켜 놓고 잊을 수 없으면 비서가 아니다」가 그날 이유였고, 17:29 에 작업을 연결과 분리한 할 일 줄(잡 큐)과 완료 알림이 붙었습니다. 알림은 ntfy 와 직접 만드는 브라우저 푸시를 견줘서 ntfy 를 골랐습니다. 요청 한 줄이면 되고 글은 최소한만 보냅니다. 그때 적은 주의가 이 편의 2단계입니다. 알림이 외부 서비스를 지나가고, 주제 이름을 아는 사람은 누구나 받으므로 주제 이름을 비밀로 다룹니다.

9월 11일에는 예약된 일의 결과를 폰 알림·메일·캘린더로 보내는 갈래를 붙였고, 9월 23일부터 새벽에 스스로 채점하는 밤 채점이 폰 알림을 씁니다. 여기서 알림이 너무 많아도, 너무 적어도 문제라는 것을 배웠습니다. 매일 울리면 아무도 안 봐서 「새로 틀린 것에만 한 번」 보내게 했습니다. 그런데 카드 요약이 9월 29일부터 며칠째 매일 떨어져 있었는데 「새로 틀린 것만」 알려서 폰은 한 번 울렸거나 아예 안 울렸습니다. 며칠째 같은 실패는 알림이 아니라 보고서를 거슬러 읽어야 보였습니다. 그래서 이 편의 6단계에는 「언제 알리고, 언제 알리지 않나」를 함께 적었습니다. 그리고 알림 하나가 아닌 정기 보고서를 따로 두는 것이 안전합니다.

→ 뒷이야기 5단계(2번 「Phase 1 개통 · Phase 2 시켜놓고 잊기」)에서 알림을 붙인 날을, 11단계에서 예약 결과 알림 갈래를, 15단계에서 밤 채점의 알림 함정을 자세히 보세요.