가이드를 더 잘 쓰는 것보다, 가이드를 없애는 게 빠르다

어제 5/4 강의에서 학생들이 막힌 곳을 줄세워 보면 이런 모양이었다.

"python을 찾을 수 없습니다" — Python 설치할 때 PATH 체크박스 놓침
python ~\Desktop\bot.py — PowerShell 의 ~ 가 외부 명령 인자에서 풀리지 않음 (내가 검증을 $HOME 으로 해놓고 일반화한 죄)
메모장이 자동으로 bot.py.txt 로 저장 — 학생은 bot.py 라고 생각하지만 파일은 다른 이름
Drive 다운로드는 Downloads 로 떨어지는데 가이드는 Desktop 가정
ModuleNotFoundError: No module named 'google' — pip install 이 다른 Python 환경에 깔린 케이스
EPERM: process.cwd failed — macOS 의 "전체 디스크 접근 권한" 막힘

이걸 다 가이드 안에 "주의" 박스로 박을 수 있다. 실제로 INSTALL.md 분량이 두 배 늘었다. 모든 명령에 ✅정상 / ❌에러 표시가 붙고 silent success 가 정상이라는 안내가 들어가고 에러별 해결 표가 추가됐다.

그런데도 학생 한 명은 "아무 일도 안 일어났어요" 메시지를 두 번 보냈다. 그게 정상 동작이라는 걸 아무리 설명해도, 학생 입장에서는 검은 창에서 명령어를 치는 일 자체가 처음이고 두려운 일이다.

결론: 가이드를 더 잘 쓰는 것보다 가이드를 없애는 게 빠르다

오늘 만든 게 그거다. AgentClient.exe — 더블클릭 한 번으로 동작하는 단일 실행 파일.

스펙

파일: AgentClient.exe
크기: 60MB
의존성: 0 (Python, pip, 패키지 모두 .exe 안에 통합)
GUI: Tkinter (Python 기본 라이브러리)
빌드 도구: PyInstaller 6.20
대상 OS: Windows 10/11 (Mac 빌드 별도 진행)

학생 흐름 (이전 13단계 → 4단계)

AgentClient.exe 다운로드 → 더블클릭
창이 뜨면 Google AI Studio API 키 + 텔레그램 봇 토큰 두 개 입력
"🟢 시작" 클릭
텔레그램에서 본인 봇한테 /start

이게 전부다. Python 설치 없음. PowerShell 없음. ~ 없음. .txt 없음. cd 없음.

내부 구조

AgentClient.exe
├─ Python 3.13 인터프리터 (PyInstaller 가 통합)
├─ google-generativeai (Gemini API)
├─ python-telegram-bot (텔레그램 인터페이스)
├─ ddgs (DuckDuckGo 검색)
├─ requests + beautifulsoup4 (웹페이지 가져오기)
└─ client.py (Tkinter GUI + bot 로직 통합)

GUI 는 두 화면이다. 첫 실행에 키 입력 화면, 그 다음부터는 키가 ~/AppData/Roaming/AgentClient/config.json 에 저장돼서 바로 상태 화면으로 들어간다. 상태 화면에는 시작/정지 버튼과 실시간 로그 영역이 있다.

봇 로직은 별도 스레드에서 돌고, asyncio 이벤트 루프 + Telegram polling + Gemini Function Calling 자동 사이클이 그 안에서 작동한다. UI 스레드는 200ms 마다 큐에서 로그 메시지 꺼내 화면에 추가한다.

도구 5개는 그대로

list_files — 작업 폴더 목록
read_file / write_file — 텍스트 파일 R/W (path traversal 차단)
web_search — DuckDuckGo 5개 결과
fetch_url — 웹페이지 텍스트 추출

봇 자체의 능력은 어제 만든 CLI 버전과 동일하다. 바뀐 건 입구뿐이다.

오늘 빌드한 건 Windows .exe 만이고, Mac .app 은 GitHub Actions CI 로 자동 빌드 셋업할 예정. 아이콘 / 스플래시 / 시스템 트레이 / 자동 시작 등은 v1.1 이후로 미뤘다.

크몽 판매를 검토 중이다. 직접 경쟁자가 0건이고 (다운로드형 완성 텔레그램 AI 에이전트는 시장에 없음), 가까운 카테고리 (1:1 OpenClaw 셋업 서비스) 는 ₩55K~₩100K 에서 70-100건 리뷰가 쌓여있다. 우리 단가는 ₩29K~₩39K 정도가 적정 임계값이라는 게 시장조사 결론. 자세한 분석은 다음 일지로.

GitHub Releases: https://github.com/wildeconforce/agent-starter-kit/releases/tag/v1.0.0-beta

기술적으로 어렵지 않았던 이유

봇 로직 자체는 가벼워서 (메모리 50MB, CPU 거의 0%, 모든 LLM 추론은 Google 서버) 클라이언트화는 진짜 mechanical 작업이었다.

bot.py → Tkinter 안으로 통합: 1시간
PyInstaller spec 작성 + 빌드: 1시간
GUI 로드 + .exe 부팅 검증: 30분

문제는 늘 봇 로직이 아니라 봇 로직이 동작할 환경을 학생이 직접 차리도록 강요했던 것 이었다. 그 환경 차림 단계 (Python + pip + Terminal) 를 .exe 안에 통째로 넣으니 모든 학생 측 트랩이 사라진다.

가이드를 더 잘 쓰는 것보다, 가이드가 필요 없게 만드는 게 항상 빠르다.