'CodeGraph' 가이드
(FastAPI & Claude 성능 분석 포함)
최근 Claude Code, Cursor, Gemini 등 개발을 도와주는 AI 코딩 에이전트의 성능이 상당합니다. 하지만 복잡하고 거대한 코드베이스를 다룰 때, 에이전트가 코드를 탐색하느라 수많은 토큰을 소모하고 응답도 느려지는 문제를 한 번쯤 겪어보셨을 겁니다.
오늘은 이러한 비효율성을 해결하기 위해 등장한 오픈소스 프로젝트, CodeGraph에 대해 자세히 알아보겠습니다.
1. CodeGraph란 무엇인가?
CodeGraph는 AI 에이전트가 코드베이스를 탐색할 때 발생하는 토큰 소모와 응답 지연 문제를 해결하기 위한 사전 인덱싱(Pre-indexed) 코드 지식 그래프(Code Knowledge Graph) 시스템입니다. 한 마디로 하면 "AI를 효과적으로 쓰는 방법"이겠네요.
실제 동작은 아래와 같은 방식으로 진행됩니다.
- 추출 (Extraction) — tree-sitter를 통해 소스 코드를 AST(추상 구문 트리)로 파싱합니다. 언어별 전용 쿼리를 사용하여 노드(함수, 클래스, 메서드)와 엣지(호출, 임포트, 상속, 인터페이스 구현 관계)를 추출합니다.
- 저장 (Storage) — 모든 데이터는 FTS5 전체 텍스트 검색(Full-Text Search)을 지원하는 로컬 SQLite 데이터베이스(.codegraph/codegraph.db)에 저장됩니다.
- 해결 (Resolution) — 추출이 완료되면 상호 참조 관계를 해결합니다. 함수 호출은 실제 정의로, 임포트(import)는 소스 파일로 연결되며, 클래스 상속 및 프레임워크 전용 패턴까지 명확하게 매핑됩니다.
- 자동 동기화 (Auto-Sync) — MCP 서버가 운영체제(OS) 네이티브 파일 이벤트를 감지하여 프로젝트를 실시간으로 감시합니다. 코드 변경 시 디바운싱(2초간의 정적 윈도우)을 거치고, 소스 파일만 필터링하여 증분 동기화(Incremental Sync)를 수행합니다. 덕분에 별도의 설정 없이도 코딩하는 동안 그래프가 항상 최신 상태로 유지됩니다.
💡 기존 방식의 문제점
일반적으로 Claude 같은 AI 에이전트에게 "특정 함수를 호출하는 곳을 찾아줘" 혹은 "A라는 함수의 기능이 뭐야?" 라고 요청하면, 에이전트는 내부적으로 grep, glob, read 같은 도구를 수십 번씩 호출하며 프로젝트 전체 파일을 스캔합니다. 이 과정에서 다음과 같은 문제가 발생합니다.
- 컨텍스트 낭비: 불필요한 코드까지 LLM의 메인 컨텍스트에 포함되어 토큰 비용이 불어납니다.
- 응답 지연: 수많은 파일을 직접 읽고 분석하느라 답변을 받기까지 오랜 시간이 걸립니다.
✨ CodeGraph의 해결책
CodeGraph는 AI 에이전트의 탐색 방식을 "파일 전체 스캔 방식"에서 "구조화된 그래프 조회 방식"으로 전환합니다. 코드를 미리 구조화된 지식 그래프로 인덱싱해 두고, 에이전트가 필요할 때 데이터베이스를 즉시 조회하게 만들어 토큰 소모와 탐색 시간을 극적으로 줄여줍니다.
2. CodeGraph 주요 장점(주관적)
- 100% 로컬 동작: 외부 API 키나 클라우드 서비스 연동이 전혀 필요 없습니다. 모든 데이터가 개발자 PC의 SQLite DB로만 관리되므로 사내 보안 코드베이스에도 유출 걱정 없이 안전하게 적용할 수 있습니다.
- 실시간 자동 동기화: 운영체제의 파일 이벤트를 감시하여, 코드가 수정되면 변경된 파일만 증분 갱신합니다.
- 간편한 배포: 복잡한 설정 없이 한 줄의 명령어로 간편하게 설치하고 대화형 마법사로 에이전트를 자동 구성할 수 있습니다.
- 수많은 언어 지원: 대략 20종의 프레임워크를 지원합니다. TypeScript, JavaScript, Python, Go, Rust ...
3. 실제 효율성 및 성능 벤치마크 비교
제가 가장 많이 사용하는 FastAPI 프로젝트와 VSCode 환경, 그리고 Claude 3.5 Sonnet 모델을 기준으로 측정한 실제 효율성 데이터입니다. 기존 방식(CodeGraph 미사용)과 사용 후의 차이를 구체적인 지표로 비교 가능합니다.
① Claude 3.5 Sonnet 기준 종합 효율성 비교
파이썬 웹 프레임워크인 FastAPI(약 100개 파일 규모) 에서 리팩토링 및 아키텍처 분석 작업을 수행했을 때의 평균 데이터입니다.
| 평가 항목 (Metric) | CodeGraph 미사용 (기존 에이전트) |
CodeGraph 사용 (MCP 연동) |
개선율 (Improvement) |
| 평균 작업당 비용 (USD) | $0.78 | $0.33 | 비용 58% 절감 |
| 평균 입력 토큰 수 (Input Tokens) | 157.8k | 111.7k | 토큰 29% 절감 |
| 불필요한 파일 도구 호출 (Grep/Read) | 60회 | 4.6회 | 도구 호출 92% 감소 |
| 작업 완료 시간 (Latency) | 170초 | 132초 | 속도 22% 단축 |
분석 요약: CodeGraph를 사용하면 Claude가 어떤 파일에 원하는 정보가 있는지 찾아 헤매는 '탐색 단계'를 건너뛰기 때문에, 입력 토큰 수가 29% 감소하고 결과적으로 비용이 58%나 절감됩니다. 크게 차이나는 경우에는 5000 : 170000 처럼 30배 정도나 토큰이 차이나는 경우도 있었습니다.
아래는 공식 벤치마크 결과입니다.
② 프로젝트 규모별 도구 호출(Grep/Read) 감소율
코드베이스의 크기가 커질수록 CodeGraph의 효율성은 더욱 압도적으로 변합니다. VSCode를 비롯한 주요 오픈소스 프로젝트에서의 파일 탐색 도구 호출 감소량 그래프입니다.
[프로젝트 규모별 AI 도구 호출 감소율 (%)]
VS Code (~10,000 files) : ██████████████████████████████ 80% 감소
Django (~3,000 files) : ████████████████████████ 65% 감소
FastAPI (~800 files) : ███████████████████████ 62% 감소
Tokio (~790 files) : ████████████████████ 55% 감소③ VSCode 및 개발 환경에서의 체감 효과
- VSCode 파일 저장 시 자동 인덱싱: 코드를 수정하고 Ctrl + S를 누르면 배경에서 2초 이내에 지식 그래프가 업데이트됩니다. 개발 흐름이 전혀 끊기지 않습니다. (저는 이 부분이 신기하더라구요. 따로 AI를 돌리는 것도 아닌데 저장만 하면 알아서 sqlite에도 저장이 되고, 바로바로 claude가 파일을 탐색하는데 도움을 줍니다.)
- Claude의 Hallucination 방지: 컨텍스트 창이 수많은 소스 코드로 가득 차면 Claude가 핵심 논리를 놓치고 엉뚱한 답변을 하기 쉽습니다. CodeGraph는 필요한 핵심 맥락만 골라 제공하므로 답변의 정확도가 눈에 띄게 향상됩니다. (사실 이 부분은 프로젝트가 그렇게까지 크진 않아서 체감하지 못하였지만 문서에는 저런 내용이 있더라구요.)
4. CodeGraph 시작하기 (튜토리얼)
내 프로젝트에 CodeGraph를 직접 적용하고 AI 에이전트와 연동하는 과정을 단계별로 안내해 드리겠습니다.
1: 설치하기
CodeGraph는 단일 명령어로 손쉽게 설치할 수 있는 독립형 바이너리를 지원합니다. 터미널을 열고 아래 명령어를 입력해 줍니다. 아참, node.js를 설치해야 npx를 사용 가능하고, 파워쉘/맥/리눅스 에서도 설치 가능합니다.
# Bash
# 글로벌 설치 및 설정 마법사 실행
npx @colbymchenry/codegraph init
# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh
# Windows (PowerShell)
irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex명령어를 실행하면 대화형 설치 마법사가 나타나며, 현재 시스템에 설치된 AI 에이전트(Claude Code, Cursor 등)를 자동으로 감지하여 MCP설정을 도와줍니다. 저는 클로드만 사용하였습니다.
2: 프로젝트 인덱싱 빌드
설치가 완료된 후, 분석하고자 하는 프로젝트(예: FastAPI 기반 프로젝트)의 루트 디렉토리에서 인덱싱을 초기화합니다.
# Bash
codegraph init -i이 명령을 실행하면 프로젝트의 모든 소스 코드를 스캔하여 .codegraph/codegraph.db 파일을 생성하고 해당 파일에 지식 그래프를 생성합니다. 프로젝트 규모에 따라 몇 초에서 수십 초 정도 소요됩니다. 아래 그림처럼 값이 들어간다면 성공입니다. 저는 sqlite viewer extension을 활용하기에 이렇게 보입니다.
3: AI 에이전트 활용하기
연동이 완료되면 Claude Code나 VSCode 내의 에이전트(CLI)에게 다음과 같이 구체적인 아키텍처 질문을 던질 수 있습니다.
- 질문 예시 1: "현재 A 엔드포인트가 호출하는 하위 비즈니스 로직과 데이터베이스 모델의 관계를 알려줘."
- 질문 예시 2 (파급 효과 분석): "지금 auth.py에 있는 토큰 검증 함수를 수정하면, 프로젝트 전체에서 어떤 코드들이 영향을 받는지 codegraph_impact 도구로 분석해 줘."
Claude는 수십 개의 파일을 열어보느라 버벅대지 않고, CodeGraph가 제공하는 관계도를 바탕으로 빠르게 답변을 내놓습니다.
4: 그 외의 코드
codegraph # Run interactive installer
codegraph install # Run installer (explicit)
codegraph uninstall # Remove CodeGraph from your agents (inverse of install)
codegraph init [path] # Initialize in a project (--index to also index)
codegraph uninit [path] # Remove CodeGraph from a project (--force to skip prompt)
codegraph index [path] # Full index (--force to re-index, --quiet for less output)
codegraph sync [path] # Incremental update
codegraph status [path] # Show statistics
codegraph query <search> # Search symbols (--kind, --limit, --json)
codegraph files [path] # Show file structure (--format, --filter, --max-depth, --json)
codegraph context <task> # Build context for AI (--format, --max-nodes)
codegraph callers <symbol> # Find what calls a function/method (--limit, --json)
codegraph callees <symbol> # Find what a function/method calls (--limit, --json)
codegraph impact <symbol> # Analyze what code is affected by changing a symbol (--depth, --json)
codegraph affected [files...] # Find test files affected by changes (see below)
codegraph serve --mcp # Start MCP server마치며
AI 지원을 받아 코딩하는 시대에 토큰 절약과 속도 개선은 개발 생산성과 직결되는 매우 중요한 요소입니다. 특히 비용이 비싼 Claude 3.5 Sonnet 등을 메인으로 사용하신다면 CodeGraph 도입은 선택이 아닌 필수가 아닐까 생각합니다. 실제로 Claude 팀 플랜을 사용중인데, 보통 오전에 작업하면 점심시간 언저리에서 뻗던 클로드가 하루종일 까지는 아니어도 2~3시 까지는 버티는 정도가 된 것 같습니다. Claude에게 질문하여 입력 토큰이 유의미하게 줄어드는 것을 확인할 수 있었구요. 이제 막 사용하는 단계이기에 1~2주 정도는 사용량 추적하면서 확인이 필요한 단계기는 합니다만, 지금까지의 결과로는 매우 마음에 드는 기능이네요.
그리고 로컬에서 돌아가기에 프로젝트 내부망에서 사용할수 있다는 점도 꽤나 매력적이지 않나 생각하고 있습니다. 더 규모가 커지거나 파일을 수시로 업데이트 하는 경우, Git 과의 연동 등이 문제가 없는지도 확인해 봐야겠네요.
GitHub - colbymchenry/codegraph: Pre-indexed code knowledge graph for Claude Code, Codex, Gemini, Cursor, OpenCode, AntiGravity,
Pre-indexed code knowledge graph for Claude Code, Codex, Gemini, Cursor, OpenCode, AntiGravity, Kiro, and Hermes Agent — fewer tokens, fewer tool calls, 100% local - colbymchenry/codegraph
github.com