Claude Code의 AI 에이전트로부터 Discord 멘션 알림을 보내는 구현

하고 싶은 것

Claude Code를 사용하여 「AI가 자율적으로 계속 움직이는 메커니즘」을 구축하다 보면, 다음과 같은 문제가 발생한다.

AI가 「사장님의 판단이 필요합니다」라고 판단하여 카드를 만들었음에도, 사람이 알아차리지 못하는 경우다.

president-office/requests/

에 의뢰 카드를 두어도, 사람이 직접 대시보드를 열지 않으면 알 수 없다. AI는 사람에게 능동적으로 알림을 보낼 수 없다.

이를 해결하기 위해 「AI 에이전트가 의뢰 카드를 생성했을 때, Discord에서 사람을 멘션(Mention)하여 본문을 보내는」 메커니즘을 구현했다.

구성

AI 에이전트
→ 의뢰 카드 생성 (president-office/requests/*.md)
→ discord-request 명령어 실행
...

사람은 Discord 알림만 확인하면 카드 내용도 그 자리에서 읽을 수 있고, 대시보드에서 조작할 수 있다.

구현

1. Discord Webhook URL 가져오기

• Discord 서버의 임의 채널을 연다
• 채널 설정 → 연동 서비스 → 웹후크(Webhook) → 새 웹후크
• Webhook URL을 복사한다

2. 자신의 Discord User ID 가져오기

• Discord 설정 → 고급 설정 → 개발자 모드: ON
• 자신의 아이콘을 우클릭 → 「사용자 ID 복사」

3. 환경 변수 설정하기

# .env (public repo에 커밋하지 말 것)
# DISCORD_TIMELINE_WEBHOOK_URL=<Webhook URL>
# DISCORD_PRESIDENT_USER_ID=<자신의 Discord User ID (18자리 숫자)>

4. notify.py에 함수 추가하기

# src/discord_bot/notify.py
DISCORD_MAX_CHARS = 1900
def mention_president() -> str:
...

5. CLI 명령어 만들기

# src/discord_bot/request_notifier.py
import sys
from src.discord_bot.notify import notify_request_card
...

# pyproject.toml
[project.scripts]
discord-request = "src.discord_bot.request_notifier:main"

6. AI 에이전트가 의뢰 카드를 만들면 자동으로 보내기

rules/16-agent-to-president-requests.md

에 추가:

## Discord 알림 (필수)
의뢰 카드를 생성하면 반드시 Discord에 알림을 보낸다.
```bash
...

그 후 에이전트가 규칙을 읽고 있다면, 카드 생성 → `discord-request` 실행을 자동으로 수행한다.

## 실제로 도착하는 메시지

@mino 📬 새로운 의뢰가 있습니다 — 2026-05-16-4-article-review.md

title: 기사 리뷰 의뢰
...

이렇게 하면 스마트폰의 Discord 앱으로 알림이 오고, 그 자리에서 내용을 확인할 수 있다.

## 포인트

**AI에서 사람으로의 알림은 Webhook이 가장 심플하다**. Discord의 bot token을 사용하는 방법도 있지만, Webhook이 권한 설정이 필요 없고 게시만 하기에는 충분하다.

**카드 본문을 전체 전송함으로써**, 대시보드를 열지 않고도 Discord 상에서 내용을 파악할 수 있다. 2000자 제한이 있으므로 긴 문장은 끝부분을 자르고 URL을 첨부하는 설계로 했다.

**DISCORD_PRESIDENT_USER_ID가 설정되어 있지 않아도 에러를 내지 않는다**. 멘션 없이 채널 게시만 이루어지지만, 알림 자체는 전달된다. 환경 변수가 불완전해도 계속 작동하는 것이 자율 운용의 철칙이다.

## 응용

동일한 메커니즘으로 「기사 리뷰 의뢰」, 「삭제 의뢰」, 「승인 의뢰」 모두에 대응할 수 있다. 의뢰 카드 템플릿을 종류별로 준비해 두면, AI가 카드 종류에 따른 적절한 메시지를 보낼 수 있다.

더 발전시킨다면, Discord의 슬래시 커맨드 (Slash Command)를 사용하여 인간이 Discord에서 직접 「승인」 버튼을 누를 수 있도록 만들 수도 있다. 현재는 대시보드 (Web UI)에서 승인하는 설계이지만, Discord만으로 완결되는 동선도 흥미로울 것이다.

나의 AI 회사 운영에서는, 아침에 일어나 Discord를 확인하는 것만으로 「AI가 무엇을 만들었는지 · 무엇을 물어보고 있는지」를 한눈에 알 수 있도록 되어 있다. 인간이 PC 앞에 앉지 않아도 판단할 수 있는 상태가 자율 운영 (Autonomous Operation)의 이상적인 형태라고 생각한다.

### Discussion

![](https://static.zenn.studio/images/drawing/discussion.png)