repo-graph

AI 코딩 어시스턴트를 위한 구조적 그래프 메모리. 코드베이스를 매핑하고, 구조를 기반으로 탐색하며, 중요한 부분만 읽으세요.

repo-graph는 LLM에게 코드베이스의 지도(엔티티, 관계, 흐름)를 제공하여, 모든 것을 먼저 읽지 않고도 올바른 파일로 이동할 수 있게 합니다.

전체 코드베이스로 LLM의 컨텍스트 창을 가득 채우거나(또는 올바르게 추측하기를 바라거나) 하는 대신, repo-graph는 무엇이 존재하고, 어떻게 연결되어 있으며, 진입점이 어디인지에 대한 가벼운 그래프를 구축합니다. LLM은 그래프를 쿼리하여 필요한 최소한의 파일 세트를 찾고, 해당 파일만 읽습니다.

데모

https://github.com/user-attachments/assets/a1e4171b-b225-40d4-9210-39453e14b76a

https://github.com/user-attachments/assets/fc3191e5-fc35-4bd7-8372-72af55995883

동일한 버그, 동일한 모델, 동일한 프롬프트 — 유일한 차이점은 repo-graph 설치 여부입니다.

작업: Go + Angular 모노레포(566개 노드, 620개 엣지)에서 반전된 비교 연산자 수정하기.

토큰 사용량 2.5배 감소. ~9배 더 빠름. 동일한 정확한 수정.

테스트 실행 방법

비교를 공정하게 유지하기 위해 두 실행 모두 동일한 조건을 사용했습니다:

• 동일한 모델: Claude Opus, 100% (Haiku 라우팅 없음)

• 동일한 프롬프트: "최근에 생성된 그룹이 닫힘으로 표시되고, 오래된 그룹은 열림으로 표시됩니다. 이는 반대입니다. 새 그룹은 멤버가 가입할 수 있도록 열려 있어야 합니다. 버그를 찾아 수정하세요."

• 새로운 컨텍스트: 각 실행은 이전 대화 없이 /clear에서 시작함

• 다른 도구 없음: 두 실행 모두 CLAUDE.md, 플러그인, 훅 및 기타 모든 MCP 서버를 제거함 — 유일한 변수는 repo-graph 설치 여부였음

• 힌트 없음: 프롬프트는 증상만 설명하고 위치는 설명하지 않음 — Claude가 스스로 group_controller.go:57을 찾아야 함

repo-graph가 없으면 Claude는 키워드를 grep하고, 파일을 읽고, 다시 grep하고, 더 많은 파일을 읽으며 결국 버그를 좁혀 나갑니다. repo-graph가 있으면 Claude는 flow("groups")를 호출하여 정확한 핸들러 함수와 파일을 가져와 읽고 수정합니다.

FastAPI, Gin, Hono, NestJS에 대한 미리 생성된 예제를 살펴보세요. 아무것도 설치하지 않고도 검사할 수 있는 실제 그래프 출력입니다.

문제점

코드 작업을 하는 LLM은 컨텍스트의 대부분을 방향을 잡는 데 낭비합니다:

• 관련 없는 것으로 판명된 파일 읽기

• 서로 다른 언어의 구성 요소 간 연결 누락

• 기능이 어디서 시작되고 무엇에 영향을 주는지 알지 못함

• 5개면 충분한데 50개의 파일을 로드함

이는 비용이 많이 들고 느리며, 코드베이스가 커질수록 더 심해집니다.

repo-graph의 해결책

repo-graph는 코드베이스를 한 번 스캔하여 다음의 그래프를 구축합니다:

• 엔티티: 모듈, 패키지, 클래스, 함수, 라우트, 서비스, 구성 요소

• 관계: 임포트, 호출, 핸들, 정의, 포함

• 흐름: 진입점에서 데이터 계층까지의 엔드투엔드 경로

그런 다음 LLM이 다음을 수행할 수 있도록 12개의 MCP 도구를 노출합니다:

1. 방향 잡기(Orient) — "이 저장소에는 어떤 언어가 있나요? 주요 기능은 무엇인가요?"

2. 탐색(Navigate) — "라우트에서 데이터베이스까지의 로그인 흐름을 추적하세요" / "UserService와 결제 API 사이의 최단 경로는 무엇인가요?"

3. 범위 지정(Scope) — "이 기능을 이해하려면 몇 줄을 읽어야 하나요?" / "이 버그 수정에 필요한 파일만 알려주세요"

4. 평가(Assess) — "이 함수를 변경하면 어떤 영향이 있나요?" / "어떤 파일이 가장 큰 유지보수 위험인가요?"

LLM은 수천 줄을 읽는 대신 수백 개의 토큰으로 구조적 컨텍스트를 얻습니다.

지원되는 언어

여러 분석기가 하나의 저장소와 일치할 수 있습니다(예: Go 백엔드 + Angular 프론트엔드 + SCSS). 각 분석기는 자신의 노드와 엣지를 하나의 통합된 그래프에 기여합니다.

설치

pip install mcp-repo-graph

Python 3.11+가 필요합니다. 유일한 런타임 의존성은 mcp[cli]입니다.

빠른 시작

1. 그래프 생성

repo-graph-generate --repo /path/to/your/project

이 명령은 코드베이스를 스캔하고 대상 저장소 내의 .ai/repo-graph/에 그래프 데이터를 씁니다.

2. AI 어시스턴트에 연결

MCP 구성에 추가하세요:

Claude Code (~/.claude/claude_code_config.json 또는 프로젝트 .mcp.json):

{
  "mcpServers": {
    "repo-graph": {
      "command": "repo-graph",
      "args": ["--repo", "/path/to/your/project"]
    }
  }
}

환경 변수 사용:

{
  "mcpServers": {
    "repo-graph": {
      "command": "repo-graph",
      "env": { "REPO_GRAPH_REPO": "/path/to/your/project" }
    }
  }
}

3. 사용하기

이제 AI 어시스턴트가 12개의 모든 도구에 액세스할 수 있습니다. 답변 가능한 예시 쿼리:

• "이 코드베이스는 무엇을 하나요?" -> status 도구

• "결제 흐름을 추적하세요" -> flow 도구

• "UserService를 변경하면 무엇이 깨지나요?" -> impact 도구

• "이 버그에 어떤 파일이 필요한가요?" -> minimal_read 도구

• "이 파일이 너무 큰데, 어떻게 분할해야 할까요?" -> split_plan 도구

• "인증 흐름을 시각적으로 보여주세요" -> graph_view 도구

4. git 훅으로 최신 상태 유지(권장)

repo-graph-generate를 pre-commit 훅에 추가하여 그래프가 자동으로 최신 상태로 유지되도록 하세요. 재생성에 LLM 컨텍스트를 소비할 필요가 없습니다:

# .git/hooks/pre-commit (or add to your existing hook)
#!/bin/sh
repo-graph-generate --repo .
git add .ai/repo-graph/

chmod +x .git/hooks/pre-commit

모든 커밋이 그래프를 최신 상태로 유지합니다. LLM은 generate에 토큰을 낭비하지 않고도 항상 최신 지도를 가집니다.

팁: 버전 관리에 그래프 데이터를 포함하고 싶지 않다면 .gitignore에 .ai/repo-graph/를 추가하고 git add 줄을 건너뛰세요. 그래프는 로컬에만 저장됩니다.

MCP 도구 참조

생성

탐색

컨텍스트 예산 관리

상태 분석

작동 원리

1. 감지(Detect) — scan_project_dirs()가 프로젝트 루트를 찾습니다(모노레포 레이아웃 포함: packages/*, apps/*, services/*, src/*). 각 분석기는 마커 파일을 확인합니다.

2. 스캔(Scan) — 일치하는 분석기가 정규식 휴리스틱을 사용하여 엔티티와 관계를 추출합니다. AST 파싱, 외부 툴체인, 빌드 단계가 필요 없습니다.

3. 병합(Merge) — 모든 분석기 결과가 하나의 그래프로 병합됩니다. 노드는 ID별로, 엣지는 (from, to, type)별로 중복 제거됩니다.

4. 제공(Serve) — MCP 서버가 그래프를 메모리에 로드하고 BFS 기반 탐색 도구를 노출합니다.

그래프 데이터 형식

생성된 파일은 대상 저장소 내의 .ai/repo-graph/에 저장됩니다:

• nodes.json — [{id, type, name, file_path}, ...]

• edges.json — [{from, to, type}, ...]

• flows/*.yaml — 순서가 지정된 단계 시퀀스가 있는 명명된 기능 흐름

• state.md — 빠른 방향 파악을 위한 사람이 읽을 수 있는 스냅샷

엣지 타입: imports, defines, contains, uses, calls, handles, handled_by, exports, includes.

새 분석기 추가

repo_graph/analyzers/<language>.py를 생성하세요:

from .base import AnalysisResult, Edge, LanguageAnalyzer, Node, scan_project_dirs, rel_path, read_safe

class MyLangAnalyzer(LanguageAnalyzer):

    @staticmethod
    def detect(repo_root):
        # Check for language marker files
        return any(
            (d / "my-marker").exists()
            for d in scan_project_dirs(repo_root)
        )

    def scan(self):
        nodes, edges = [], []
        # ... scan files, extract entities, build relationships ...
        return AnalysisResult(
            nodes=nodes,
            edges=edges,
            state_sections={"MyLang": f"{len(nodes)} entities\n"},
        )

    # Optional: file-level analysis for bloat_report / split_plan
    def supported_extensions(self):
        return {".mylang"}

    def analyze_file(self, file_path):
        # Return dict with function/method sizes, class counts, etc.
        pass

    def format_bloat_report(self, analysis):
        # Format the analysis dict into a human-readable string
        pass

_analyzer_classes()에 추가하여 analyzers/__init__.py에 등록하세요.

라이선스

MIT

지원

repo-graph가 시간을 절약해 주었다면 커피 한 잔을 사주시는 것을 고려해 보세요.