할일을 사람에게 맡기듯 AI에게도 맡길 수 있으면 어떨까. Butterfly에 "봇 멤버"를 넣으면서 결국 작은 에이전트 실행 환경을 만들게 된 과정과, 그 사이에 했던 고민을 정리했다.

1. 시작은 반대 방향이었다

처음 만든 건 봇이 아니라 커넥터(MCP 서버)였다. 2026년 10월, Claude 앱에서 "Butterfly에 할일 올려줘", "이번 주 남은 거 뭐야?"라고 말하면 Claude가 Butterfly 도구를 불러 할일을 조회·추가·완료하게 했다. 쓰다 보니 도구가 계속 늘었다 — 일괄 변경, 지난 마감 미루기, 검색, 날짜 범위 필터까지.

그런데 이 방식에는 분명한 한계가 있었다. 사람이 Claude를 열어야만 일이 시작된다. 할일 앱 안에서 "이건 AI가 해 줬으면" 싶은 순간에 할 수 있는 게 없었다.

그래서 방향을 뒤집었다. Claude가 Butterfly를 부르는 게 아니라, Butterfly의 할일이 Claude를 부르게.

2. 핵심 결정: 봇은 기능이 아니라 "멤버"다

AI 기능을 붙이는 가장 흔한 방법은 화면 어딘가에 ✨ 버튼을 다는 것이다. 우리는 그러지 않기로 했다. 대신 봇을 프로젝트 멤버로 만들었다.

  • 할일의 담당자로 봇을 고르면 → 봇이 일을 시작한다.
  • 봇은 결과를 댓글로 남긴다.
  • 댓글로 "여기 다시 봐 줘"라고 하면 → 봇이 이어서 처리한다.
  • 마감일이 있으면 그 시각에 실행한다.

새 UI를 거의 만들지 않아도 됐다. 담당자 시트, 댓글, 마감일, 알림 — 사람끼리 협업하려고 이미 만들어 둔 장치가 그대로 봇과의 인터페이스가 됐다. 사용자 입장에서도 배울 게 없다. 팀원에게 일을 맡기던 방식 그대로 봇에게 맡기면 된다.

3. 가장 오래 고민한 것: 누가 돈을 내고, 어디서 돌까

봇을 "멤버"로 정하고 나니 진짜 질문이 남았다. AI 호출 비용은 누가 내고, 실행은 어디서 하나? 정답이 하나가 아니어서 결국 실행 방식을 세 가지로 나눴다.

클라우드 봇 내 컴퓨터 봇 Claude 클라우드 작업 봇
실행 위치 Butterfly 서버 소유자의 컴퓨터 Anthropic 클라우드(예약 작업)
비용 소유자의 Anthropic API 키(쓴 만큼) 소유자의 Claude 구독 소유자의 Claude 구독
잘하는 일 글 작업 — 항상 켜져 있음 코드 작업 — 폴더 · 세션 · Git 구독으로 도는 클라우드 작업
멈추는 이유 월 한도, 키 오류 컴퓨터 꺼짐, 로그인 풀림 작업 설정 문제

클라우드 봇은 가장 단순하다. 소유자가 API 키를 등록하면 서버가 Messages API를 부른다. 키는 AES-GCM으로 암호화해 저장하고, 화면에는 끝 4자리만 보여 준다(다시 보여 주지 않고 교체만 된다). 월 토큰 한도를 두고, 이번 달 사용량을 토큰 수로 보여 준다.

내 컴퓨터 봇은 데스크톱 앱 안에 작은 러너를 두는 방식이다. 러너가 30초마다 서버에 heartbeat를 보내고 대기열(inbox)을 확인해, 일이 있으면 로컬의 claude -p로 처리하고 결과를 올린다. Butterfly는 AI를 직접 호출하지 않는다. 그래서 이 봇의 설정에는 사용량 · 한도 · 요금 항목이 아예 없다.

Claude 클라우드 작업 봇은 가장 나중에 붙였다. 소유자가 claude.ai에서 만든 예약 작업(routine)을 Butterfly 서버가 트리거 API로 깨우고, 작업은 이 봇 전용 커넥터로 할일을 다룬 뒤 report_result로 결과를 남긴다. 컴퓨터를 켜 둘 필요 없이 구독으로 도는 셈이다.

봇을 만든 뒤에는 실행 방식을 바꿀 수 없게 했다. 방식마다 설정 항목 자체가 달라서, 바꿀 수 있게 하면 설정 화면이 "이 방식이면 이 칸은 무시됩니다" 같은 예외로 가득 찬다.

4. 에이전트가 되는 순간: 도구 루프

처음의 클라우드 봇은 할일 내용을 읽고 답을 댓글로 쓰는 게 전부였다. 그러다 "하위 할일로 쪼개 줘", "마감 다시 잡아 줘" 같은 요청이 자연스럽게 나왔다. 글만 쓰는 봇은 그걸 말로만 해 줄 수 있었다.

그래서 커넥터에서 쓰던 Butterfly 도구를 봇에게도 줬다. 모델이 도구를 부르고, 결과를 보고, 다시 도구를 부르는 루프 — 이 순간부터 봇은 사실상 에이전트가 됐다. 같은 구현을 그대로 재사용하되 몇 가지를 조였다.

  • 범위를 프로젝트 안으로 묶었다. 계정 전체를 건드리는 도구(프로젝트 목록 · 생성, 일괄 변경)는 뺐다.
  • 왕복 횟수에 상한을 뒀다. 넘으면 거기까지의 결과로 끝낸다.
  • 오늘 날짜(소유자 시간대)를 프롬프트에 넣었다. "내일까지"를 해석하려면 오늘이 언제인지 알아야 한다.
  • 결과 댓글은 도구로 쓰지 않고 실행이 끝난 뒤 따로 남긴다.

작은 버그도 있었다. 모델이 도구를 부르기 전에 쓴 답변이 결과 댓글에서 빠졌다. 오늘의 운세를 부탁했더니 "운세를 할일로 정리했어요"만 남고 운세 본문이 사라진 게 그 증상이었다.

5. 만들면서 부딪힌 고민들

봇이 봇을 깨우는 무한 루프

봇이 할일을 고치면, 그 변경이 다시 "담당 봇 실행" 조건을 만족할 수 있다. 봇이 쓴 댓글이 봇을 다시 부르는 식이다. 그래서 봇이 쓰는 토큰에 botId를 실어 보내고, 서버가 "봇이 만든 변경"을 알아보면 담당 봇 재실행 같은 연쇄를 하지 않게 했다. 세 실행 방식 모두 같은 장치를 쓴다.

언제 실행할까

처음에는 "매일 정해진 시각에 담당 할일을 다시 읽고 새 할일로 응답"하게 만들었다. 써 보니 할일 앱의 리듬과 맞지 않았다. 결국 마감일에 실행하는 쪽으로 바꿨다. 시각까지 정한 마감은 그 시각에, 날짜만 정한 마감은 그날 아침에. 마감을 바꾸면 새 마감에 다시 돈다.

배포 직후나 봇을 다시 켰을 때 밀린 할일이 한꺼번에 도는 것도 막아야 했다. 실행 시각이 너무 오래 지난 할일은 크론이 건너뛴다.

남의 컴퓨터에서 AI가 코드를 고친다는 것

내 컴퓨터 봇에 코드 작업을 허용하면서 권한 설계에 가장 공을 들였다.

  • 할일마다 별도 worktree와 bot/<봇>/<할일> 브랜치를 만들고, 그 안에서만 고치고 커밋한다.
  • 허용하는 Git 명령은 status · diff · log · show · add · commit뿐이다. push · checkout · reset · branch는 거부한다.
  • 봇 기기 키 파일은 읽지 못하게 막았다.
  • 폴더만 고른 봇의 읽기 권한도 디스크 전체가 아니라 그 폴더 안으로 좁혔다.
  • 결과 댓글에 브랜치 · 커밋 수를 적고, 보호 브랜치(main/master)가 바뀌었으면 경고한다.
  • 할일이 완료되거나 지워지면 worktree를 정리한다. 커밋하지 않은 변경은 남겨 두고, 브랜치는 원래 저장소에 병합됐을 때만 지운다.

또 하나. 프로젝트에 붙은 봇은 멤버 누구나 부를 수 있다. 즉 다른 팀원이 내 컴퓨터와 내 Claude 구독을 쓰게 된다는 뜻이다. 그래서 봇 추가 마법사 마지막에 "함께 쓰는 봇이에요" 경고를 띄우고, "확인했어요"를 눌러야 다음으로 넘어가게 했다.

실패를 누구에게, 몇 번 알릴까

AI 기능은 실패하는 방식이 다양하다. 그리고 실패 안내가 뭉뚱그려지면 사용자는 아무것도 할 수 없다.

  • 처음엔 크레딧 부족이 "처리 중 오류, 다시 요청해 주세요"로 나갔다. 다시 요청해도 같은 이유로 실패하니 의미가 없었다. 원인을 구분해서 알리게 바꿨다.
  • 한도 도달이나 키 오류는 할일 작성자가 아니라 **고칠 수 있는 사람(봇 소유자)**에게 알려야 한다.
  • 그리고 한 번만 알린다. 안 그러면 맡긴 할일마다 같은 푸시가 쌓인다. 한도는 달마다 한 번, 키 오류는 키를 다시 저장할 때까지 한 번. 안내 댓글 아래에는 소유자에게만 "한도 바꾸기 · 키 바꾸기" 버튼을 붙였다.
  • 컴퓨터 봇이 꺼져 있으면 "꺼져 있어요" 안내를 한 번 남긴다. 일을 가져가면 "받았어요" 댓글을 한 번 남긴다. 이건 상태가 아니라 사건이라, 할일에 상태 칩을 붙이지 않았다.

봇에게 규칙을 어떻게 알려 줄까

봇마다 지침(Markdown)을 둘 수 있다. 여기에 더해 프로젝트 공지를 지침처럼 읽게 했다. 관리자가 공지로 프로젝트 규칙을 정하면 봇도 따른다. 처음엔 모든 공지를 읽게 했다가, 공지를 올릴 때 "봇 지침으로 쓰기"를 켠 것만 읽도록 바꿨다(기본 꺼짐). 공지가 길게 쌓여도 실행마다 드는 토큰이 끝없이 늘지 않도록 글자 수 상한에서 자른다. 봇 지침과 공지가 부딪히면 봇 지침이 먼저다.

작은 것들

  • 봇 결과 댓글은 서버가 직접 붙인다. 할일을 통째로 다시 저장하는 기존 경로를 타면 동시 편집과 충돌한다.
  • 앱이 표를 그리지 못해서, 봇에게 표 대신 목록으로 답하라고 했다.
  • 봇이 댓글을 남겨도 앱이 포그라운드로 돌아오기 전엔 몰랐다. 기존 "댓글" 알림 채널을 그대로 재사용해 작성자에게 알리고, 포그라운드에서 푸시를 받으면 바로 동기화하게 했다.
  • 모델 이름을 자유 입력으로 받았더니 오타 하나로 봇이 조용히 실패했다. 고정 선택지로 바꿨다.

6. 돌아보며

  • 기존 협업 장치가 최고의 AI 인터페이스였다. 담당자 · 댓글 · 마감일 · 알림. 봇을 위해 새로 만든 화면보다 이미 있던 걸 봇에게 열어 준 게 훨씬 자연스러웠다.
  • "누가 돈을 내는가"가 아키텍처를 정했다. API 키냐 구독이냐에 따라 실행 위치, 설정 항목, 멈추는 이유, 안내 문구까지 전부 갈라졌다.
  • 에이전트는 도구를 주는 순간 시작되고, 범위를 좁히는 데서 완성된다. 도구 루프 자체보다 프로젝트 범위, 왕복 상한, 연쇄 차단, Git 명령 화이트리스트 같은 울타리에 시간이 더 들었다.
  • 실패 안내는 기능의 절반이다. 원인을 구분하고, 고칠 수 있는 사람에게, 한 번만.