항상 대화할 수 있는 환경 만들기 — Python 봇에서 Claude Code 채널로

Sullivan은 Selforge 프로젝트의 사고 파트너 에이전트예요. 텔레그램으로 생각을 보내면 분류하고, 정기적으로 회고를 돕고, 아침 브리핑을 보내는 시스템이었어요.

초기 아키텍처는 이랬어요:

[Telegram] → [Python bot.py (launchd 데몬)]
                → scheduler.py (cron 트리거)
                → agents/capture.py (Anthropic API 호출)
                → agents/reflection.py (Anthropic API 호출)
                → obsidian.py (파일 읽기/쓰기)

Python이 텔레그램 메시지 수신부터 전처리, Claude API 호출, 후처리, Obsidian 저장, 텔레그램 응답까지 모든 단계를 관리하고 있었어요. 각 에이전트마다 프롬프트 조립, 에러 핸들링, fallback 로직을 전부 Python으로 짜야 했고요.

운영하면서 세 가지 마찰이 명확해졌어요.

1. 개선 병목: 에이전트 행동을 바꾸려면 코드 수정 → 테스트 → deploy.sh 파이프라인을 매번 타야 했어요. MD 파일에 에이전트 행동을 서술해뒀지만, 실제 동작은 Python 코드가 결정했어요. MD와 코드 사이의 괴리가 점점 벌어졌고요.

2. 코드 복잡성: Python 약 2000줄. 각 에이전트마다 프롬프트 조립, API 호출, 에러 핸들링, 응답 파싱 로직이 있었어요. LinkedIn에서 콘텐츠를 추출하는 로직만 해도 Voyager API, surrogate character 처리, agent_mode fallback 등이 겹겹이 쌓여 있었고요.

3. API 비용 구조: Anthropic API 종량제로 월 $5~15 소요. 금액보다 “호출 최적화”라는 인지적 비용이 컸어요. 충분한 컨텍스트를 줘야 좋은 결과가 나오는데, 비용을 의식하면 프롬프트를 줄이게 돼요.

이 세 마찰의 공통 원인은 하나였어요 — Python이라는 중간 레이어. Claude가 직접 할 수 있는 일(파일 읽기/쓰기, URL 추출, 텍스트 분석)을 Python이 대신하고 있었어요.

Claude Code Channels에 텔레그램 플러그인이 추가되면서, 아키텍처 전환의 가능성이 열렸어요.

Channels의 핵심은 이거예요:

• Claude Code 세션이 직접 텔레그램 메시지를 수신/발신
• 파일 I/O는 네이티브 도구(Read, Write, Glob)로 처리
• URL 콘텐츠 추출은 WebFetch로 처리
• 스케줄링은 CronCreate로 처리
• API 호출 비용이 없음 (구독 내 포함)

가장 근본적인 변화: 에이전트의 행동을 MD 파일이 직접 결정해요. Agent MD에 “vault에서 오늘 Captures를 읽고 맥락 기반 질문을 던진다”라고 쓰면, Claude가 Read, Glob 등 네이티브 도구를 활용해서 그대로 수행해요. Python으로 “파일 경로 조립 → glob → 파일 읽기 → 프롬프트 조립 → API 호출”을 코딩할 필요가 없어요.

두 번째 채널(PM)을 구축하면서 에이전트 정의와 채널 하네스가 서로 다른 설계 레이어라는 걸 알게 됐어요.

에이전트 정의 (.claude/agents/selforge-pm.md): “이 에이전트는 무엇인가” — 역할, 가치 계층, 정보 수집 프로토콜, 질문 전략. 서브에이전트로 호출될 때의 행동 명세예요.

채널 하네스 (.claude/skills/pm-channel.md): “이 세션에서 어떻게 동작하는가” — 페르소나 정체성, 톤, 메시지 라우팅, 크론 스케줄, 위임 규칙. 메인 세션이 페르소나를 입을 때의 운영 명세예요.

Sullivan 채널이 잘 돌아간 이유는 이 두 층이 모두 갖춰져 있었기 때문이에요. PM 채널에는 에이전트 정의만 있었고 하네스가 없었어요.

여기서 추가로 설계 결정이 필요했어요 — 세션에서 사용자와 소통하는 주체를 어떻게 구성할 것인가.

Orchestrator-as-persona 패턴을 선택했어요. 메인 Claude Code 세션 자체가 “나는 셀피다”로 동작하고, 코드 구현 같은 무거운 작업만 서브에이전트에 위임하는 구조예요. Sullivan 채널도 이미 이 패턴이었고, Anthropic 공식 가이드도 이걸 추천하더라고요.

실제 PM 하네스에 들어간 핵심 요소:

## 셀피의 정체성
셀피는 Selforge의 전략적 PM이자 흐민의 시스템 파트너.

## 메시지 라우팅
/status → 시스템 전체 상태 점검
/plan   → 이번 주 태스크 현황 + 제안
/daily  → 오늘 태스크 브리핑
기본값  → 셀피로서 직접 응답

## 역할 경계
사고/감정 관련 메시지 → "이건 설리반이 더 잘 도와줄 수 있을 것 같아요."

역할 경계를 문서에서 명시적으로 강제하지 않으면, LLM은 맥락에 따라 역할이 흐려져요. “이것은 하지 않는다”를 구체적으로 나열하는 게 효과적이었어요.

CLAUDE.md는 프로젝트 레벨이라 모든 세션이 공유해요. CLAUDE.md에 세션 분기 로직(“세션 이름을 확인하고 해당 파일을 로드하라”)을 넣는 것도 가능하지만, Claude가 이 라우팅을 따르지 않는 경우가 간헐적으로 발생했어요.

init prompt 방식이 더 안정적이에요. 세션의 첫 번째 사용자 메시지이므로 Claude가 반드시 처리하고, 읽어야 할 파일 경로를 명시적으로 전달하니 모호함이 없어요.

selforge/
├── CLAUDE.md                      ← 모든 세션이 공유 (프로젝트 규칙)
├── .claude/agents/
│   ├── sullivan.md                ← 사고 파트너 에이전트 정의
│   └── selforge-pm.md             ← PM 에이전트 정의
├── .claude/skills/
│   ├── sullivan-channel.md        ← Sullivan 채널 하네스
│   └── pm-channel.md              ← PM 채널 하네스

각 Runner 스크립트의 핵심 차이는 INIT_PROMPT 하나예요:

# sullivan-runner.sh
INIT_PROMPT="Read .claude/skills/sullivan-channel.md and follow the instructions"

# pm-runner.sh
INIT_PROMPT="Read .claude/skills/pm-channel.md and follow the instructions"

이 패턴은 Claude Code Channels 세션이 영속적으로 운영되는 환경을 전제로 해요. tmux + Runner(while true) + LaunchAgent + Watchdog의 영속성 체인이 세션의 크래시 복구와 자동 재시작을 담당하고요. 세션이 (재)시작되면:

1. Claude Code가 Channels 모드로 기동 → 텔레그램 봇 연결
2. CLAUDE.md 자동 로딩 — 프로젝트 공통 규칙 적용
3. init prompt 수신 → 해당 채널 하네스 파일을 읽음
4. 에이전트 역할로 전환 + 크론 스케줄 등록
5. 이제 이 텔레그램 봇은 해당 에이전트로 동작

두 에이전트가 같은 프로젝트 파일에 접근하니까 유기적 협력도 가능해요. Sullivan이 vault에 저장한 인사이트를 셀피가 주간 리뷰에서 참조하고, tmux send-keys로 세션 간 직접 통신도 할 수 있어요.

Python 봇 대비 세 가지 리스크가 있어요.

1. 세션 의존성

• 문제: Claude Code 세션이 죽으면 봇이 멈춤
• 완화: tmux + Runner(while true) + LaunchAgent + Watchdog 4레이어 영속성 체인
• 한계: 맥이 완전히 꺼져 있으면 불가능

2. CronCreate 7일 만료

• 문제: recurring 작업이 7일 후 자동 만료
• 완화: 하트비트 패턴 — 매일 00:05에 CronList 점검 + 누락 시 재등록
• 구조: 각 크론 프롬프트 파일(.claude/skills/cron/*)에 CronList 확인 로직이 포함되어, 누락 시 자동 재등록

## Step 0: 크론 점검 (세션 시작 시 1회)
CronList를 실행한다. 6개 작업이 모두 있는지 확인한다.
누락이 있으면 scheduler.md를 읽고 누락된 작업만 재등록한다.

3. 비결정성

• Python: 동일 입력 → 동일 출력 (결정적)
• Claude: 동일 입력 → 다른 출력 가능 (비결정적)
• 판단: 회고 질문, 인사이트 발견처럼 “매번 다른 관점”이 가치인 영역에서는 비결정성이 오히려 장점

추가로, 텔레그램 환경에서 채널을 여러 개 운영할 때 환경변수 문제를 겪었어요. Claude Code가 MCP 서버를 스폰할 때 환경변수를 세정(sanitize)해서 TELEGRAM_STATE_DIR이 전달되지 않았거든요. 세 채널이 같은 봇 토큰으로 폴백해서 하나만 동작하는 상황이었어요. 부모 프로세스의 환경변수를 복원하는 브릿지 스크립트로 해결했고요. “당연히 전달될 것”을 가정하지 말고 항상 확인해야 한다는 걸 배웠어요.

이 전환의 핵심 레슨을 정리하면 이래요.

중간 레이어가 정당한지 주기적으로 질문한다. “이 코드가 하는 일을 도구가 직접 할 수 있는가?”

Python 봇의 모든 코드는 본질적으로 “배관(plumbing)“이었어요. 메시지를 전달하고, 파일을 읽고 쓰고, API를 호출하는 — Sullivan의 핵심 가치인 포착, 분류, 요약, 회고와는 무관한 코드였어요. Claude Code가 그 배관을 네이티브로 제공하게 되면서, Python 레이어의 존재 이유가 사라졌어요.

추가로 이 과정에서 얻은 설계 원칙들:

• 에이전트 정의(what)와 채널 하네스(how)는 별개의 레이어다. 에이전트가 무엇인지 정의하는 것과, 세션에서 어떻게 동작하는지 정의하는 건 다른 문서에요. 이 구분이 없으면 “에이전트를 만들었는데 왜 채널에서 안 되지?”라는 혼란이 생겨요.
• MD가 곧 코드인 세계에서, 하네스 파일은 행동 명세서다. 채널 하네스에 두 가지 동작 모드가 혼재하면 Claude의 행동이 예측 불가능해져요. 한 하네스에는 한 모드만 기술해야 해요.
• 두 번째를 만들 때 첫 번째의 구조가 보인다. Sullivan 채널을 만들 때는 자연스럽게 진화했던 구조가, PM 채널을 만들면서 비로소 명시적인 패턴으로 정리됐어요. 시스템을 이해하는 가장 좋은 방법은 두 번째 인스턴스를 만들어보는 거예요.