Claude Code의 실제 코드 검색 토큰 절감 측정

이 요약은 AI가 원문을 분석해 생성했습니다. 정확한 내용은 원문 기준으로 확인하세요.

TL;DR

작성자는 약 164k-token 규모의 Roblox 게임을 Claude Code로 개발하면서 tree-sitter 기반 MCP가 전체 파일 대신 필요한 AST 조각만 반환하도록 구성했습니다. 188회의 신뢰성 있는 호출에서 비교 대상 파일 전체 읽기보다 2,120,451 tokens를 절감해 약 93% 감소를 기록했고, 저장소 전체와 직접 비교하면 약 99%였습니다. 다만 Luau를 사용한 단일 게임의 n=1 사례이며 초기 로그 일부가 유실됐고, 정액제에서는 비용보다 토큰 한도 관리에 효과가 있습니다. MCP 플러그인과 실제 게임 저장소를 Apache-2.0으로 공개해 사용량 과금 환경에서 재현 가능한 측정을 가능하게 했습니다.

실용적 조언

토큰 절감률을 측정할 때는 저장소 전체 크기보다 각 검색 조각이 나온 파일 전체를 에이전트가 읽었을 상황을 기준선으로 삼는 편이 적절합니다. 호출마다 반환 조각의 토큰 수와 비교 대상 파일의 토큰 수를 함께 기록해야 합니다. 저장소 전체와 비교한 수치는 별도의 참고값으로 분리해야 실제 사용 조건과 혼동하지 않습니다.
코드 검색 도구는 생성 단계보다 통합과 리팩터링 단계에서 더 큰 효과를 낼 가능성이 있습니다. 함수나 심볼 단위로 질의할 수 있는 retrieve_code와 explain_symbol 같은 인터페이스를 제공하면 에이전트가 전체 파일을 반복해서 읽는 대신 필요한 AST 조각만 받을 수 있습니다. 로그 손실을 막기 위해 초기부터 호출 기록의 정상 동작을 확인하고, 누락된 구간은 전체 결과와 분리해 보고해야 합니다.

섹션별 상세

작성자는 synthetic benchmark의 토큰 절감 수치 대신 실제 Roblox 게임 개발에서 얻은 측정값을 제시했습니다. 약 52개 파일과 약 164k tokens 규모의 게임을 Claude Code로 만들고, tree-sitter 기반 MCP가 질의에 맞는 AST 조각만 반환하도록 구성했습니다. retrieve_code(query)와 explain_symbol(name) 두 도구의 호출 기록을 남겨 반환한 조각의 토큰 수와 해당 파일 전체를 읽었을 때의 토큰 수를 비교했습니다.

신뢰성 있게 기록된 188회 retrieve 호출에서 전체 파일을 읽는 방식보다 2,120,451 tokens를 아꼈고, 절감률은 약 93%였습니다. 164k-token 저장소 전체를 직접 비교하면 일반적인 조각이 약 1k tokens라서 약 99%까지 줄었지만, 작성자는 이 수치를 실제 호출의 기준으로 사용하지 않았습니다. 각 조각이 나온 파일만 에이전트가 실제로 열었을 상황을 기준으로 삼아 과장된 저장소 전체 비교와 구분했습니다.

절감 효과는 개발 단계에 따라 달라졌습니다. 생성 작업이 많은 단계에서는 코드 검색 호출이 적어 토큰 절감이 거의 나타나지 않았고, 통합과 리팩터링 단계에서는 관련 심볼과 코드 조각을 찾아 읽는 호출이 많아 효과가 커졌습니다. 초기 두 단계의 로그는 버그로 유실됐으므로 188회는 신뢰할 수 있게 기록된 하한이며, 실제 전체 호출 수는 더 많았습니다.

작성자는 결과가 Luau를 사용한 단일 게임과 단일 개발 사례라는 점을 명시해 n=1의 한계를 인정했습니다. Claude Code의 정액제에서는 토큰 비용 자체가 줄지 않고 주간 토큰 한도에 늦게 도달하는 효과가 생깁니다. 반면 사용량 과금 API나 Codex의 토큰 가격 체계에서는 줄어든 입력 토큰이 실제 비용 절감으로 연결될 수 있습니다.

구현은 특정 공급자에 종속되지 않도록 Apache-2.0 라이선스로 공개됐고, MCP 플러그인과 base_url을 바꾸는 proxy, 일반 library 형태로 사용할 수 있습니다. extractor는 Luau를 포함한 13개 언어를 지원하며, 작성자는 스크린샷이 아닌 실제 게임 저장소도 공개해 수치를 재현할 수 있게 했습니다. 따라서 핵심 기여는 토큰 절감률 자체뿐 아니라 호출 로그와 코드 저장소를 함께 둔 측정 방법에 있습니다.

용어 해설

모델 컨텍스트 프로토콜(MCP): — MCP는 AI 에이전트가 외부 도구와 데이터에 정해진 인터페이스로 접근하게 하는 연결 규격입니다. 이 글에서는 코드 검색 도구를 Claude Code와 Codex에 연결하는 통로로 쓰였습니다.
추상 구문 트리(Abstract Syntax Tree): — Abstract Syntax Tree는 소스 코드를 함수·변수·클래스 같은 구조 단위로 표현한 트리입니다. 이 구조를 이용하면 파일 전체가 아니라 질의와 관련된 코드 조각만 찾아 에이전트에 전달할 수 있습니다.
tree-sitter 구문 분석기(tree-sitter): — tree-sitter는 여러 프로그래밍 언어의 소스 코드를 구문 트리로 변환하는 파서 라이브러리입니다. 글의 MCP는 이를 사용해 13개 언어에서 함수나 심볼 단위의 AST 조각을 추출합니다.
토큰 할당량(Token Quota): — Token Quota는 모델 호출에 사용할 수 있도록 서비스가 정해 둔 토큰 사용 한도입니다. 이 사례에서는 파일 전체를 반복해서 읽는 대신 필요한 조각만 전달해 Claude Code의 주간 한도에 늦게 도달하게 합니다.
사용량 과금 API(Metered API): — Metered API는 호출한 토큰 수나 처리량에 따라 비용을 계산하는 API입니다. 글의 방식은 정액제 Claude Code에서는 비용보다 한도 관리에 효과가 있고, 사용량 과금 환경에서 실제 금액 절감으로 이어집니다.

언급된 도구

Claude Code중립

코드 생성과 Roblox 게임 전체 개발에 사용한 coding agent입니다.

MCP중립

에이전트가 retrieve_code(query)와 explain_symbol(name) 도구를 호출하도록 연결한 인터페이스입니다.

tree-sitter중립

소스 코드에서 질의에 맞는 AST 조각을 추출하는 데 사용한 parser library입니다.

Codex중립

동일한 MCP 플러그인과 토큰 가격 체계를 적용할 수 있는 coding agent로 언급됐습니다.