Code-Graph-RAG: 지식 그래프로 모노레포를 이해하는 궁극의 RAG

“이 함수를 호출하는 게 다 어디지?” “User 클래스가 어떤 메서드를 가지고 있더라?” “인증 관련 코드가 어딨지?”

거대한 모노레포 앞에서 이런 질문을 던진 적이 있나요? grep으로 검색하고, 파일을 열어보고, 다시 검색하고… 수십 분이 흐르고 나서야 간신히 관계를 파악했을 겁니다.

Code-Graph-RAG는 이 문제를 근본적으로 해결합니다. 코드를 지식 그래프로 변환하여, 자연어로 질문하고 정확한 답을 얻을 수 있습니다. 2,075개 이상의 스타를 받으며 개발자들의 필수 도구로 자리 잡고 있습니다.

왜 지식 그래프인가

기존 RAG의 한계

Code-Graph-RAG의 접근

코드를 그래프로 보는 겁니다. 함수가 함수를 호출하고, 클래스가 인터페이스를 구현하고, 모듈이 모듈을 임포트하는 관계. 이 모든 것을 노드와 엣지로 표현하면, 놀라운 일이 가능해집니다.

UserService.create_user() ──CALLS──▶ Database.insert()
         │
         └───INHERITS──▶ BaseService

핵심 기능

1. 지식 그래프 구축

Tree-sitter로 AST를 파싱하고, Memgraph에 그래프를 저장합니다.

추적하는 관계:

• CALLS — 함수 A가 함수 B를 호출
• INHERITS — 클래스 A가 클래스 B를 상속
• IMPLEMENTS — 클래스 A가 인터페이스 B를 구현
• IMPORTS — 모듈 A가 모듈 B를 임포트
• DEPENDS_ON_EXTERNAL — 외부 패키지 의존성

그래프 스키마:

2. 자연어 쿼리

더 이상 함수 이름을 정확히 알 필요가 없습니다.

> Show me all classes that contain 'user' in their name
> Find functions related to database operations
> What methods does the User class have?
> Show me functions that handle authentication

3. Semantic Code Search

UniXcoder 임베딩으로 “하는 일”로 검색합니다.

> error handling functions
> authentication code
> database connection logic

함수 이름이 processData여도 “사용자 인증을 처리하는 함수”로 검색하면 찾을 수 있습니다.

4. 수술적 코드 편집 (Surgical Code Edit)

이게 진짜 매력입니다. AST 기반으로 정확히 타겟팅해서 수정합니다.

> Update the login function to add rate limiting
> Add logging to all database connection functions
> Convert these Python functions to async/await pattern

작동 방식:

1. AST로 함수 위치 정확히 파악
2. diff-match-patch로 변경사항만 수정
3. 시각적 diff 미리보기 제공
4. 승인 후 적용

5. AI 코드 최적화

언어별 베스트 프랙티스를 적용합니다. 참조 문서를 제공하면 그 가이드라인에 맞게 최적화합니다.

> Optimize this function following our coding standards
> Refactor according to architecture.md

6. 실시간 업데이트

watchdog으로 파일 변경을 감지하고, 지식 그래프를 자동으로 동기화합니다. 멀티 터미널 워크플로우에서도 일관성을 유지합니다.

지원 언어

완전 지원 (7개 언어)

개발 중 (4개 언어)

C#, Go, PHP, Scala — 곧 지원될 예정입니다.

기술 스택

다중 LLM 지원

# Google Gemini
ORCHESTRATOR_PROVIDER=google
ORCHESTRATOR_MODEL=gemini-2.5-pro

# OpenAI
ORCHESTRATOR_PROVIDER=openai
ORCHESTRATOR_MODEL=gpt-4o

# Ollama (로컬)
ORCHESTRATOR_PROVIDER=ollama
ORCHESTRATOR_MODEL=llama3.2
ORCHESTRATOR_ENDPOINT=http://localhost:11434/v1

설치 및 실행

1. 저장소 클론

git clone https://github.com/vitali87/code-graph-rag.git
cd code-graph-rag

2. 의존성 설치

uv sync --extra treesitter-full

3. 환경 변수 설정

cp .env.example .env
# .env 파일 편집하여 API 키 입력

4. Memgraph 시작

docker-compose up -d

5. 그래프 구축 및 쿼리

# 파싱 및 인제스트
cgr start --repo-path /path/to/repo --update-graph --clean

# 대화형 쿼리
cgr start --repo-path /path/to/your/repo

Claude Code MCP 통합

Claude Code에서 직접 Code-Graph-RAG를 사용할 수 있습니다.

claude mcp add --transport stdio code-graph-rag \
  --env TARGET_REPO_PATH=/path/to/project \
  --env CYPHER_PROVIDER=openai \
  --env CYPHER_MODEL=gpt-4 \
  --env CYPHER_API_KEY=your-api-key \
  -- uv run --directory /path/to/code-graph-rag code-graph-rag mcp-server

MCP 도구

실제 사용 예시

예시 1: 의존성 추적

> What functions call UserService.create_user?

┌─────────────────────────────────────────────────────┐
│ UserService.create_user() 호출자                     │
├─────────────────────────────────────────────────────┤
│ AuthController.register()         auth/controller.py│
│ AdminController.create_user()     admin/controller.py│
│ TestFactory.create_test_user()    tests/factory.py  │
└─────────────────────────────────────────────────────┘

예시 2: 인터페이스 구현 찾기

> Show me all classes that implement the Repository interface

┌─────────────────────────────────────────────────────┐
│ Repository 인터페이스 구현체                          │
├─────────────────────────────────────────────────────┤
│ UserRepository     repositories/user.py             │
│ OrderRepository    repositories/order.py            │
│ ProductRepository  repositories/product.py          │
└─────────────────────────────────────────────────────┘

예시 3: 수술적 편집

> Add logging to all database connection functions

🔍 3개 함수 발견:
  - Database.connect()
  - ConnectionPool.acquire()
  - Database.reconnect()

📝 변경 미리보기:
```diff
 def connect(self):
+    logger.info("Connecting to database...")
     self._connection = self._create_connection()
+    logger.debug(f"Connection established: {self._connection.id}")
```

언제 유용한가

모노레포 탐색

수백 개의 패키지가 있는 모노레포에서, “인증 로직이 어디 있지?”라는 질문에 몇 초 만에 답할 수 있습니다.

레거시 코드 이해

문서가 없는 레거시 프로젝트. 함수가 함수를 호출하고, 그 함수가 또 다른 함수를 호출… 그래프로 보면 한눈에 이해할 수 있습니다.

리팩토링

“이 함수를 수정하면 어디가 영향받지?” — 그래프에서 CALLS 관계만 따라가면 됩니다.

온보딩

새 팀원이 프로젝트 구조를 파악하는 데 며칠이 걸리던 시간이 몇 시간으로 줄어듭니다.

다른 도구와의 비교

마치며: 코드를 그래프로 보는 시각

Code-Graph-RAG는 단순한 검색 도구가 아닙니다. 코드를 이해하는 새로운 방식입니다.

함수 A가 함수 B를 호출하고, 클래스 C가 인터페이스 D를 구현하는 관계. 이 모든 것을 그래프로 표현하면, 복잡한 코드베이스도 탐색 가능한 지도가 됩니다.

“이 함수를 호출하는 게 다 어디지?” — 이제 그래프에서 바로 확인할 수 있습니다.

🔗 관련 정보

• GitHub: https://github.com/vitali87/code-graph-rag
• 공식 사이트: https://code-graph-rag.com
• 개발자: vitali87
• 언어: Python
• 라이선스: MIT