AI만 읽는 문서, 한국어로 써야 할까

개요

웨이브웍스는 모바일 게임과 앱을 만드는 회사이고, 개발은 AI 코딩 도구 Claude Code로 진행합니다. 규칙 파일과 설계서, 인계 문서는 Claude가 세션마다 읽고 사람은 직접 열지 않는데도 전부 한국어로 써 왔기 때문에, 같은 내용을 영어로 썼을 때보다 토큰을 더 쓰고 있었습니다. 그래서 이틀에 걸쳐 사람이 읽는 글만 빼고 Claude가 읽는 문서는 영어로 쓰는 것을 기본으로 바꿨습니다. 바꾼 문서 174개를 변환 전후로 재니 토큰이 약 31% 줄었지만 짧은 설계서는 오히려 늘어나, 변환 범위를 다시 조정했습니다.

사람이 열지 않는 문서

저희가 Claude Code로 개발할 때 Claude는 세션을 열 때마다 전역 규칙 파일과 프로젝트 규칙을 읽고, 작업에 따라 설계서와 계획서, 인계 문서를 더 읽습니다. 저희는 그 문서를 직접 열어 보는 일이 거의 없고, 내용이 궁금하면 Claude에게 요약을 시키거나 HTML 보고서로 받아 확인합니다. 그런데 문서는 전부 한국어로 쓰여 있었고, 세션 여러 개와 프로젝트 여러 개가 같은 문서를 매번 읽으니 한국어가 영어보다 토큰을 많이 쓴다면 그 차이가 세션마다 쌓이는 구조였습니다.

얼마나 차이가 나는지 먼저 재 봤습니다. 전역 규칙 파일 3개를 영어로 바꾸고 토큰 수를 세니 1,175에서 582로 약 0.50배가 됐습니다. 측정에는 tiktoken의 cl100k_base를 썼는데, Claude의 토크나이저와 같지 않아서 대리 지표로만 봅니다. 세션마다 항상 로드되는 분량이 약 25.8K토큰이어서 같은 비율이면 약 10K토큰, 39% 정도가 줄 것으로 처음에는 추정했습니다. 변환을 마친 뒤 이 추정을 실측으로 확인한 결과는 뒤의 「개선된 부분」에 있습니다.

처음 계산은 틀렸습니다. 첫 보고서에는 바이트 기준으로 77KB가 줄어든다고 적었는데, 한글이 글자당 3바이트라서 바이트 수가 절감을 부풀린 것이었고 실제로 바꾼 뒤 바이트는 1~3%만 줄었습니다. 비용은 토큰으로 드니 이 수치를 지우고 토큰 기준으로 보고서를 정정했습니다.

경로 목록에서 기본 원칙으로

처음에는 영어로 쓸 문서의 경로를 목록으로 정했고, 이미 있는 한국어 문서는 일괄 번역하지 않기로 했습니다. 한 번 번역하는 데 드는 비용, 한국어로 검색하던 것이 깨지는 문제, 번역하면서 의미가 바뀔 위험 때문이었습니다. 그런데 목록에 없는 문서를 어느 언어로 써야 하는지가 매번 모호했고, 앱 5곳에는 목록 밖의 한국어 문서가 수백 개 남아 있었습니다.

그래서 저희는 원칙을 뒤집어, 사람이 읽는 글을 빼고 기본은 영어로 하되 한국어로 남길지는 질문 3개로 판정하기로 정했습니다.

• 사용자가 읽거나 확인·승인하는 문서인가. 콘솔 설명, 요청한 요약, HTML 보고서, 결정 기록이 여기 들어갑니다.
• 운영상 한국어가 분명히 유리한가. 훅이 검사하는 문구, 스킬을 부르는 문구, 사용자 발언 인용이 그렇습니다.
• 영어로 바꾸면 깨지는가. 프로그램이 읽는 표, 대시보드가 읽는 제목, 코드가 인용하는 문자열이 해당합니다.

하나라도 “예”면 한국어로 두고, 파일 일부만 해당하면 그 부분만 한국어로 남깁니다. 예외는 한 파일에 모아 두고 프로젝트별로 덧붙일 수 있게 했습니다.

영어로 바꾸면 깨지는 것

다른 문서와 스킬이 한국어 절 제목으로 인용하는 곳이 먼저 깨졌습니다. 제목을 영어로 바꾸면 그 제목을 가리키던 인용이 끊어지기 때문에, 바꾸기 전에 저장소 전체에서 그 제목을 검색하고 새로 적는 인용은 “영어 (한국어)” 형태로 두 표기를 함께 씁니다.

코드가 읽는 한국어도 있었습니다. 표의 “양쪽/한쪽” 값을 프로그램이 그대로 파싱하고, 새 앱 생성기는 템플릿 안의 한국어 자리표시자를 찾아 앱 이름으로 치환하고, 대시보드는 문서의 상태값을 읽어 표시합니다. 이런 문자열은 번역하면 프로그램이 찾지 못하므로 코드와 함께 고치거나 그대로 둡니다.

훅이 검사하는 한국어 문구는 번역 자체를 막았습니다. 실제로 번역 에이전트가 템플릿의 자리표시자를 영어로 바꿔 버려 원문으로 되돌린 일이 있었고, 그 뒤로 훅이 검사하는 문구와 자리표시자는 번역 대상에서 뺍니다.

한국어로 검색되게 하기

영어로 바꾼 문서를 나중에 한국어로 찾을 수 있는지가 걱정이었습니다. 저희가 Claude에게 한국어로 묻기 때문입니다. 변환한 문서 4개를 두고 사용자가 칠 법한 한국어 질의 18개를 만들어 검색하니 12개는 찾았고 6개는 실패했는데, 실패한 6개는 모두 같은 개념을 다른 철자로 쓴 경우였습니다. 문서에는 “절 단위 편집”이라고 적혀 있는데 “절 편집”으로 검색한 식입니다. 반대로 작업 이름, 영어 용어, 키워드 줄에 적어 둔 정확한 문구는 항상 찾았습니다.

그래서 영어 문서 첫 줄에 한국어 키워드 줄을 두고 개념마다 표기를 2~3개씩 적는 규칙을 더했습니다. 같은 방식으로 다른 문서를 대상으로 2차 시험을 하니 질의 16개 중 12개가 적중했고, 남은 4개는 문서에 원래 없던 용어를 물은 것이어서 키워드로 해결할 문제가 아니었습니다. 대시보드에서는 문서가 한국어로 보여야 하므로 문서마다 10줄 이내의 “한국어 요약” 절도 두었는데, 이 요약은 콘솔에서 저희가 승인한 설명과 같은 내용입니다.

번역은 스킬로, 검증은 따로

기존 문서를 바꾸는 일은 english-convert라는 스킬로 만들어 Claude가 매번 같은 절차로 하게 했습니다. 먼저 문서를 한국어 비율과 크기, 다른 곳에서 인용되는지로 등급을 나눕니다. 자주 읽히는 문서, 열린 작업에 연결된 문서, 코드가 경로를 인용해 확인이 필요한 문서, 고칠 때 변환할 문서, 예외 문서, 이미 영어인 문서의 여섯 등급입니다. 그다음은 범위 승인, 백업, 문서별 지시서, 번역, 검증, 묶음마다 독립 검토 1회, 전후 비교 순서로 진행합니다.

검증 도구는 숫자와 ID, 경로가 빠졌는지와 한국어 비율이 남았는지만 확인합니다. 한국어 비율이 낮아졌다고 의미가 보존된 것은 아니어서 의미는 검토 단계가 맡는데, 검토 단계가 실제로 오역을 잡았습니다. “매주 월요일 09:30”이 monthly로 옮겨졌고, 번호가 작은 단계를 가리키는 “뒤 단계”는 later stage로 방향이 반대가 됐습니다. “게임 이름의 글자 하나”는 “한 글자”로만 옮겨져 무엇의 글자인지 빠졌습니다.

마크다운 문서를 쓰거나 고칠 때 예외 목록 밖의 문서에 한국어 비율이 높으면 알려 주는 경고 훅도 더했는데, 작업을 막지는 않고 파일마다 세션에 한 번만 알립니다.

개선된 부분

변환이 끝난 뒤 원래 한국어였고 지금 영어인 마크다운 문서 174개를 골라, 변환 직전 버전과 현재 버전을 같은 파일끼리 비교해 토큰을 셌습니다. 측정 방식은 앞과 같은 tiktoken의 cl100k_base로, 대리 지표입니다.

합계로는 836,544토큰이 578,705토큰이 되어 257,839토큰, 약 31%가 줄었고, 같은 문서를 읽을 때 드는 토큰이 약 3분의 1 줄었다고 보면 됩니다. 이 차이는 한 번 읽을 때의 값이고, 세션마다 그리고 프로젝트마다 같은 문서를 되풀이해 읽을 때 그만큼씩 쌓이는데, 세션 수와 읽는 횟수는 재지 않아서 실제 절감 비용은 측정 전입니다. 매 세션 읽는 전역 12개만 보면 18,138토큰이 11,580토큰이 되어 세션을 열 때마다 약 6.6K토큰을 덜 읽습니다. 프로젝트 지침 등은 이 12개에 포함하지 않았습니다. 앞의 규칙 파일 3개 0.50배는 가장 크게 준 사례이고, 전체 평균은 0.69배입니다. 전역 규칙 중 글쓰기 규칙 하나는 원칙 설명이 늘어 토큰이 1,625에서 1,677로 소폭 늘었습니다.

바이트로는 반대로 늘었습니다. 174개 합계가 2,101,221바이트에서 2,185,228바이트로 4% 늘었습니다. 한글은 글자당 3바이트여서 영어로 바꾸면 글자 수가 늘어도 바이트는 비슷하고, 거기에 키워드 줄과 한국어 요약이 더해졌기 때문입니다. 그래서 파일 크기로는 절감이 보이지 않고 토큰으로만 보입니다.

오히려 늘어나는 경우

모든 문서가 줄어든 것은 아닙니다. 설계서 표본 3건은 키워드 줄과 한국어 요약이 더해져 토큰 추정이 늘었습니다.

이 수치는 토크나이저 없이 한국어 글자당 1.2토큰 같은 휴리스틱으로 계산한 추정입니다. 그래서 큰 절감은 길고 자주 읽히는 문서에서 나오는 것으로 보고, 끝난 작업의 계획서와 설계서처럼 읽히지 않는 문서는 변환하지 않거나 뒤로 미루기로 했습니다.

결론

변환한 범위는 전역 규칙과 출력 스타일, 전역 지침, 루트 문서 9개, 스킬 40개, 새 앱 템플릿 9개, 메모리 26개, 앱 5곳의 자주 읽는 문서입니다. 이 개수는 규모를 보여 주는 것이고, 측정된 효과는 문서 174개의 토큰이 대리 지표로 31% 줄었다는 것입니다. 이 문서들이 세션마다 실제로 몇 번 읽히는지, 그래서 세션당 비용이 얼마나 줄었는지, 에이전트의 작업 정확도가 달라졌는지, 메모리를 불러오는 품질이 유지되는지는 아직 재지 않았습니다.

남은 한계도 있습니다. 일부 스킬은 호출 시험을 하지 않았고 새 앱 생성을 끝까지 실행해 보지 않았으며, 고칠 때 변환하기로 한 문서는 그대로 한국어입니다. 모국어로 써도 에이전트 정확도가 떨어지지 않는다는 글들도 있는데, 저희가 바꾼 기준은 토큰과 상시 로드량이었고 정확도 비교는 측정 전입니다.

같은 방식을 쓰려는 분이라면 세션마다 항상 로드되는 파일의 크기를 먼저 재서 토큰이 어디서 나가는지 확인하고, 어느 문서를 한국어로 남길지 판정하는 질문을 번역 전에 정해 두는 것이 순서상 먼저입니다. 문서 하나를 바꾸기 전에는 그 제목을 다른 문서가 인용하는지 검색하고, 바꾼 뒤에는 실제로 칠 법한 한국어 질의로 검색이 되는지 몇 개라도 돌려 보면, 저희가 뒤늦게 고친 두 가지를 앞당길 수 있습니다.

다음에 할 일은 경고 훅의 로그를 한 주 모아 기준을 조정하고, 시험하지 않은 스킬 호출을 확인하는 것입니다.