CodeGraph - AI 코딩 에이전트를 위한 코드 지식 그래프 완벽 가이드

CodeGraph — AI 코딩 에이전트를 위한 로컬 코드 지식 그래프

CodeGraph - AI 코딩 에이전트를 위한 코드 지식 그래프 완벽 가이드

AI 코딩 에이전트가 코드를 읽을 때 무슨 일이 일어나는지 생각해본 적이 있나요? Claude Code나 Cursor, Codex 같은 도구가 코드베이스를 탐색할 때, 사실은 굉장히 비효율적인 작업을 반복하고 있습니다. 파일을 grep으로 훑고, glob으로 찾고, Read로 내용을 불러오며, 이 모든 과정이 토큰을 소비합니다. 바로 이 문제점을 해결하기 위해 등장한 것이 CodeGraph입니다.

CodeGraph란 무엇인가

CodeGraph는 AI 코딩 도구를 위한 로컬 코드 지식 그래프입니다. 핵심 개념은 간단합니다. 코드를 미리 인덱싱해서 기호 관계, 호출 그래프, 코드 구조를 쿼리 가능한 그래프로 정리해두면, AI 에이전트가 파일을 매번 스캔하지 않아도 됩니다.

Tree-sitter를한 AST 파싱으로 코드를 분석하고, SQLite 데이터베이스에 FTS5 전체 텍스트 검색과 함께 저장합니다. 그리고 이를 MCP 서버를 통해 8개의 전문화된 도구로 제공합니다. 완전히 로컬에서 실행되므로 어떤 데이터도 외부로 전송되지 않습니다.

지원 대상

CodeGraph는 현재 다음 에이전트를 공식 지원합니다:

• Claude Code

• Cursor

• Codex CLI

• OpenCode

• Hermes Agent (나의 환경!)

• Gemini CLI

• Antigravity IDE

이 가운데 Hermes Agent가 포함되어 있다는 점은 개인적으로도 흥미롭습니다. 이미 제가 사용하고 있는 에이전트가 바로 CodeGraph의 혜택을 받을 수 있다는 뜻이니까요.

설치 방법

macOS나 Linux라면 다음 한 줄이면 충분합니다:

curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh

Node.js가 이미 설치되어 있다면 npm으로도 설치할 수 있습니다:

npx @colbymchenry/codegraph# 또는npm i -g @colbymchenry/codegraph

프로젝트에서 초기화하는 방법은 다음과 같습니다:

cd your-projectcodegraph init -i

설치 스크립트가 자동으로 에이전트를 감지해서 설정을 구성해줍니다. 설정을 제거하고 싶다면 codegraph uninstall을 실행하면 되며, 인덱스 파일은.

벤치마크 결과

실제 7개 오픈소스 코드베이스에서 테스트한 결과는 압도적입니다. 테스트는 Claude Code를 headless 모드로 실행하고, CodeGraph 설치 여부에 따른 성능 차이를 측정했습니다.

평균적으로 비용 35% 절감, 토큰 57% 절감, 속도 46% 향상, 도구 호출 71% 감소를 달성했습니다.

각 코드베이스별 세부 결과를 보면 더 명확합니다. VS Code 확장 프로그램처럼 파일 수가 많은 프로젝트에서는 토큰 사용량이 78% 줄어들었고, Excalidraw에서는 90%까지 감소했습니다. Tokio,Rust 프로젝트에서는 비용이 82%, 토큰이 86% 각각 절감되었습니다.

특히할 도구 호출 횟수입니다. Excalidraw에서는 79회에서 단 3회로, 96%가 줄어들었습니다. 이는 AI 에이전트가 파일 탐색에 쏟는 에너지를 획기적으로 줄였다는 뜻입니다.

어떻게 작동하는가

기존 AI 에이전트가 질문에 답하려고 할 때의 과정을 비교해보면 이해가 쉽습니다. CodeGraph 없는 경우, 에이전트는 먼저 grep으로 관련 파일을 찾고, 각 파일을 Read로 불러오고, 필요하다고 판단되면 하위 에이전트를spawn해서 더 깊이 탐색합니다. 이 과정에서 모든 파일 읽기 이 토큰을 소비합니다.

CodeGraph 있는 경우, 에이전트가 먼저 codegraph_context로 해당 영역의 지도를 확인하고, codegraph_explore로 관련 코드를 쿼리합니다. 이미 인덱싱된 정보를 가져오므로 파일 읽기 없이 즉각 답변할 수 있습니다.

예를 들어 "Django ORM이 QuerySet에서 쿼리를 구성하고 실행하는 방법"이라는 질문에 대해, CodeGraph 없이면 여러 파일을 읽으면서 에이전트가 19회의 도구 호출을 수행하지만, CodeGraph를 사용하면 단 9회로 동일 질문에 답변합니다. 토큰은 739k로 1.2M 대비 크게 줄었습니다.

아키텍처 깊이 들여다보기

CodeGraph의 핵심은 Tree-sitter를한 AST 파싱에 있습니다. 코드를 파싱하여 함수, 클래스, 모듈, 호출 관계, 상속 관계 등의 기호 정보를 추출합니다. 이 모든 데이터는 SQLite 데이터베이스에 저장되며, FTS5 전체 텍스트 검색으로 쿼리를 지원합니다.

MCP 서버는 이 데이터를 8개의 전문화된 도구로 제공합니다. codegraph_context는 현재 프로젝트의 구조를 개요로 보여주고, codegraph_explore는 특정 기호나 호출 체인을 탐색하며, codegraph_search는 코드 전체를합니다.

그래프 형태의 덕분에 에이전트는 호출 체인, 사용되지 않는 메서드, 다단계 종속성 등을 자연어로 추론할 수 있습니다. 기존 벡터 검색 기반 RAG보다 구조화된 관계를 활용하므로 코드 분석에 더 효과적입니다.

사용 시 고려사항

CodeGraph가 항상 최고의 선택은 아닙니다. Gin처럼 파일 수가 약 150개 정도로 작은 프로젝트에서는 기존 네이티브 검색이 이미 빠르기 때문에, CodeGraph 적용 시 개선 폭이 상대적으로 작습니다. 또한 각 실행마다 토큰 사용량이 달라서 벤치마크 수치가 일정한 것이 아니라는 점도할 필요가 있습니다.

다만 코드베이스 규모가 커질수록 효과는 분명해집니다. 수천에서 수만 개의 파일로 구성된 프로젝트에서는 인덱스를 통한 쿼리가 파일 읽기 대비 압도적으로 효율적입니다.

마무리

AI 코딩 에이전트의 꽃은 코드를 잘 작성하는 데 있지만, 정작 코드베이스를 이해하는 데는 그다지 능숙하지 않습니다. 이 근본적인 문제를 Tree-sitter와 SQLite, MCP 서버로 해결한 CodeGraph는 에이전트의 행동 방식에 혁신을 가져올 수 있는 도구입니다.

특히 Hermes Agent 지원이 포함되어 있다는 점과, 100% 로컬 실행으로 데이터 프라이버시를 보장한다는 점에서 실무 환경에 바로 적용하기 좋은 선택입니다. 코딩 에이전트를 본격적으로하고 있다면, CodeGraph는 반드시 알아두어야 할 도구입니다.

---

📚 출처

• GitHub - colbymchenry/codegraph

• CodeGraph 공식 문서

• CodeGraph.ai

---

📚 출처

• https://news.hada.io/topic?id=29873