code-review-graph 소개
최근 AI 기반 코딩 어시스턴트인 Claude Code를 활용하여 개발 생산성을 높이는 사례가 급증하고 있습니다. 하지만 Claude Code에게 특정 커밋을 리뷰하거나 새로운 기능을 추가해 달라고 요청할 때, 모델은 전체 코드베이스의 문맥을 파악하기 위해 수많은 파일을 읽어들이는 비효율성을 보입니다. 소규모 프로젝트에서는 이러한 방식이 큰 문제가 되지 않지만, FastAPI(약 2,915개 파일)나 Next.js(약 27,732개 파일)와 같은 대규모 모노레포 환경에서는 상황이 전혀 다릅니다. 변경 사항과 전혀 관련 없는 수천 개의 파일까지 스캔하게 되면서 불필요한 토큰 낭비가 기하급수적으로 발생하게 됩니다. 이는 개발자의 API 비용 부담을 가중시킬 뿐만 아니라, 프롬프트 내에 노이즈를 증가시켜 오히려 코드 리뷰의 품질을 떨어뜨리는 주요 원인이 됩니다.
이러한 문제를 근본적으로 해결하기 위해 등장한 오픈소스 도구가 바로 **code-review-graph**입니다. code-review-graph 프로젝트는 Tree-sitter를 사용하여 사용자의 코드베이스를 분석하고, 함수, 클래스, 임포트, 호출 및 상속 관계를 모두 포함하는 영구적인 구조적 지도(Knowledge Graph)를 구축합니다.
이렇게 추출된 모든 노드와 엣지 데이터는 외부 서버나 클라우드로 전송되지 않고 개발자 로컬 환경의 SQLite 데이터베이스에 안전하게 저장됩니다. 이후 개발자가 파일을 수정하거나 Git 커밋을 수행하면, 시스템이 변경된 파일과 그에 의존하는 파일들만 추적하여 2초 이내에 그래프를 다시 파싱합니다. 결과적으로 Claude는 전체 코드를 맹목적으로 읽는 대신 이 로컬 지식 그래프를 쿼리하여 무엇이 변경되었고 어떤 파일이 영향을 받는지 정확하고 빠르게 파악할 수 있게 됩니다.
code-review-graph를 도입함으로써 얻을 수 있는 이점은 매우 강력하며 실제 프로덕션 환경의 벤치마크 수치로도 증명되었습니다. 실제 프로젝트 저장소를 기준으로 코드 리뷰 시 평균 6.8배의 토큰을 절약할 수 있으며, 대규모 모노레포에서의 실시간 코딩 작업에서는 최대 49배까지 토큰 사용량을 획기적으로 줄일 수 있습니다. 또한, 관련 없는 코드가 컨텍스트에서 배제되면서 AI가 당면한 문제에만 온전히 집중할 수 있게 되어 코드 리뷰 품질 점수가 평균 7.2점에서 8.8점으로 향상되는 극적인 효과를 보였습니다.
클라우드 연동, 원격 분석(Telemetry), 회원 가입 등의 번거로운 절차가 일절 없으며, 프로젝트 내부의 .code-review-graph/ 디렉터리에 생성되는 단일 SQLite 파일만으로 모든 기능이 완벽하게 동작하므로 프라이버시와 보안을 중시하는 기업 환경에도 매우 적합합니다.
code-review-graph의 주요 기능
code-review-graph는 개발자의 작업 흐름을 방해하지 않으면서도 강력한 성능을 발휘하도록 다양한 최신 기술 스택과 아키텍처를 채택하고 있습니다. 프로젝트의 주요 아키텍처와 기술적 세부 사항은 다음과 같습니다.
Tree-sitter 기반 다국어 AST 파싱
code-review-graph의 핵심은 코드의 구문 분석(AST, Abstract Syntax Tree)을 빠르고 정확하게 수행하는 Tree-sitter에 있습니다. Tree-sitter는 현재 Python, TypeScript, JavaScript, Go, Rust, Java, C#, Ruby, Kotlin, Swift, PHP, C/C++ 등 총 12개의 주요 프로그래밍 언어를 공식적으로 지원합니다.
각 언어별 파서를 통해 코드 내의 모든 식별자(함수명, 클래스명 등)는 충돌을 방지하기 위해 정규화된 이름(Qualified names, 예: src/auth.py::AuthService.login)으로 노드화되어 그래프에 저장됩니다.
Blast Radius (영향 범위) 분석
특정 파일이나 함수가 변경되었을 때, 이 도구는 해당 변경이 프로젝트 전체에 미치는 파급 효과인 '영향 범위(Blast Radius)'를 계산합니다. NetworkX 라이브러리를 활용하여 넓이 우선 탐색(BFS) 방식으로 방향성 그래프를 순회하며, 변경된 함수를 호출하는 모든 호출자(Caller), 의존성 파일(Dependent), 그리고 관련 테스트 코드를 즉각적으로 식별합니다.
또한, 리소스 고갈을 방지하기 위해 BFS 탐색은 최대 500개 노드로 제한되도록 설계되었습니다. 이 정보를 통해 Claude는 전체 파일이 아닌, 정확히 영향을 받는 파일 집합만을 선별하여 읽을 수 있습니다.
SHA-256 기반 초고속 증분 업데이트 (Incremental Engine)
초기 그래프 빌드 이후에는 전체 저장소를 다시 스캔하지 않는 스마트한 증분 업데이트 엔진이 작동합니다. PostEdit 및 PostGit 훅(Hook)을 통해 파일 저장이나 Git 커밋 이벤트가 발생하면 백그라운드에서 즉시 업데이트가 트리거됩니다.
이때 SHA-256 해시 비교를 통해 내용이 실제로 수정되지 않은 파일은 파싱을 완전히 건너뛰며(Hash Skip), 변경된 파일과 그 종속 파일만 다시 파싱합니다. 약 2,900개의 파일이 있는 프로젝트에서도 이러한 증분 업데이트는 2초 이내에 완료되므로 개발자의 워크플로우를 전혀 지연시키지 않습니다.
로컬 우선주의와 SQLite 데이터베이스 최적화
모든 관계 데이터는 프로젝트 최상단 디렉터리가 아닌 .code-review-graph/ 디렉터리 내부의 단일 SQLite 파일에 저장되어 관리의 편의성을 높이고 .gitignore 설정 충돌을 방지합니다. 다수의 동시 읽기 작업을 원활하게 처리하기 위해 SQLite의 WAL(Write-Ahead Logging) 모드를 사용하며 별도의 외부 데이터베이스가 필요하지 않습니다.
옵션으로 제공되는 벡터 임베딩([embeddings]) 기능 역시 별도의 벡터 데이터베이스를 띄울 필요 없이 동일한 SQLite 파일 내에 바이너리 블롭(Binary Blobs) 형태로 안전하게 저장됩니다.
code-review-graph 설치 및 사용 방법
code-review-graph는 Python 3.10 이상 및 uv 패키지 관리자가 설치된 환경에서 동작합니다. 터미널에서 다음 명령어를 통해 플러그인 또는 패키지 형태로 손쉽게 설치할 수 있습니다.
Claude Code 플러그인으로 설치 (권장)
가장 간편한 방법으로, Claude Code 내부의 마켓플레이스를 통해 직접 설치하고 구성할 수 있습니다:
claude plugin marketplace add tirth8205/code-review-graph
claude plugin install code-review-graph@code-review-graph
Pip를 이용한 글로벌/가상환경 설치
또는, Python의 기본 패키지 관리자를 사용하여 설치할 수도 있습니다:
pip install code-review-graph
code-review-graph install
설치가 완료된 후 Claude Code를 재시작하고, 프로젝트 디렉터리에서 Claude에게 /build-graph 또는 아래와 같이 프롬프트를 입력하면 초기 지식 그래프 구축이 시작됩니다. 500개 파일 기준 초기 빌드에는 약 10초가 소요되며 이후로는 자동 업데이트됩니다.
"Build the code review graph for this project."
라이선스
code-review-graph 프로젝트는 오픈소스 커뮤니티의 발전을 위해 상업적 이용 및 수정이 자유로운 MIT License로 공개 및 배포되고 있습니다.
code-review-graph 관련 HackerNews 게시글
code-review-graph 프로젝트 GitHub 저장소
더 읽어보기
이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다. 
파이토치 한국 사용자 모임
이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일
로 보내드립니다! (기본은 Weekly지만 Daily로 변경도 가능합니다.)
아래
쪽에 좋아요
를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~ 