Code-Graph-RAG: 텍스트 검색을 넘어 지식 그래프로 모노레포 호출 관계를 추적하는 AI 코드베이스 분석 도구

대규모 모노레포(Monorepo)나 다국어 코드베이스에서 AI 코딩 에이전트를 활용할 때 가장 빈번하게 발생하는 문제는 특정 함수나 모듈을 수정했을 때 어떤 호출자가 영향을 받는지 정확히 파악하기 어렵다는 점입니다. 일반적인 LLM 도구는 단순 텍스트 grep이나 파일 단위 청크 검색에 의존하기 때문에 동음이의 식별자, 주석, 테스트 코드의 문자열이 섞여 오탐이 발생하거나 다른 패키지에 위치한 실제 호출자를 누락하기 쉽습니다.

이미지 출처: vitali87 / GitHub

오픈소스 프로젝트 Code-Graph-RAG(vitali87/code-graph-rag)는 이러한 평면적 텍스트 검색의 한계를 해결하기 위해 코드베이스 전체를 구문 분석하여 상호 연결된 지식 그래프(Knowledge Graph)로 구축하는 RAG 시스템입니다. 자연어 질문을 그래프 쿼리 언어인 Cypher로 변환해 정확한 호출 경로를 순회(graph walk)하고, AST 기반 코드 수정 및 MCP(Model Context Protocol) 서버 연동을 통해 Claude Code 등 최신 코딩 에이전트와 직접 결합할 수 있습니다.

Tree-sitter와 컴파일러 프론트엔드를 결합한 다국어 지식 그래프 구축

Code-Graph-RAG의 핵심 아키텍처는 코드를 단순 텍스트가 아닌 '구조화된 그래프'로 변환하여 다루는 데 있습니다.

• Tree-sitter 기반 AST 구문 분석: 견고하고 언어 중립적인 Tree-sitter 파서를 통해 소스 코드에서 함수, 클래스, 메서드, 모듈을 추출하고 이들 간의 정의, 호출, 상속, 임포트 관계를 식별합니다.
• 컴파일러급 프론트엔드 연동 지원: 단순 구문 분석을 넘어 정밀한 타입 및 심볼 해석이 필요한 경우 C/C++용 libclang, Go용 go/types를 비롯해 Java용 javac, C#용 Roslyn, Python용 Jedi와 같은 컴파일러 수준 프론트엔드를 선택적으로 결합할 수 있습니다.
• Memgraph 기반 언어 중립 스키마 저장: 추출된 노드와 엣지는 고성능 인메모리 그래프 데이터베이스인 Memgraph에 표준화된 스키마로 저장됩니다. 여러 프로그래밍 언어가 혼재된 대규모 모노레포 환경에서도 단일 그래프 스키마 안에서 전체 프로젝트의 구조적 맥락을 통합 관리할 수 있습니다.

자연어 Cypher 질의와 정확한 영향도 분석(Blast Radius)

지식 그래프가 구축되면 개발자나 코딩 에이전트는 자연어로 코드베이스의 구조와 관계를 질의할 수 있습니다.

• 자연어-Cypher 변환 및 그래프 순회: "이 함수를 수정하면 어떤 컴포넌트가 영향을 받는가?"와 같은 자연어 질문이 입력되면 시스템이 이를 Cypher 그래프 쿼리로 변환합니다. 키워드 매칭에 기대는 추측 대신, 그래프의 엣지를 따라 호출 체인을 엄밀하게 순회(graph walk)하여 결과를 도출합니다.
• 오탐과 누락 차단: 동일한 이름의 변수나 함수라도 스코프와 네임스페이스가 다르면 다른 노드로 분리되므로, 텍스트 검색 특유의 노이즈와 잘못된 연관 관계를 원천 차단합니다.
• 데드코드 식별 및 구조 파악: 프로젝트 내에서 아무런 인입 호출(inbound call) 엣지가 없는 고립 노드를 탐색하여 불필요한 데드코드(dead code)를 손쉽게 선별할 수 있습니다.

AST 기반 안전한 수정·ast-grep·런타임 트레이스와 MCP 연동

Code-Graph-RAG는 단순 조회에 그치지 않고 코드 수정과 실행 시점 정보 통합 기능까지 포괄적으로 제공합니다.

• AST diff 미리보기 및 안전한 수정: AI가 코드를 직접 덮어쓰는 대신 AST 수준에서 변경 사항을 계산하고 diff를 먼저 시각화하여 구조적 안전성을 검증한 뒤 적용합니다.
• ast-grep 기반 구조화 검색과 재작성: 단순 정규식이 아닌 코드 문법 패턴을 기반으로 하는 ast-grep 엔진을 연동하여 대규모 코드 리팩토링 및 패턴 교체를 정밀하게 수행합니다.
• 런타임 트레이스 통합 (cgr trace): 정적 분석만으로 포착하기 어려운 동적 디스패치나 런타임 호출 흐름을 cgr trace 명령을 통해 실행 시점 트레이스 데이터로 수집하고 기존 지식 그래프에 병합할 수 있습니다.
• MCP(Model Context Protocol) 서버 모드 지원: Claude Code 등 최신 AI 코딩 도구가 MCP 프로토콜을 통해 로컬 지식 그래프를 도구(tool)로 등록하고 실시간 질의 및 코드 탐색을 수행할 수 있습니다.
• 13종 이상의 다국어 지원: Python, TypeScript, JavaScript, Rust, Go, Java, C, C++, C#, PHP, Lua, Dart 등 폭넓은 언어 생태계를 지원합니다.

실무 도입 시 고려사항과 인덱스 관리

지식 그래프 기반 코드 분석을 워크플로우에 적용할 때 염두에 두어야 할 지점도 존재합니다.

• 정기적인 인덱스 갱신 필요: 코드가 지속적으로 수정되는 환경에서 그래프 인덱스를 동기화하지 않으면 이전 상태의 호출 관계가 반환될 수 있으므로, 개발 주기나 파일 변경 시점에 맞춘 주기적 재색인이 권장됩니다.
• FFI 및 크로스 랭귀지 경계 설정: Python에서 C++ 네이티브 확장을 바인딩하는 등 언어 경계를 넘나드는 FFI(Foreign Function Interface) 호출선의 경우 단일 언어 파서만으로는 호출선이 끊길 수 있어 추가적인 분석 설정이 필요할 수 있습니다.

출처

• GitHub 저장소: vitali87/code-graph-rag
• Code-Graph-RAG 공식 웹사이트: code-graph-rag.com
• X Signal (@Ryrenz): Code-Graph-RAG 분석 및 모노레포 코드 그래프 활용 소개