CodeGraph: AI 코딩 에이전트를 위한 사전 인덱싱 코드 지식 그래프

읽을거리&정보공유
, , , , , ,
1

CodeGraph: AI 코딩 에이전트를 위한 사전 인덱싱 코드 지식 그래프
CodeGraph: AI 코딩 에이전트를 위한 사전 인덱싱 코드 지식 그래프1536×804 192 KB

CodeGraph 소개

CodeGraph는 Claude Code, Cursor, Codex CLI, opencode 같은 AI 코딩 에이전트가 코드베이스를 탐색할 때 발생하는 토큰 소모와 응답 지연 문제를 해결하기 위한 사전 인덱싱(pre-indexed) 코드 지식 그래프(Code Knowledge Graph)입니다. 일반적으로 코딩 에이전트가 "이 함수를 호출하는 곳을 모두 찾아줘" 같은 요청을 받으면, 내부의 Explore 서브에이전트가 grep, glob, Read 같은 도구를 수십 번씩 호출하며 파일을 스캔합니다. 이 과정에서 메인 컨텍스트에 불필요한 코드가 흘러들고, 시간이 길어지며, 토큰 비용도 누적됩니다.

CodeGraph는 이 "파일 스캔으로 시작하는 탐색" 을 "그래프 조회로 시작하는 탐색" 으로 바꾸는 MCP 서버입니다. tree-sitter 기반 파서가 19개 이상의 언어에서 함수, 클래스, 메서드 같은 노드와 호출, import, 상속 같은 엣지를 추출하고, 그 결과를 프로젝트 내부의 .codegraph/codegraph.db SQLite 파일에 FTS5 전체 텍스트 검색 인덱스와 함께 보관합니다. 에이전트는 codegraph_search, codegraph_callers, codegraph_impact 같은 도구를 통해 그래프를 즉시 조회하고, 그 결과를 바탕으로 필요한 파일만 정확히 읽습니다.

CodeGraph 설치 과정

저자인 Colby McHenry는 README에서 6개 실제 코드베이스(VS Code, Excalidraw, Claude Code, Alamofire, Swift Compiler 등)를 대상으로 한 자체 벤치마크를 공개하고 있습니다. 같은 질문을 Claude Opus 4.6 + Claude Code v2.1.91 환경에서 Explore 에이전트가 CodeGraph를 쓸 때와 쓰지 않을 때로 나눠 측정한 결과로, 평균 92% 적은 도구 호출과 71% 더 짧은 응답 시간 을 보고합니다. 이 글에서는 CodeGraph의 동작 방식, 지원 언어와 프레임워크 라우트, 벤치마크 수치, 설치와 사용 방법, 라이선스를 차례로 정리합니다.

CodeGraph가 해결하는 토큰 소모 문제

코딩 에이전트의 토큰 소모 패턴은 대부분 "코드 어디에 있는지 찾는" 과정에서 발생합니다. 함수 한 개를 수정하려고 해도, 에이전트는 그 함수가 어디에 정의되어 있는지, 어디서 호출되는지, 어떤 import 사슬을 거쳐 도달하는지를 모르기 때문에 grep과 Read를 반복합니다. 모놀리식 코드베이스에서는 이 발견 단계 가 답변 시간의 대부분을 차지합니다.

CodeGraph는 이 발견 단계를 인덱스 시점으로 이동 시킵니다. 프로젝트 초기화 시 한 번 전체 그래프를 만들어 SQLite에 저장하고, 이후에는 운영체제의 네이티브 파일 이벤트(FSEvents, inotify, ReadDirectoryChangesW)를 감시하면서 2초 정적 윈도우(debounced 2-second quiet window)로 변경된 파일만 증분 동기화합니다. 에이전트가 작업하는 동안 그래프가 자동으로 최신 상태를 유지하므로, 별도의 재인덱싱 명령이 필요 없습니다.

저자가 공개한 벤치마크 표는 다음과 같습니다. 모든 측정은 Claude Opus 4.6(1M context) + Claude Code v2.1.91에서, 같은 질문을 CodeGraph 활성/비활성 으로 동일하게 던져 측정한 결과입니다.

코드베이스 CodeGraph 사용 CodeGraph 미사용 개선폭
VS Code (TypeScript) 3 calls, 17s 52 calls, 1m 37s 94% 적음, 82% 빠름
Excalidraw (TypeScript) 3 calls, 29s 47 calls, 1m 45s 94% 적음, 72% 빠름
Claude Code (Python+Rust) 3 calls, 39s 40 calls, 1m 8s 93% 적음, 43% 빠름
Claude Code (Java) 1 call, 19s 26 calls, 1m 22s 96% 적음, 77% 빠름
Alamofire (Swift) 3 calls, 22s 32 calls, 1m 39s 91% 적음, 78% 빠름
Swift Compiler (Swift/C++) 6 calls, 35s 37 calls, 2m 8s 84% 적음, 73% 빠름

Swift Compiler 벤치마크는 25,874개 파일과 272,898개 노드로 가장 큰 케이스이며, CodeGraph는 이를 4분 이내에 인덱싱했고, 에이전트는 6번의 explore 호출과 0번의 파일 읽기 로 "Swift 컴파일러가 오류 진단을 어떻게 처리하는가" 라는 횡단(cross-cutting) 질문에 35초만에 답했습니다.

CodeGraph의 동작 방식

CodeGraph의 파이프라인은 추출 → 저장 → 해결 → 자동 동기화의 4단계로 구성됩니다.

추출(Extraction): tree-sitter 파서가 소스 코드를 AST로 변환합니다. 언어별 쿼리(language-specific queries) 가 함수, 클래스, 메서드 같은 노드와 호출, import, extends, implements 같은 엣지를 추출합니다. 이 단계는 IDE 의 의미적 분석과 동일한 수준의 정확도를 목표로 합니다.

저장(Storage): 모든 노드와 엣지는 로컬 SQLite DB(.codegraph/codegraph.db) 에 들어갑니다. SQLite 의 FTS5 전체 텍스트 검색 인덱스가 함께 생성되어 "UserService 라는 이름이 들어간 모든 심볼" 같은 질의가 즉시 동작합니다.

해결(Resolution): 추출이 끝난 후 참조가 해결됩니다. 함수 호출은 정의로, import 는 소스 파일로, 클래스 상속은 상위 클래스로 각각 연결됩니다. 이때 프레임워크 라우트(framework-aware routes) 가 함께 처리됩니다.

자동 동기화(Auto-Sync): MCP 서버가 운영체제 네이티브 파일 이벤트를 감시하다가 변경 사항이 감지되면 2초 정적 윈도우 뒤에 해당 파일만 증분 갱신합니다. 빌드 아티팩트, node_modules, dist 같은 디렉토리는 기본적으로 제외 글롭(exclude glob)에 포함되어 있습니다.

README 본문의 ASCII 다이어그램은 위 흐름을 다음과 같이 표현합니다.

Claude Code
  ↓
Explore Agent  ───  Explore Agent
        ↓                  ↓
   CodeGraph MCP Server
   ┌────────┬───────────┬──────────┐
   │ Search │ Callers   │ Context  │
   └────────┴───────────┴──────────┘
              ↓
      SQLite Graph DB
   ┌─────────────────────┐
   │ • 387 symbols       │
   │ • 1,204 edges       │
   │ • Instant lookups   │
   └─────────────────────┘

CodeGraph의 19개 언어와 13개 프레임워크 라우트

언어 지원 폭은 CodeGraph 의 차별점 중 하나입니다. TypeScript, JavaScript, Python, Go, Rust, Java, C#, PHP, Ruby, C, C++, Swift, Kotlin, Scala, Dart, Svelte, Vue, Liquid, Pascal/Delphi 가 "Full support" 로 표기되어 있고, 각 언어별로 클래스, 메서드, 함수, 트레이트 등 주요 심볼이 추출됩니다. Scala 의 경우 클래스, 트레이트, 메서드, 타입 별칭, Scala 3 enum 까지 추출하며, Svelte 5 runes 와 SvelteKit 라우트도 인식합니다.

또한 CodeGraph 는 프레임워크 라우트(framework-aware routes) 노드를 만들어 URL 패턴을 해당 핸들러 함수/메서드와 references 엣지로 연결합니다. 이 덕분에 "이 컨트롤러를 호출하는 URL 이 무엇인지" 같은 질의가 가능합니다. 지원 프레임워크는 다음과 같습니다.

프레임워크 인식되는 형태
Django) path(), re_path(), url(), include(), CBV .as_view()
Flask) @app.route('/path', methods=[...]), 블루프린트 라우트
FastAPI) @app.get(...), @router.post(...), 표준 HTTP 메서드 전체
Express) app.get(...), router.post(...), 미들웨어 체인
Laravel) Route::get(), Route::resource(), Controller@action
Rails) get '/x', to: 'users#index', 해시 로켓 => 문법
Spring) @GetMapping, @PostMapping, @RequestMapping
Gin / chi / gorilla / mux) r.GET(...), router.HandleFunc(...)
Axum / actix / Rocket) .route("/x", get(handler))
ASP.NET) [HttpGet("/x")]
Vapor) app.get("x", use: handler)
React Router / SvelteKit) 라우트 컴포넌트 노드

CodeGraph 설치와 기본 사용

설치는 npx 한 줄로 충분합니다. 대화형 설치기가 설치된 에이전트(Claude Code, Cursor, Codex CLI, opencode) 를 자동 감지하고, 각 에이전트의 MCP 서버 설정과 권한 자동 허용을 함께 구성합니다.

npx @colbymchenry/codegraph

비대화형(CI / 스크립팅) 으로 사용할 경우 다음과 같은 플래그를 조합할 수 있습니다.

codegraph install --yes                              # 감지된 에이전트, 전역 설치
codegraph install --target=cursor,claude --yes       # 대상 명시
codegraph install --target=auto --location=local     # 프로젝트 로컬 설치
codegraph install --print-config codex               # 설정 스니펫만 출력

프로젝트 인덱스는 codegraph init -i 로 초기화합니다. 이후에는 파일 변경에 따라 자동 동기화되므로, 별도의 재인덱싱이 필요 없습니다. 라이브러리로도 사용 가능하며, TypeScript 측 API 는 다음과 같습니다.

import CodeGraph from '@colbymchenry/codegraph';

const cg = await CodeGraph.init('/path/to/project');
await cg.indexAll({
  onProgress: (p) => console.log(`${p.phase}: ${p.current}/${p.total}`)
});

const results = cg.searchNodes('UserService');
const callers = cg.getCallers(results[0].node.id);
const context = await cg.buildContext(
  'fix login bug',
  { maxNodes: 20, includeCode: true, format: 'markdown' }
);
const impact = cg.getImpactRadius(results[0].node.id, 2);

cg.watch();   // auto-sync on file changes
cg.unwatch(); // stop watching
cg.close();

MCP 서버 모드에서 노출하는 도구는 8개입니다: codegraph_search(이름으로 심볼 찾기), codegraph_context(작업 컨텍스트 구축), codegraph_callers(호출자), codegraph_callees(피호출자), codegraph_impact(영향 반경 분석), codegraph_node(단일 심볼 상세), codegraph_files(파일 구조), codegraph_status(인덱스 상태).

codegraph affected 명령은 변경된 소스 파일에 영향을 받는 테스트 파일을 임포트 의존 그래프를 따라 자동 추적합니다. CI/pre-commit hook 에서 변경분에 해당하는 테스트만 실행하도록 만드는 데 활용할 수 있습니다.

codegraph affected src/utils.ts src/api.ts
git diff --name-only | codegraph affected --stdin
codegraph affected src/auth.ts --filter "e2e/*"

라이선스

CodeGraph는 MIT 라이선스로 공개되어 있어 개인 및 상업적 목적으로 자유롭게 사용할 수 있습니다. 100% 로컬에서 동작하고 외부 API 호출이 없으며, SQLite 데이터베이스 파일만 디스크에 남기므로 사내 코드베이스에도 적용하기 쉽습니다.

:github: CodeGraph 프로젝트 GitHub 저장소

더 읽어보기



이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다. :hugs:

:pytorch:파이토치 한국 사용자 모임:south_korea:이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일:love_letter:로 보내드립니다! (기본은 Weekly지만 Daily로 변경도 가능합니다.)

:wrapped_gift: 아래:down_right_arrow:쪽에 좋아요:+1:를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~ :star_struck:

2개의 좋아요