alpaka206

code-review-graph: AI 코드 리뷰의 컨텍스트를 줄이는 방법

date
Apr 20, 2026
slug
code-review-graph-ai-code-review-context
author
status
Public
tags
Blog
Github
Study
AI
summary
Tree-sitter와 MCP로 코드베이스를 그래프화해 Claude Code와 Codex의 리뷰 컨텍스트를 줄이는 code-review-graph의 작동 원리와 적용법을 정리합니다.
type
Post
thumbnail
category
📗 Docs
updatedAt
May 5, 2026 02:50 PM
AI 코드 리뷰를 하다 보면 생각보다 큰 낭비가 자주 생깁니다. PR에서 실제로 바뀐 코드는 몇 줄인데, 에이전트는 관련 가능성이 있는 파일을 넓게 읽기 시작합니다. 레포가 커질수록 이 문제는 더 커지고, 토큰 비용도 늘어나고, 모델이 봐야 할 맥락도 흐려집니다.
code-review-graph는 이 문제를 조금 다른 방식으로 해결한다고 해서 공부해보았습니다. 코드 전체를 매번 읽히는 대신, 로컬에서 코드베이스를 구조화된 그래프로 만들어 두고 Claude Code나 Codex 같은 AI 코딩 도구가 필요한 부분만 먼저 조회하게 만듭니다.

code-review-graph가 하는 일

한 줄로 정리하면, code-review-graph는 코드베이스를 Tree-sitter로 파싱해서 함수, 클래스, 파일, 테스트, 호출 관계를 그래프 DB에 저장하고, 그 그래프를 MCP 서버로 노출하는 도구입니다.
여기서 중요한 포인트는 “AI가 코드를 더 많이 읽게 하는 것”이 아니라 “읽기 전에 영향 범위를 좁히게 하는 것”입니다.
예를 들어 로그인 함수가 바뀌었다면 에이전트가 전체 src를 훑는 대신 이런 질문을 먼저 할 수 있습니다.
  • 이 함수의 caller는 누구인가요?
  • 이 파일을 import하는 파일은 무엇인가요?
  • 이 변경으로 영향을 받을 flow는 무엇인가요?
  • 관련 테스트는 있나요?
  • 변경된 함수 중 risk가 높은 것은 무엇인가요?
이 질문에 대한 답을 그래프에서 먼저 받은 뒤, 정말 필요한 파일만 읽는 방식입니다.

내부 작동 방식

전체 흐름은 단순합니다.
Repository
-> Tree-sitter parsing
-> File/Class/Function/Test nodes 추출
-> CALLS/IMPORTS_FROM/INHERITS/TESTED_BY edges 추출
-> SQLite graph DB 저장
-> MCP tools로 Claude Code, Codex에 제공
처음에는 전체 빌드를 합니다.
code-review-graph build
이때 git ls-files 기준으로 추적 중인 파일을 수집하고, .gitignore와 .code-review-graphignore에 걸리는 파일은 제외합니다. 각 파일은 Tree-sitter로 파싱되고, 결과는 .code-review-graph/graph.db에 저장됩니다.
이후에는 매번 전체를 다시 만들지 않습니다.
code-review-graph update
update는 git diff로 변경 파일을 찾고, 해당 파일을 import하거나 의존하는 파일만 추가로 확인합니다. 파일 hash가 이전과 같으면 skip하기 때문에 큰 레포에서도 변경분 중심으로 그래프를 갱신할 수 있습니다.

핵심 개념: Blast Radius

code-review-graph의 핵심은 blast radius 분석입니다. blast radius는 이번 변경이 영향을 줄 수 있는 코드 범위를 의미합니다.
구현상으로는 변경된 파일 안의 graph node를 seed로 잡고 BFS를 수행합니다. 이때 양방향으로 탐색합니다.
  • forward: 이 노드가 호출하거나 의존하는 대상
  • reverse: 이 노드를 호출하거나 의존하는 대상
기본 depth는 2 hop입니다. 결과로 impacted nodes, impacted files, 연결 edge를 얻습니다.
주의할 점은 이 결과가 “반드시 깨지는 파일 목록”은 아니라는 점입니다. 정적 분석 기반이므로 동적 호출, DI, framework convention, reflection 같은 패턴은 놓칠 수 있습니다. 그래서 이 도구는 정답 생성기라기보다 리뷰 후보군을 줄이는 pre-filter에 가깝습니다.

Risk Score는 무엇을 보는가

detect_changes 계열 도구는 변경된 함수나 클래스를 찾아 risk score를 계산합니다. 이 점수는 코드 품질 점수라기보다 리뷰 우선순위에 가깝습니다.
주요 기준은 다음과 같습니다.
  • 중요한 실행 flow에 포함되는가
  • 여러 community에서 호출되는가
  • 테스트가 부족한가
  • auth, token, password 같은 보안 관련 이름인가
  • caller가 많은가
점수가 높은 항목은 사람이 먼저 보거나, AI에게 source snippet을 더 읽게 만들면 됩니다.

Claude Code에 적용하기

Claude Code는 이 도구와 가장 자연스럽게 붙습니다. 설치하면 .mcp.json, CLAUDE.md, .claude/skills, hooks 설정까지 자동으로 만들어집니다.
pipx install code-review-graph
cd /path/to/repo
code-review-graph install --platform claude-code -y
code-review-graph build
Claude Code에서는 slash command로 사용할 수 있습니다.
/code-review-graph:build-graph
/code-review-graph:review-delta
/code-review-graph:review-pr
자연어로 요청할 때는 이렇게 말하면 됩니다.
code-review-graph를 먼저 사용해서 현재 변경사항을 리뷰해줘.
get_minimal_context_tool로 시작하고,
risk가 높으면 detect_changes_tool과 get_review_context_tool로 확장해줘.
전체 파일을 먼저 읽지 말고 impacted files 중심으로 봐줘.

Codex에 적용하기

Codex도 MCP를 사용할 수 있으므로 같은 방식으로 붙일 수 있습니다.
pipx install code-review-graph
cd /path/to/repo
code-review-graph install --platform codex -y
code-review-graph build
자동 설치는 ~/.codex/config.toml에 MCP 서버를 추가합니다.
[mcp_servers.code-review-graph]
command = "uvx"
args = ["code-review-graph", "serve"]
type = "stdio"
여러 레포를 오가거나 실행 위치가 불명확하면 --repo를 명시하는 편이 안전합니다.
[mcp_servers.code-review-graph]
command = "uvx"
args = ["code-review-graph", "serve", "--repo", "C:\\path\\to\\repo"]
type = "stdio"
Codex에서는 Claude Code처럼 slash command 경험이 자동으로 붙는 것은 아니므로, 레포 루트의 AGENTS.md에 graph-first 지침을 추가하는 것을 권장합니다.
## code-review-graph 사용 규칙

코드 탐색, 리뷰, 영향 범위 분석을 할 때는 파일 전체를 먼저 읽지 말고 code-review-graph MCP 도구를 우선 사용합니다.

권장 순서:
1. get_minimal_context_tool(task="<작업 설명>")
2. detect_changes_tool(base="origin/main", detail_level="minimal")
3. risk가 높으면 get_review_context_tool 또는 get_impact_radius_tool로 확장합니다.
4. 부족한 경우에만 rg, file read로 fallback합니다.

언제 효과가 큰가

이 도구는 모든 상황에서 무조건 이득이 되는 도구는 아닙니다. 작은 단일 파일 변경에서는 그래프 메타데이터가 원본 파일보다 더 클 수 있습니다. 반대로 큰 레포, 모노레포, 다중 파일 PR에서는 효과가 커집니다.
특히 다음 상황에 잘 맞습니다.
  • PR 리뷰 전에 영향 범위를 빠르게 좁히고 싶을 때
  • 리팩터링 전 caller/callee/test 관계를 확인하고 싶을 때
  • 신규 입사자가 코드 구조를 파악해야 할 때
  • 모노레포에서 관련 파일을 사람이 직접 지정하기 어려울 때

도입 시 주의할 점

첫째, .code-review-graph/는 로컬 DB이므로 커밋하면 안 됩니다. 대신 .code-review-graphignore는 팀 공통 규칙으로 커밋하는 편이 좋습니다.
둘째, graph freshness가 중요합니다. 그래프가 오래되면 영향 범위도 틀릴 수 있습니다.
code-review-graph status
code-review-graph update
또는 watch mode를 사용할 수 있습니다.
code-review-graph watch
셋째, 기본 동작은 로컬이지만 cloud embedding 옵션을 켜면 코드 서명이 외부 API로 나갈 수 있습니다. 회사 코드라면 embedding은 끄거나 local provider, 또는 사내 self-hosted endpoint를 쓰는 편이 안전합니다.

정리

code-review-graph는 AI 코드 리뷰의 컨텍스트 문제를 꽤 현실적인 방식으로 다룹니다. 모델을 더 똑똑하게 만드는 도구라기보다는, 모델이 읽기 전에 무엇을 봐야 하는지 정리해 주는 로컬 코드 인덱스에 가깝습니다.
Claude Code에서는 자동화가 잘 되어 있어 바로 적용하기 좋고, Codex에서도 MCP 설정과 AGENTS.md 지침을 추가하면 충분히 활용할 수 있습니다.
다만 정적 분석 기반이라는 한계는 분명합니다. 이 도구만으로 리뷰 품질이 보장되지는 않습니다. 대신 테스트, 타입체크, CI, 사람 리뷰와 함께 사용하면 AI가 불필요한 파일을 덜 읽고 중요한 변경부터 보게 만드는 데 도움이 됩니다.

참고

Back to blog
Newer postYouTube Data API v3 활용법2026년 4월 27일Older postHarness: Claude Code 에이전트 팀을 설계하는 방법2026년 4월 13일
RelatedYouTube Data API v3 활용법2026년 4월 27일RelatedHarness: Claude Code 에이전트 팀을 설계하는 방법2026년 4월 13일RelatedAI 더빙 서비스2026년 3월 12일