Claude Code, Cursor, Codex 등의 AI 코딩 에이전트를 사용할 때, **"어떤 파일을 읽어야 하는가"**를 탐색하는 과정에서 토큰을 대량으로 소비하고 있지는 않은가? 나 또한 개인 사업인 "코바야시 WEB 시스템"으로서 제조업 DX(Digital Transformation) 프로젝트에 참여하고 있으며, 기간 시스템 개수 시 수천 개의 파일이 포함된 리포지토리(Repository)를 AI가 탐색하도록 하고 있다.

이 "탐색 비용"을 절감하는 도구가 바로 CodeGraph다. 본 기사에서는 도입 방법과 효과를 공유한다.

AI 에이전트의 "탐색"이라는 약점

AI 에이전트는 코드 구조를 파악하기 위해 grep, glob, Read를 반복한다. 파일 단위(file-by-file)의 탐색은 대규모 리포지토리일수록 토큰 소비와 레이턴시(Latency)를 비대화시킨다.

내가 담당했던 기간 시스템 교체 PJ(Project)에서는 수주·생산·청구 시스템이 수백 개의 파일에 산재해 있었다. AI에게 "청구 플로우를 따라가 줘"라고 의뢰하면, 끝없이 파일을 읽으며 동일한 구조를 몇 번이고 스캔한다. 단 1회의 질문으로 수만~10만 토큰을 소비하는 케이스도 있었다.

CodeGraph로 지식 그래프를 로컬 구축

CodeGraph는 tree-sitter를 사용하여 소스 코드를 AST(Abstract Syntax Tree)로 분해하고, 심볼 관계 및 호출 그래프를 로컬 SQLite에 저장한다. 주요 특징:

• 토큰 16% 절감, 도구 호출 58% 절감 (7개 리포지토리 벤치마크 결과)
• 로컬 완결형: API 키 불필요, 데이터 외부 유출 없음
• 자동 동기화: 파일 감시를 통해 2초 후 인덱스 자동 업데이트
• 20개 이상의 언어 지원: TypeScript, Python, Go, Rust, Java 등 Claude Code / Cursor / Codex / Hermes Agent 통합

도입은 원라이너(One-liner), 프로젝트 초기화도 명령어 하나로

Node.js가 필요 없으며, curl/PowerShell 한 번으로 도입할 수 있다:

curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh
codegraph install --yes --target=claude,hermes

각 프로젝트에서는 다음을 실행하기만 하면 된다:

cd /opt/data/projects/client-system
codegraph init

.codegraph/가 생성되며, auto-sync가 활성화된다.

벤치마크: 에이전트가 어떻게 빨라졌는가

Claude Opus 4.8 (headless)로 7개의 실제 리포지토리를 테스트한 결과, 평균적으로 토큰 47% 절감, 도구 호출 58% 절감, 22% 속도 향상을 기록했다.

리포지토리	언어	비용 절감	토큰 절감	속도 향상	도구 호출 절감
VS Code	TypeScript	18%	64%	11%	81%
...

특히 대규모 리포지토리일수록 효과가 크며, VS Code에서는 파일 읽기 횟수가 0, grep/bash 호출도 0이 되었다.

x1lite에서의 운용: 제조업 DX에 적합한 설계

나는 개발 환경을 Beelink EliteMini (x1lite) + Ubuntu 24.04 + Docker로 구축하고 있다. CodeGraph는 호스트 측에 로컬로 설치하여 Hermes Agent나 Claude Code에서 직접 참조한다.

핵심은 인덱스를 프로젝트별로 격리하고, 원격 전송을 일절 수행하지 않는 설계다. 제조업 클라이언트 프로젝트에서는 고객의 소스 코드를 외부로 유출하지 않으면서 AI 지원을 받아야 하는데, CodeGraph는 그 요구사항에 자연스럽게 부합한다.

codegraph explore "인증 미들웨어의 호출처를 추적"

단 한 번의 쿼리로 관련 심볼과 소스 스니펫(Snippet)이 반환된다.

요약: 개발의 데이터 주권을 되찾다

AI 에이전트 이용 증가와 함께, 탐색 비용의 분산과 토큰 소비의 폭발은 심각해지고 있다. CodeGraph는 이 문제를 로컬·오프라인에서 해결하는 심플한 OSS(Open Source Software)다.

내가 생각하는 DX는 "고가의 클라우드에 의존하지 않고, 사내 자산을 주권(Sovereignty)을 가지고 관리하는 것"이다. CodeGraph는 개발 환경에 대한 자연스러운 도입 사례다.

Kobayashi WEB System은 제조업 및 중소기업을 위한 개발 환경 개선 및 AI 에이전트 통합 지원을 다루고 있다. 개발 비용이나 탐색의 번거로움으로 고민하고 있는 분들은 꼭 상담해 보길 바란다.

Discussion