[Tech Deep Dive] code-review-graph 코드 레벨 분석: LLM 에이전트를 위한 로컬 지식 그래프 및 MCP 아키텍처

한눈에 보기

• 한 줄 정의: Claude Code, Cursor 등 AI 코딩 에이전트의 컨텍스트 윈도우 낭비를 막기 위해, 코드베이스 구조를 로컬 지식 그래프(Knowledge Graph)로 추상화 하는 MCP 기반 개발자 도구
• 핵심 아키텍처: Tree-sitter AST 파싱 → SQLite 저장 → FastMCP 도구 호출 → Blast Radius (영향 범위) 계산 → 최소 컨텍스트(Minimal Context) 반환
• 서비스 가치: LLM이 저장소 전체를 읽는 (Full Scan) 비용을 제거하여 리뷰 시 평균 6.8배, 최대 49배의 토큰 소모량 절감 및 탐색 지연시간(Latency) 최적화
• 현재 상태: 2026년 5월 2일 기준 main 브랜치, 기준 커밋 0919071, 최신 릴리스 v2.3.2
• 도입 전 체크리스트(운영 리스크) 신규 분석 도구의 경로 타입 버그(Issue #384), Windows stdio 환경의 Git Subprocess Hang, 파일 삭제 시 SQLite트랜젝션 충돌, 스키마 문서 불일치.

서론: LLM 컨텍스트 최적화의 필요성

AI 코딩 도구를 대형 모노레포(Monorepo)나 비즈니스 엔터프라이즈 환경에 도입할 때 직면하는 가장 큰 병목은 '컨텍스트 탐색' 이다. LLM은 특정 파일의 변경이 미치는 영향을 파악하기 위해 불필요한 주변 파일까지 넓게 스캔하게 되며, 이는 곧 토큰 비용 증가와 응답 속도 저하로 직결된다.

 

code-review-graph 는 이 문제를 해결하기 위한 일종의 '컨텍스트 프리프로세서(Pre-processor)"로  AI 모델 자체를 튜닝하는 것이 아니라, AI 가 추론을 시작하기 전에 읽어야 할 최소한의 컨텍스트(Minimal Context)를 필터링 하여 제공하는 것이다. 

이는 "Claude Code가 필요한 코드만 읽도록, 내 저장소의 구조 지도를 로컬에 만들어 둔다"는 것입니다. 지식 그래프는 파일, 함수, 클래스, import, 호출 관계를 점과 선처럼 연결해 둔 지도라고 보면 된다. 

 

그냥 보면, 코드 리뷰 도구처럼 보이지만, 실제 코드를 따라가면 AI에게 넘길 맥락의 양과 순서를 조절하는 프로젝트인 것을 확인할 수 있다. 쉽게 말해 "AI 리뷰어"라기보다 "AI 리뷰어에게 필요한 자료만 골라 주는 사서"에 가깝다.

1. 핵심 기술 용어 정리 (Prerequisites)

용어 (Term)	기술적 정의 (Description)
지식 그래프 (Knowledge Graph)	소스 코드의 AST 기반 정적 분석 결과를 노드(파일, 함수, 클래스)와 엣지(호출, 상속, import)로 모델링한 데이터 구조.
Tree-sitter	소스 코드를 구문 분석(Parsing)하여 구체 구문 트리(CST/AST)를 생성하는 파서 생성기. 점진적 파싱을 지원해 속도가 매우 빠름.
MCP (Model Context Protocol)	LLM 클라이언트가 로컬 파일 시스템, 데이터베이스, 외부 API 등에 안전하게 접근하고 도구를 호출하기 위한 표준 인터페이스.
Blast Radius	특정 코드 변경(Diff)이 애플리케이션 내에서 영향을 미칠 수 있는 의존성 및 호출 범위.
증분 업데이트 (Incremental Update)	그래프 전체를 리빌드하지 않고, Git Diff와 파일 해시를 비교하여 변경된 파일과 의존성 노드/엣지만 재계산하는 최적화 기법.

 

2. 아키텍처 흐름 및 핵심 모듈 분석 (Hotspots)

code-review-graph의 작동 흐름은 처음 보면 복잡해 보이지만, 사용자가 AI에게 리뷰를 요청하면 MCP 서버가 호출되고, 로컬 SQLite애 구축된 그래프를 조회하여 결과를 JSON-RPC 로 AI 에게 반환하는 구조이다. 

핵심은 전체 저장소를 매번 다시 읽지 않는다는 점이다. 처음에는 그래프를 빌드해야 하지만, 이후에는 변경된 파일과 그 영향을 받는 파일만 다시 본다. 파일이 수천 개 이상인 프로젝트에서는 "모든 파일을 읽고 판단한다"는 접근 자체가 비용이 되는 것을 고려하면, 상당히 토큰비용을 줄일 수 있게 된다.

공식 벤치마크 표에서는 6개 실제 오픈소스 저장소, 13개 커밋 기준으로 naive 방식 대비 평균 8.2배 토큰 감소를 주장한다. 하지만, 작은 단일 파일 변경에서는 오히려 그래프 방식이 더 많은 토큰을 쓸 수 있고, 검색 품질과 flow detection에는 한계가 있다쓰여 있다.

 

공식 저장소가 제공하는 MCP 통합 흐름도도 같은 방향을 보여 줍니다.

 

이 그림에서 중요한 점은 AI가 직접 저장소를 샅샅이 뒤지는 구조가 아니고, AI는 먼저 MCP 도구를 부르고, 그래프는 영향을 받을 가능성이 높은 파일과 함수, 테스트 공백, 위험 신호를 돌려주는 형태이다. 그다음 AI가 필요한 파일을 더 읽게 된다, 즉, code-review-graph는 AI의 추론을 대신하지 않고, AI가 추론하기 전 읽을 자료를 줄이는 역할을 하는 것이다.

 

A. cli.py: 온보딩 및 진입점

사용자 명령(install, build, update, serve)을 처리하는 CLI 엔트리포인트다. CRG_DATA_DIR, CRG_REPO_ROOT 등의 환경 변수를 지원해서 CI 파이프라인이나 팀 단위 표준 환경 설정에 유연하게 대응할 수 있도록 설계되었다.

B. main.py: FastMCP 라우터 및 비동기 처리 최적화

총 28개의 MCP 도구(Tools)가 노출되는 API 게이트웨이 역할을 한다.

• 비동기 오프로딩 (v2.3.2 핵심 업데이트): 기존 버전에서는 그래프 빌드나 임베딩 생성 시 stdio 파이프가 멈춰서 클라이언트(Claude Code 등)가 'Synthesizing...' 상태로 무한 대기(Hang)하는 병목이 있었다. 이를 해결하기 위해 가장 무거운 5개 도구를 async def로 전환하고 asyncio.to_thread를 통해 메인 이벤트 루프에서 완전히 오프로딩(Offloading)하도록 아키텍처를 개선했다.
• 확장된 분석 도구: 단순 조회를 넘어 get_hub_nodes_tool(아키텍처 병목 탐색) 등 6종의 신규 구조 분석 도구가 추가됐고, 추출된 데이터를 Neo4j나 Gephi에서 시각화할 수 있도록 GraphML, Cypher 포맷 내보내기(Export) 기능을 지원한다.

C. parser.py: Tree-sitter 기반 AST 추출기

소스 코드를 파싱해서 NodeInfo와 EdgeInfo 객체로 변환하는 모듈이다.

• CALLS, IMPORTS_FROM, TESTED_BY 등의 엣지를 생성한다.
• 이 모듈의 구문 분석 커버리지가 곧 전체 시스템의 신뢰도(Precision vs Recall)를 결정한다. 지원 언어(현재 23개 이상)별 파서 구현 편차가 존재할 수 있어서, 조직 내 주력 스택에 대한 파싱 정확도 검증이 선행되어야 한다.

D. incremental.py: 성능 최적화의 핵심, 증분 엔진

전체 파싱 방식(Full Build)은 대형 저장소에서는 불가능에 가깝다.

• 동작 방식: Git diff와 추적(Tracked) 파일을 기준으로 변경분을 감지하고, ProcessPoolExecutor를 사용해 병렬 파싱을 수행한다.
• 리스크 포인트: 파일이 삭제(Delete)되거나 이름이 변경(Rename)된 후 update를 실행하면 SQLite 트랜잭션 충돌 오류가 발생하는 버그(Issue #406)가 있다. 대규모 리팩토링 후에는 그래프 리빌드(Rebuild)를 권장한다.

E. graph.py & tools/context.py: 스토리지 및 컨텍스트 압축

• graph.py:성능 저하를 막기 위해 SQLite의 WAL (Write-Ahead Logging) 모드를 활성화해서 읽기/쓰기 동시성을 확보한다.
• context.py: get_minimal_context 함수가 변경 파일의 Blast Radius를 계산해서 AI에게 전달할 '최소 문맥'을 생성한다. 공식 벤치마크 기준 Recall(재현율)은 100%에 가깝지만 Precision(정밀도)은 0.38 수준이다. 즉, "중요한 파일을 놓치지 않기 위해 보수적으로(넓게) 탐색"하는 안전 중심의 전략을 취하고 있다.

3. 실행 검증 가이드 (CLI 기반)

1) 설치 및 Claude Code 연동 (초기 셋업)

가장 짧은 경로는 pip 설치 후 install과 build를 실행하는 방식

python3 -m venv .venv
source .venv/bin/activate

pip install code-review-graph
code-review-graph install --platform claude-code
code-review-graph build
code-review-graph status

• 목적: 현재 저장소에 code-review-graph를 설치하고 그래프 DB를 생성
• 기대 결과: .code-review-graph/graph.db가 만들어지고, AI 도구가 MCP 서버를 부를 준비 완료
• 흔한 실패 지점: shell PATH에 CLI가 없거나, Claude Code가 이전 MCP 설정을 계속 들고 있는 경우
• 복구 메모: 터미널 재시작, Claude Code 재시작, docs/TROUBLESHOOTING.md의 command not found 항목 확인

Codex나 다른 도구로 붙이는 경우

README와 CLI 선택지를 보면 Claude Code 외에도 여러 도구를 겨냥한다. Codex 환경에서는 플랫폼 옵션을 바꾸는 방식으로 접근할 수 있다.

code-review-graph install --platform codex
code-review-graph build

• 목적: AI 코딩 도구가 MCP 서버를 통해 그래프 분석을 호출하도록 설정
• 기대 결과: 저장소별 MCP 설정과 안내 파일이 준비됨
• 흔한 실패 지점: 프로젝트 설정과 사용자 전역 설정이 섞이는 경우
• 운영 메모: 팀 환경에서는 install이 어떤 파일을 수정하는지 먼저 dry run 또는 별도 브랜치에서 확인하는 편이 안전

2) 독립적인 MCP 서버 실행 (Custom Integration)

특정 도구만 허용하여 백그라운드 서버로 띄우고 싶을 때 사용한다.

code-review-graph serve \
  --repo /path/to/project \
  --tools query_graph_tool,semantic_search_nodes_tool,detect_changes_tool

• 목적: 특정 저장소를 대상으로 필요한 MCP 도구만 노출
• 기대 결과: stdio MCP transport로 AI 도구가 선택된 tool만 호출
• 흔한 실패 지점: stdout에 로그가 섞이면 JSON-RPC 통신이 깨질 수 있음
• 운영 메모: README는 CRG_TOOLS 환경변수로 도구를 제한하는 방법도 안내

3) 변경 영향 범위(Blast Radius)직접 확인

CI/CD 파이프라인이나 프리커밋(Pre-commit) 훅에서 활용할 수 있는 명령

code-review-graph detect-changes --base HEAD~1 --brief

• 목적: 최근 커밋 대비 바뀐 파일과 영향 범위를 간단히 확인
• 기대 결과: 위험 파일, 관련 함수, 테스트 공백 후보를 요약
• 흔한 실패 지점: Git base ref가 없거나 shallow clone에서 diff 기준을 못 찾는 경우
• 운영 메모: CI에서 쓰려면 fetch depth와 base branch 설정을 명확히 해야 함

한계 확인 예제: 작은 단일 파일 변경

README 벤치마크에서 express 예시는 naive보다 graph 방식이 더 나쁜 결과를 보여서 작은 변경에도 무조건 이득이라고 보면 안 된다.

code-review-graph build

echo "# tiny change" >> README.md
code-review-graph detect-changes --base HEAD --brief

• 목적: 아주 작은 변경에서 그래프 방식이 실제로 이득인지 확인
• 기대 결과: 경우에 따라 그래프 초기화와 도구 호출 비용이 더 크게 느껴질 수 있음
• 흔한 실패 지점: 사용자가 "큰 저장소에서 좋은 전략"을 "모든 변경에서 좋은 전략"으로 오해
• 해석 메모: code-review-graph는 대형 저장소, 다중 파일 변경, 반복 리뷰에서 강점이 더 잘 드러남

4. 프로덕션 도입 시 고려사항 및 한계 

사내 개발 플랫폼이나 엔터프라이즈 환경에 표준 도구로 도입하기 전, 아래의 기술적 부채와 크리티컬 버그를 반드시 평가해야 합니다.

1. 신규 분석 도구 경로 타입 버그 (Issue #384):
   • v2.3.2에 대거 추가된 analysis_tools.py 기반 신규 분석 도구들이 동작하지 않는 치명적 버그가 있습니다. 내부 _validate_repo_root() 함수가 Path 객체를 기대하나 str 타입이 전달되어 예외(Exception)가 발생합니다. 해당 기능 활용 시 핫픽스(Hotfix) 적용이 필수적입니다.
2. 플랫폼 호환성 이슈 (OS Dependencies):
   • macOS/Linux 환경에서는 비교적 안정적이나, Windows 하위 시스템(PowerShell 등)과 stdio 방식의 MCP 통신 조합에서 프로세스 Hang 이슈(Issue #401)가 잔존합니다.
3. 스키마 문서 부채 (Documentation Debt):
   • v2.3.2부터 엣지(Edge)의 추출 상태를 명시하는 confidence 컬럼(EXTRACTED / INFERRED / AMBIGUOUS)이 DB 스키마(v9)에 추가되었으나, docs/schema.md에는 반영되지 않았습니다. 데이터 파이프라인 연동을 위해 직접 DB에 쿼리를 날릴 경우 소스코드를 직접 확인해야 합니다.
4. 보안 및 외부 API 호출 제한:
   • semantic_search_nodes_tool 등 활용 시 임베딩을 위해 소스 코드가 외부 API로 전송될 수 있습니다. 보안이 엄격한 환경에서는 로컬 임베딩 모델(예: Ollama)로 라우팅되도록 설정과 검증이 필요합니다.

 

공식 벤치마크 그림도 같은 방향을 보여 줍니다. 토큰 절감 수치는 매력적이지만, README에 함께 적힌 한계까지 같이 읽어야 균형이 맞다.

5. 서비스로서의 의미

서비스 관점에서 code-review-graph의 핵심 고객은 "코드를 많이 쓰는 사람"보다 AI 코딩 도구를 매일 쓰고, 저장소가 커서 맥락 관리 비용이 커진 개발자와 플랫폼팀이 된다

• 누가 쓰는가: Claude Code, Codex, Cursor, Kiro 같은 AI 개발 도구를 팀 단위로 쓰는 조직
• 줄이는 시간: 리뷰 전 코드 탐색, 영향 파일 찾기, 테스트 공백 확인, 반복 질문 비용
• 대체하는가: LLM을 대체하지 않고 AI 도구의 앞단에서 맥락을 고르는 보완재
• 돈을 낼 가치: 사내 개발 플랫폼, 리뷰 자동화, 보안형 로컬 코드 분석, onboarding assistant
• 운영 비용: 언어 파서 유지, MCP 호환성, DB migration, Windows/macOS/Linux 지원, 문서 관리
• 신뢰 조건: 빠진 영향 파일이 적고, false positive를 설명할 수 있으며, 소스 코드 외부 전송을 통제할 수 있어야 함

6. 비슷한 프로젝트와 비교하면

결론적으로, code-review-graph는 단순한 검색 유틸리티가 아니라 '대형 모노레포에서의 복잡한 의존성 추적 및 리뷰 자동화'에 압도적인 강점을 지닌 인프라스트럭처이다. LLM의 컨텍스트 윈도우 크기에 맹목적으로 의존하는 대신, 구조화된 데이터를 통해 프롬프트 효율과 시스템 성능을 동시에 극대화하려는 엔지니어링 팀에게 훌륭한 레퍼런스가 될 것이다.

비교 대상	핵심 역할	강점	주의점
code-review-graph	AI가 읽을 코드 범위 축소	로컬 그래프, 영향 분석, MCP 연결	언어별 품질 편차와 운영 이슈
Sourcegraph Cody	대형 코드베이스 검색과 AI 보조	엔터프라이즈 검색과 권한 모델	독립 인프라와 비용 부담
Semgrep / CodeQL	보안 취약점과 규칙 기반 분석	보안 검출과 CI 통합	AI 맥락 선택 도구는 아님
Cursor / Claude Code 기본 context	IDE 안에서 AI 코딩 보조	사용 경험이 간단함	저장소 전체 구조 기억에는 한계
일반 RAG / GraphRAG	문서나 코드 의미 검색	범용 검색과 요약에 강함	코드 구조 불변식은 별도 설계 필요