디스코드가 일렉트론을 버리고 Rust 로 간다길래

디스코드가 데스크톱 앱을 Rust 로 다시 만든다는 소식을 봤다. UI 는 사람들이 예상하기로는 Tauri 였으나 GPUI 로 그린다고 한다. 공동 창업자이자 CTO 인 Stanislav Vishnevskiy 가 11월 초에 X 에 직접 올린 이야기라 소문은 아닌 것 같다 ( Windows Latest ). GPUI 는 Zed 에디터를 만든 팀이 쓰는 프레임워크다. 웹뷰를 띄우는 게 아니라 GPU 로 화면을 직접 그린다. 일렉트론은 앱마다 크롬을 하나씩 들고 다니는 구조라 메모리를 많이 먹는다는 얘기가 늘 따라다녔는데, 디스코드는 그 구조 자체를 내려놓기로 한 것 같다. 모바일도 같이 바뀐다고 한다. React Native 를 빼고, 화면은 각 플랫폼 네이티브로 두되 그 아래 코드는 Rust 로 데스크톱과 공유한다는 이야기다. 나는 메모리 숫자보다 이쪽이 더 눈에 들어왔다. 메모리 얘기도 돈다. 테스트 빌드가 300MB 조금 안 되게 쓴다는 스크린샷이다. 근데 출시 전 빌드 화면 한 장이고 출시일도 없어서, 그냥 그런 게 있구나 하고 보고 있다. 왜 C++ 에서 Rust 로 옮겼나 나도 C++ 로 짜던 코드를 Rust 로 옮겼다. 회사 일이라 자세히 쓰기는 어렵고, 이유만 적어 둔다. 한 번에 옮긴 건 아니다. 4년 전에는 일부 모듈만 Rust 로 바꿨고, 작년에 코어 로직 전부를 Rust 로 옮겼다. 지금 일렉트론은 UI 만 맡고 있다. 개인적으로 만드는 앱도 코어 로직은 전부 Rust 로 짠다. git 클라이언트인 git403 은 Tauri 로 만들었고, 데스크톱과 안드로이드를 같이 지원한다. vmdeck 은 애플 실리콘 맥 전용 가상화 앱이다. Parallels, VMware, UTM 을 대신하려고 만들었고, 회사에서도 라이선스 걱정 없이 쓰고 싶었다. 인텔 맥이나 윈도우용도 생각은 해 봤다. 그런데 윈도우는 이미 무료로 쓸 만한 앱이 많고, 인텔 맥은 단종돼서 아직은 손이 안 간다. 고민이 하나 있다. vmdeck 안에 윈도우를 설치해서 쓰...

게임 레포 규칙 문서 250KB를 MCP 서버로 자르기

규칙은 다섯 줄에서 시작했다. 안내판이 빈 판으로 보인 사고가 나서 한 줄이 늘었다. 점프가 영구히 잠긴 사고에 또 한 줄, 이펙트가 자기 히트박스에 걸린 사고에 또 한 줄. 다 원인을 찾아서 적어뒀고 같은 사고는 두 번 안 났다. 그렇게 아들과 만드는 로블록스 게임 레포의 CLAUDE.md 가 10KB를 넘었다.

새 세션을 열면 에이전트가 그 10KB를 읽고 시작한다. 그날 작업에 필요한 규칙은 그중 두 줄이다. 나머지 문서까지 합치면 250KB인데 그건 아예 안 읽는다. 안 읽은 문서에 그날 필요한 줄이 있으면 사고가 다시 난다.

밝은 책상에 두꺼운 바인더가 높이 쌓여 있고 그 옆에 색인 카드 한 장만 뽑혀 나와 있는 장면

그날 나는 GitHub 트렌딩을 보고 있었다. obra/superpowers 는 스킬을 배포 가능한 패키지로 떼어냈고, TencentCloud/TencentDB-Agent-Memory 는 개인 파일에 있던 기억을 팀 공유 자산으로 올렸고, huangruiteng/loopx 는 루프 상태를 커널로 만들었다. 묶어 보면 작년까지 각자 CLAUDE.md 에 손으로 적던 것을 레이어로 뜯어내는 작업들이었다.

내 문제도 그 목록에 들어가는 종류였다. 규칙과 문서를 한 파일에 쌓는 대신, 물어보면 답하는 서버로 떼어내면 된다. 붙이는 규격은 MCP다.

다른 프로젝트에서 같은 문제를 그렇게 푼 걸 본 적이 있었다. 프로젝트 문서를 MCP 도구로 노출하고, 도구 설명에 "작업 시작 전 반드시 호출"을 넣은 서버였다. 도구 여섯 개가 도메인별로 문서를 맡고, 키워드로 순위를 매겨 상위 몇 개만 돌려준다. 그 형태만 게임 레포에 옮겼다. 코드를 가져온 건 아니다. 도메인 이름도 문서 이름도 전부 달라서 옮길 것이 애초에 없었다.

참고한 저장소는 마크다운 파일이 백 개 넘게 있고 파일 하나는 8KB 안팎이었다. 내 게임 레포는 14개에 250KB 라 파일 하나가 두 배 넘게 두껍다.

참고한 서버는 파일 단위로 상위 8개를 돌려준다. 그 저장소에선 그게 전체의 몇 %라 잘 걸러진다. 근데 게임 레포에 쓰면 14개 중 8개, 150KB 넘게 돌아온다. 그냥 아무것도 안 걸러진다.

그래서 단위를 바꿨다. 파일이 아니라 heading으로 쪼갠 섹션을 검색 단위로 삼고, 개수 상한 대신 바이트 예산으로 자른다. 조각마다 원본 경로랑 줄 번호를 붙여 인덱스를 만들었다. 도구 대부분은 섹션이 수십 개씩 나왔는데, CLAUDE.md 를 맡은 get_rules 만 섹션이 여섯 개뿐이었다. 이게 나중에 문제가 된다.

나누다 보니 문서 14개 중 13개만 도구에 배정돼 있었다. 아이콘·썸네일 프롬프트 문서 하나가 어느 도구에도 안 붙어서 절대 안 나오는 문서였다. 손으로 나누면 이런 게 조용히 생긴다. 배정 안 된 문서를 세는 확인을 따로 돌리고, 그 문서는 배포 도구에 붙였다. 스토어에 올리는 이미지 얘기니까 배포 작업 중에 필요하다.

구현

구현은 셋 중에 하나였다. 참고한 저장소처럼 TypeScript에 공식 SDK를 붙이거나, Python에 MCP 패키지를 붙이거나, 프로토콜을 직접 구현하거나.

이 레포의 tools/ 는 이미 순수 python3 스크립트 다섯 개다. 이 게임에는 "에셋 의존 0"이라는 규칙이 있고 도구들도 같은 원칙으로 유지돼 있었다. npm install 이나 pip install 을 요구하는 파일을 하나 넣으면 그 규칙이 깨진다. 그래서 프로토콜을 직접 구현했다. 명세가 단순해져서 손으로 짤 만하다는 얘기가 맞는지 궁금하기도 했다.

해 보니 맞았다. stdio로 도는 MCP 서버가 처리해야 하는 건 initialize, tools/list, tools/call 세 개다. 여기에 알림을 무시하는 처리와 ping 응답을 더하면 끝이다. 표준 입력에서 한 줄씩 읽고 표준 출력에 한 줄씩 쓴다. 세션도 재연결도 상태 저장도 없다.

server.py 가 600줄쯤, 테스트가 100줄쯤이고 import는 전부 표준 라이브러리다. 참고한 TypeScript 서버랑 줄 수는 비슷하고 의존성만 없어졌다. initialize 에서 프로토콜 버전은 협상하지 않고 클라이언트가 보낸 값을 그대로 돌려준다. 로컬 도구라 그냥 넘어갔는데, 여러 클라이언트에 배포할 서버라면 이렇게 두면 안 될 것 같다.

내가 보기에 이 패턴에서 검색 알고리즘보다 중요한 건 도구 설명 문구다.

"get_rules": "코드를 쓰기 전 반드시 호출. 절대 규칙 10개·구조 원칙·
              재발견 비용이 큰 기술 사실을 우선순위로 반환한다."

에이전트는 도구 목록을 보고 언제 무엇을 부를지 스스로 정한다. CLAUDE.md 에 "규칙을 지켜라"라고 쓰는 것과 다른 건 지시가 호출 가능한 행동에 붙어 있다는 거다. 문서에 적힌 당부는 컨텍스트 안에서 다른 만 줄과 경쟁하지만, 도구 설명은 도구를 고르는 순간에 읽는다. 강제는 아니다. 안 부르고 코드를 쓸 수도 있다. 진짜 강제는 훅이 할 일이다. 이 게임 레포에는 이미 check_refs.py 가 교차 참조 15종을 검사하고, 그건 모델이 뭐라고 주장해도 안 바뀌는 사실 검사다. 문서를 읽었는지 여부는 그런 종류의 사실이 아니라서 같은 방식으로 못 막는다.

grep으로 하면 되지 않나 싶어서 질문을 문장 그대로 grep해봤는데 다섯 개 다 0건이었다. 단어로 자르면 찾긴 한다. "빈 판" 으로 grep하면 정확히 원하는 줄이 나오는데, 규칙을 적을 때 증상을 아이 말로 적어놨기 때문이다. 그건 운이다. grep은 검색어를 이미 알고 있을 때 쓸모가 있다. 몰라서 물어보는 상황에서는 그 단어를 못 고른다. 문서에 SurfaceGui.Face 로만 적혀 있었으면 0건이었을 거다.

grep은 돌려주는 단위도 파일이다. 찾아도 그 파일을 통째로 읽어야 한다. 도구는 heading으로 잘린 조각이랑 줄 번호를 준다. "포즈가 애니메이터에 덮인다"는 4KB쯤 되는 조각 몇 개로 오는데, 학습노트 전체는 13KB다.

검색어를 모르는 문제를 메우려고 동의어 사전을 뒀다. "포즈" 를 물으면 poses·Motor6D·Transform·PreSimulation·Rig 까지 같은 뜻으로 놓고 찾는다. 이 프로젝트에서 어떤 말이 어떤 말과 같은지는 내가 알아서 표로 적을 수 있는 부분이다. 범용 검색이 대신해줄 수 없는 부분이 여기다.

참고한 저장소는 이름이 검색어랑 맞으면 점수를 크게 주고, 본문에 나온 횟수는 조금씩 준다. 섹션 단위로 옮기면서 그 비율은 그대로 뒀다. 이 레포의 섹션은 큰 게 몇 KB씩 되는데, 본문 등장 횟수로만 매기면 긴 섹션이 늘 이긴다. 어떤 단어든 긴 글에 더 많이 나온다. heading은 그 조각이 무엇에 관한 것인지 사람이 직접 붙여둔 라벨이다. 「확률 · 천장」이라는 heading은 그 섹션이 확률 얘기라는 걸 쓴 사람이 보증한 것이고, 본문에 "확률"이 40번 나오는 것보다 강한 증거다.

그 덕에 잡힌 케이스가 있다. "뽑기 확률 합"은 「4. 확률 · 천장」이 아니라 「2.1 확률 합이 119.001% 였다」를 1위로 물어온다. 확률 합이 119%였다는 건 실제로 났던 사고고, 합을 물어보는 사람이 봐야 하는 건 그 사고 기록이다.

마크다운 코드 블록 안에도 # 으로 시작하는 줄이 있다. 셸 주석이다. 그걸 heading으로 잡으면 섹션이 코드 블록 중간에서 잘린다. 이 레포에도 그런 줄이 두어 개 있었다. 하나만 있어도 그 섹션은 깨지는데 검색은 여전히 뭔가를 돌려주니까 알아차릴 방법이 없다. 그래서 파서가 지금 코드 펜스 안에 있는지를 기억하게 했다.

서버는 문서를 매 호출마다 다시 읽지 않는다. 250KB를 호출마다 파싱하면 응답이 느려진다. 파일별 수정 시각을 기억해 바뀐 것만 다시 읽는다. 문서를 고치는 중에 서버를 재시작하지 않아도 되는 게 실제 이득이었다. 규칙을 한 줄 추가하고 서버 재시작 없이 바로 물어보면 그 줄이 나온다.

테스트

랭킹 로직은 조용히 틀린다. 동의어 하나를 지우면 특정 질문이 엉뚱한 문서로 가는데, 그건 에이전트가 잘못된 코드를 쓴 뒤에야 알 수 있다. 그래서 실제로 나왔던 질문을 회귀 케이스로 넣었다. 아이가 말한 표현 그대로다.

"안내판이 빈 판으로 보인다", "점프가 안 된다", "넉백이 덜컹거린다", "뽑기 확률 합", "포즈가 애니메이터에 덮인다".

각 질문이 기대한 섹션을 상위 3개 안에 물어오는지 본다. 첫 실행은 11/12였다.

[FAIL] get_engine_notes :: "포즈가 애니메이터에 덮인다"
         실제 상위 3: []

0건이다. 원인은 한국어 조사였다. 공백으로만 쪼개니까 "포즈가" 가 하나의 토큰이 되고, 동의어 표에 있는 건 "포즈" 다. "애니메이터에" 도 같다. 세 토큰 전부 아무 그룹에도 안 맞았다.

이게 참고한 저장소에서 나타나지 않았던 이유가 재밌다. 그 저장소의 회귀 케이스에도 한국어가 있는데 "포커스 업데이트" 처럼 조사 없는 명사뿐이었다. 결함은 원본에도 있었고 질문의 말투가 달라지자 나타났다. 사내 문서를 검색하는 개발자는 키워드를 던지고, 게임 만드는 초등학생은 문장으로 말한다.

형태소 분석기는 의존성 때문에 뺐고, 조사 목록을 두고 어미를 규칙으로 떼냈다.

KOREAN_PARTICLES = (
    "에서는", "으로는", "이라고", "에서도", ...
    "은", "는", "이", "가", "을", "를", "에", "의", "도", "만", ...
)

조사가 안 떨어지면 끝 글자를 하나 잘라본다. "덮인다" 는 "덮인", "덮" 으로 줄여서 문서의 "덮어쓴다" 에 닿게 한다. 거친 방법이지만 heading 점수가 순위를 잡아 줘서 그럭저럭 맞는다.

고친 뒤 12/12가 됐다. 그 질문은 학습노트의 「애니메이션: 에셋 업로드 없이 하는 법」을 물어온다. Motor6D.Transform 이 Animator에게 매 프레임 덮이니까 RunService.PreSimulation 에서 써야 이긴다는 내용인데, 애초에 그 사고를 겪고 적어둔 줄이다.

질문마다 얼마나 줄여서 돌려주는지 재 봤다. 게임 공개가 막혀 있다는 질문, 뽑기 확률 합, 포즈 질문은 다 대략 80% 넘게 줄었다. 배포 도구는 83KB에서 12KB만 오고, 그 12KB에 「오디언스 도달」 섹션이 들어 있다. 공개가 막힌 이유를 여기서 찾게 된다.

근데 점프가 안 된다는 질문이랑 커밋 전에 뭘 돌려야 하냐는 질문은 20%도 잘 안 줄었다. 둘 다 get_rules 로 간 질문이다. 섹션이 여섯 개뿐이라 조각 하나가 크고, 「절대 깨면 안 되는 규칙」 섹션은 항상 붙게 해 놨다. 그래서 원본을 거의 다 돌려준다. 자를 게 없는 문서에 검색을 붙이면 이런 숫자가 나온다.

"코드 쓰기 전 반드시 호출"이 붙은 도구가 하필 그 도구다. 제일 자주 부를 도구에서 줄어드는 양이 제일 적다. 나는 이걸 랭킹을 손봐서 될 일이 아니라 문서를 쪼개야 하는 문제로 본다. 절대 규칙 10개를 항목별로 쪼개면 "이펙트가 히트박스에 걸린다"에 4번 규칙만 줄 수 있는데, 아직 안 했다. 쪼개면 사람이 읽을 때 흐름이 끊기고, 그 손해가 이득보다 큰지 아직 모르겠다. 몇 주 써보고 정할 생각이다.

이 서버는 검색만 한다. 틀린 문서를 잘 찾아주면 틀린 답이 더 빨리 온다. 250KB 중에 낡은 줄이 몇 개인지 나는 모른다. 이 작업을 시작할 때 내 세션 메모에는 게임 레포 경로가 예전 위치로 적혀 있었고 코드 규모도 "38파일 19,315줄"로 남아 있었다. 세어보니 42파일 24,706줄이었다. 검색을 잘 붙여도 문서는 이렇게 조용히 낡는다.

트렌딩 목록 보고 시작한 일인데, 결과물은 남의 프레임워크가 아니라 파이썬 파일 하나였다. 흐름에서 가져온 건 문서를 따로 떼어내라는 방향이었고, 그 방향이 이 레포에 맞는지는 옮겨보고 나서야 알았다. 문서 개수와 크기의 분포가 달라서 검색 단위를 파일에서 섹션으로 바꿔야 했고, 질문의 말투가 달라서 조사 처리를 넣어야 했다. 둘 다 붙여보기 전에는 안 보였다.

이 게임은 만들라고 하기 전에 공부부터 시키면서 시작했다. 그때 에이전트가 만든 학습 문서 네 개가 지금 250KB의 시작이었다. 공부를 시켜서 문서를 얻었고, 문서가 쌓여서 아무도 안 읽게 됐고, 그래서 찾아 읽게 해 주는 서버를 하나 더 놨다.

댓글

이 블로그의 인기 게시물

아이들은 우리 게임에 들어오지 못한다

AI 부업 강의 여섯 편이 "리스크가 제로죠"라고 말했다

AI가 썼다는 브라우저 300만 줄에서 112만 줄은 남의 코드였다