쉬운 설명
처음 방문한 큰 건물에서 길을 잃지 않으려면 안내 지도가 꼭 필요하잖아요. 코드도 똑같습니다. 코드가 아주 많이 쌓여 있는 저장소(모노레포라고 불러요)에서는 특정 함수가 어디서 쓰이는지 찾기가 정말 힘들거든요. Code-Graph-RAG라는 오픈소스 도구는 소스 코드를 읽어서 함수와 클래스, 그리고 이들이 서로 어떻게 연결되어 있는지를 '지식 그래프'라는 지도 형태로 만들어 줍니다. 덕분에 사람이 일상적인 말로 "이 함수를 누가 호출하고 있어?"라고 물어봐도 정확한 답을 쏙쏙 찾아줄 수 있게 되는 거죠.
요약
Code-Graph-RAG는 Tree-sitter라는 코드 분석 도구로 소스 코드를 읽어 들여 함수, 클래스, 모듈 같은 요소들을 추출한 뒤, 이를 Memgraph라는 그래프 데이터베이스에 저장합니다. 기존에 많이 쓰던 방식은 코드를 잘게 잘라 벡터(숫자 뭉치)로 바꿔 저장하는 벡터 검색이었는데요. 이 방식은 '비슷하게 생긴 코드'를 찾는 데는 뛰어나지만 '실제로 연결된 코드'를 찾는 데는 한계가 있습니다. 코드를 쪼개서 벡터로 바꾸는 과정에서 호출 관계나 의존 관계 같은 연결 정보가 사라지기 때문이에요.
그래프 방식은 이 문제를 명쾌하게 해결합니다. 함수 A가 함수 B를 호출하면 그 관계가 그래프의 선(엣지)으로 그대로 남기 때문에, "이 코드를 바꾸면 어디가 깨져?" 같은 질문에도 복잡한 유사도 계산 없이 그래프를 따라가기만 하면 바로 답을 얻을 수 있습니다. 게다가 Python, TypeScript, Rust, Go, Java 등 13개 언어를 하나의 통일된 형식으로 다루므로 여러 언어가 섞인 대형 저장소도 한 번에 처리할 수 있어요. 또 MCP 서버라는 표준 방식을 통해 Claude Code 같은 AI 도구에 바로 연결해 쓸 수 있다는 점도 아주 실용적인 강점입니다.
강의용 팁
수업에서는 '벡터 검색 vs 그래프 탐색'을 비교하는 실습을 진행해 보면 좋습니다. 같은 저장소를 두고 벡터 기반 RAG 도구에는 "이 함수랑 비슷한 코드 찾아줘"라고 물어보고, Code-Graph-RAG에는 "이 함수를 호출하는 곳을 전부 알려줘"라고 질문한 뒤 결과를 비교해 주는 거죠. 그러면 학생들이 두 방식의 차이를 직관적으로 이해할 수 있습니다. 작은 오픈소스 저장소 하나를 예제로 정해 cgr start --repo-path 경로 --update-graph --clean 명령어를 실행하고, 생성된 결과 그래프를 함께 살펴보는 실습도 부담 없이 해볼 수 있어요.
또 하나 좋은 활용 소재는 'Ruby 언어가 추가된 방식'입니다. 파서를 새로 직접 짜지 않고, ast-grep이라는 구조 기반 검색 도구용 YAML 패턴 파일 하나만으로 지원 언어를 늘린 사례인데요. 이를 통해 "확장성 있는 설계란 무엇인가"를 자연스럽게 설명할 수 있습니다. 개발 경험이 없는 학생들에게도 "규칙을 딱 하나 추가했더니 새로운 언어 전체가 지도로 들어왔다"는 식으로 쉽게 풀어서 전달하기에 좋습니다.
주의 사항
Code-Graph-RAG는 아직 정식 버전이 아닌 PyPI 기준 Beta 상태(0.0.558)입니다. Docker, cmake, ripgrep, Python 3.12 이상 등 미리 설치해야 하는 전제조건이 많아서, 강의 환경에서 바로 실행하려면 사전 준비 시간이 꽤 걸릴 수 있어요. 또한 코드가 수정되면 기존 그래프가 옛날 정보가 되기 때문에, 실습 도중 코드를 바꿨다면 그래프를 다시 생성해야 최신 결과를 볼 수 있다는 점도 미리 안내해 주세요. 실무 프로덕션의 핵심 업무에 바로 적용하기보다는 보조 도구로 먼저 활용해 보는 것이 안전하다는 점도 꼭 함께 짚어주시는 게 좋습니다.
자체 검증
원문(README와 정리 자료)과 대조해 보면 핵심 내용들은 모두 확실한 근거를 가지고 있습니다. Tree-sitter로 파싱해 Memgraph에 지식 그래프로 저장하는 구조, 13개 언어 전면 지원 및 Ruby의 ast-grep 기반 구조 지원, MCP 서버를 통한 Claude Code 연결 기능 등은 원문에 분명히 명시되어 있어요. "벡터 검색은 유사한 근사치를, 그래프는 정확한 관계를 제공한다"는 설명 역시 코드를 조각(청크)으로 나누어 임베딩할 때 인덱싱 단계에서 관계 정보가 사라진다는 논리로 잘 뒷받침됩니다. 이는 정리 자료의 해석이자 관련 분야에서 일반적으로 통용되는 설명 방식이에요. 다만 버전 번호(0.0.558)나 Beta 상태 같은 세부 정보는 시점에 따라 달라질 수 있으니, 실제 강의를 진행하는 시점에 다시 한 번 확인해 보시는 것을 권장합니다.
태그
#AI #코드그래프RAG #지식그래프 #MCP #개발도구 #AI교육 #벡터검색
원문
https://github.com/vitali87/code-graph-rag