CodeGraph — 코드 변경을 따라가는 로컬 지식 그래프로 AI 에이전트의 코드 탐색을 줄입니다

AI 요약

CodeGraph는 AI 코딩 에이전트가 코드를 파악할 때 반복하는 파일 검색을 사전에 만든 코드 그래프로 대체합니다. 저장소를 색인하면 함수·클래스 같은 심볼과 호출·가져오기·상속 관계를 연결하고, 에이전트는 MCP(Model Context Protocol) 도구인 codegraph_explore를 호출해 관련 소스와 호출 경로, 변경 영향 범위를 한 번에 받습니다. 그래프와 검색 색인은 프로젝트의 .codegraph/ 디렉터리에 SQLite로 저장하며, 외부 서비스에 코드를 보내지 않는다고 안내합니다.

설치와 동기화

전역 CLI를 설치한 뒤 codegraph install을 실행하면 Claude Code, Cursor, Codex CLI, OpenCode, Gemini CLI, Kiro, GitHub Copilot 등 에이전트 설정에 MCP 서버를 연결합니다. 이 단계는 에이전트 연결만 맡습니다. 프로젝트별로 codegraph init을 실행해야 색인이 만들어집니다. 이후 파일 감시기가 변경을 감지해 그래프를 갱신하며, 기본 디바운스 시간은 2초입니다. 감시기가 갱신하는 짧은 동안 결과가 변경 전 파일을 가리키면 MCP 응답에 경고를 붙입니다. 서버가 다시 연결될 때도 파일 크기·수정 시각과 해시를 대조해, 서버가 꺼진 사이 생긴 변경을 반영합니다.

색인 엔진은 Rust 네이티브 커널과 tree-sitter 문법을 사용해 20개 언어를 처리합니다. 파일별 참조 엔진과 그래프가 일치하는지 검증하고, 사전 빌드 바이너리가 없는 플랫폼이나 구문 오류가 있는 파일은 대체 경로로 처리한다고 설명합니다. 데이터베이스는 SQLite와 FTS5를 사용하며, 파일 변경 때는 전체 저장소를 다시 훑지 않고 바뀐 부분을 갱신합니다. 저장소 크기와 실제 사용 가능한 CPU·메모리에 맞춰 작업자 풀과 캐시도 조정합니다. 웹 프레임워크 경로를 핸들러에 연결하고, Swift와 Objective-C, React Native의 JavaScript와 네이티브 코드처럼 언어 경계를 넘는 호출도 일부 해석합니다.

벤치마크와 해석

프로젝트가 제시한 비교는 VS Code, Excalidraw, Django, Tokio, OkHttp, Gin, Alamofire 등 7개 저장소에서 Claude Code의 헤드리스 실행을 비교한 결과입니다. 저장소마다 같은 구조 질문을 던지고, CodeGraph를 켠 경우와 끈 경우를 각각 4회 실행해 중앙값을 보고했습니다. Claude Opus 4.8을 사용했으며, 양쪽 모두에서 CodeGraph CLI 실행을 차단해 비교군이 우회 도구를 사용하지 못하게 했다고 밝힙니다.

프로젝트가 집계한 평균 결과는 도구 호출 88% 감소, 응답 시간 53% 단축, 처리 토큰 62% 감소, 비용 44% 감소입니다. CodeGraph 사용 시 저장소별 호출은 1~4회였고, 비교군은 최대 43회였습니다. 7개 저장소 모두에서 파일 읽기가 0회였다는 점도 함께 제시합니다. 비용 차이는 질문이 요구하는 탐색량에 따라 달랐습니다. 비교군이 28~43회 도구를 쓴 저장소에서는 57~78% 절감했지만, Django는 13%, Gin은 거의 차이가 없었습니다.

토큰 처리량 감소와 컨텍스트 창 점유 감소는 같은 뜻이 아닙니다. CodeGraph는 관련 코드를 한 번에 묶어 응답하므로, 다중 턴 세션이 끝날 때 남는 검색 문맥은 비교군보다 약 80% 많았다고 설명합니다. VS Code 사례에서는 6만 7천 토큰 대 1만 8천 토큰입니다. 따라서 긴 세션이나 작은 컨텍스트 창을 사용하는 환경에서는 이 잔여 문맥도 고려해야 합니다. 벤치마크는 프로젝트가 공개한 측정 결과이며, 서로 다른 구조 질문 7개를 사용했다는 범위 안에서 읽어야 합니다.

변경 영향 분석과 활용

CLI에는 심볼 검색, 호출자·피호출자 조회, 영향 범위 분석 외에도 변경 파일에 영향을 받는 테스트를 찾는 codegraph affected가 있습니다. 예를 들어 git diff --name-only의 결과를 넘겨 관련 테스트를 찾고, CI에서 그 테스트만 실행하도록 구성할 수 있습니다. 색인 대상은 .gitignore와 기본 제외 경로를 따르며, codegraph.json으로 확장자나 제외·포함 경로를 조정합니다. 통계 수집은 기본적으로 익명 사용 정보를 다룬다고 밝히며, codegraph telemetry off 등으로 끌 수 있습니다.

원문: GitHub / 번역·요약: Trawling