Graphify로 코드베이스를 지식 그래프로 전환하기
코드베이스가 커지면 에이전트가 파일을 읽느라 컨텍스트를 다 씁니다. LLM 없이 코드 그래프를 만드는 Graphify의 원리와 query·path·explain 명령, 벡터 RAG와의 차이를 정리했습니다.
목차
- 개요
- 지식 그래프 전환의 원리
- 설치와 첫 그래프 빌드
- 에이전트 질의 — query · path · explain
- 벡터 RAG와의 차이 및 트레이드오프
- 운영 환경 적용: Git 훅·증분 업데이트·민감 정보 관리
- 맺음말
개요
문제 배경: 파일 순회에 갇힌 AI 에이전트
파일이 수천 개를 넘으면 에이전트 컨텍스트 소진이 실질적 한계에 달합니다. Graphify가 LLM 비용 없이 지식 그래프를 빌드하고 query·path·explain 세 명령으로 구조를 탐색하는 방법과, 벡터 RAG 대신 선택해야 할 때와 그렇지 않을 때 판단 기준을 정리했습니다. Claude Code든 Cursor든 현재 주류 에이전트는 코드를 이해할 때 Read나 Glob으로 파일을 하나씩 열거나, 검색어로 일치 구간을 끌어오는 방식을 씁니다. 수십만 줄 이상의 코드베이스에서 이 방식은 두 가지 벽에 부딪힙니다. 첫째, 컨텍스트 윈도우가 빠르게 소진됩니다. 관련 없는 파일까지 읽어 들이면서 토큰 비용이 의도치 않게 높아집니다. 둘째, 파일 단위 검색은 개념 간 구조적 관계를 포착하지 못합니다. UserService가 AuthMiddleware를 어떤 경로로 호출하는지, PaymentSchema와 OrderModel이 어떻게 연결되어 있는지는 파일 몇 개를 읽어서는 온전히 파악하기 어렵습니다.
Graphify는 이 문제를 코드베이스 전체를 질의 가능한 지식 그래프로 변환해 해결합니다. 코드, 문서, SQL 스키마, 설정 파일, PDF까지 단일 그래프로 묶고, 에이전트가 원본 파일을 순회하는 대신 그래프를 질의하도록 유도합니다. 2026년 10월 기준 GitHub 스타 약 12만 8천 개(라이선스 Apache-2.0)를 기록한 오픈소스 프로젝트로, Claude Code, Cursor, Codex, Gemini CLI 등에서 /graphify 스킬로 바로 호출할 수 있습니다(Codex에서는 $graphify).
기존 방식의 한계
코드 탐색 도구의 전통적인 접근법은 크게 두 갈래입니다. 첫 번째는 키워드·정규식 검색입니다. grep이나 ripgrep을 에이전트에 연결하는 방식으로, 문자열 일치 이상의 정보를 제공하지 못하고 개념 간 의미 연결을 보여 주지 않습니다. 두 번째는 벡터 임베딩 기반 RAG입니다. 코드 청크를 임베딩해 유사도 검색으로 관련 스니펫을 가져옵니다. 이 방식은 의미론적 유사도를 다루는 데 유리하지만, 코드의 구조적 관계(호출 관계, 상속, 임포트 체인)를 손실 없이 표현하기 어렵고, 인덱스를 재구축할 때마다 임베딩 API 비용이 발생합니다.
Graphify는 임베딩 없이 tree-sitter AST 파싱으로 그래프를 결정론적으로(deterministically) 구축합니다. 두 기존 방식과 어떻게 다른지는 다음 섹션에서 동작 원리와 함께 살펴봅니다.
코드베이스 하나가 세 가지 산출물로 변환되며, 에이전트는 원본 파일 대신 graph.json을 질의합니다.
지식 그래프 전환의 원리
tree-sitter AST 파싱
Graphify가 코드 그래프를 만드는 핵심 엔진은 tree-sitter입니다. tree-sitter는 증분 파서(incremental parser) 라이브러리로, 문법이 정의된 언어라면 소스 파일을 AST(Abstract Syntax Tree)로 변환합니다. Graphify는 이 AST에서 함수 정의, 클래스 선언, 임포트 문, 호출 표현식을 추출해 노드와 엣지로 변환합니다. README 기준 약 40개 언어를 지원합니다.
이 단계에서 중요한 특성은 결정론적 실행입니다. 같은 소스를 두 번 파싱하면 항상 같은 그래프가 나옵니다. LLM을 쓰지 않으므로 네트워크 요청이 없고, 외부 API 비용도 발생하지 않습니다. 코드 그래프를 만드는 과정 전체가 로컬에서 완결됩니다. 이 결정론적 특성은 CI 파이프라인에서 그래프를 자동 재빌드할 때 일관성을 보장하는 기반이 됩니다. 매번 같은 결과를 보장할 수 없는 임베딩 방식과 달리, 소스만 동일하다면 그래프도 동일합니다.
문서·PDF·이미지·영상은 사정이 다릅니다. 비정형 자료에서 의미를 추출하는 단계에서는 어시스턴트 모델이나 별도로 설정한 API 키가 필요합니다. Graphify는 ollama, openai, gemini, anthropic, bedrock 등 여러 백엔드를 지원해 조직의 기존 LLM 계약을 그대로 활용할 수 있습니다.
코드 노드는 LLM 없이, 문서·PDF 노드는 어시스턴트 모델을 거쳐 같은 그래프에 합류합니다.
EXTRACTED와 INFERRED 엣지 태그
Graphify가 그래프에 추가하는 모든 엣지에는 신뢰 태그가 붙습니다. EXTRACTED는 소스에 명시된 관계입니다. import UserService from './user'라는 구문이 실제로 존재하면 해당 임포트 엣지는 [EXTRACTED]가 됩니다. INFERRED는 Graphify가 맥락을 분석해 연결한 관계입니다. 명시적 참조는 없지만 네이밍 패턴이나 공유 타입 시그니처로 연결이 추정될 때 붙습니다.
이 구분이 실제 프로젝트에서 중요한 이유는 에이전트가 그래프를 신뢰해 행동을 결정할 때 연결의 강도를 알아야 하기 때문입니다. INFERRED 엣지를 따라 수정 범위를 결정하면 잘못된 파일을 건드릴 위험이 생깁니다. README 예시에서도 graphify explain "APIRouter" 결과에 각 연결마다 [EXTRACTED] 또는 [INFERRED] 태그가 명시되어 있어, 에이전트가 연결의 신뢰도를 인식하며 탐색할 수 있습니다.
엣지 신뢰도를 구분함으로써 에이전트는 명시적 관계와 추정 관계를 다르게 다룰 수 있습니다.
커뮤니티 감지와 God 노드
Graphify는 그래프를 빌드한 뒤 Leiden 알고리즘으로 커뮤니티를 자동 분할합니다. Leiden은 LLM 없이 그래프 위상(topology)만으로 밀집 연결 집합을 찾아냅니다. 이 커뮤니티가 코드베이스의 하위 시스템에 해당합니다. 도메인 지식 없이 대형 모노리포를 처음 탐색할 때, 어느 파일이 어느 도메인에 속하는지를 빠르게 파악하는 단서가 됩니다. 레이블 역시 LLM 없이 자동 생성됩니다.
God 노드는 연결 수(degree)가 가장 높은 개념들입니다. God 노드에 해당하는 클래스나 모듈은 변경 시 파급 범위가 넓습니다. GRAPH_REPORT.md에 이 목록이 정리되므로, 코드 리뷰나 리팩터링 전에 에이전트가 참조하면 의도치 않은 영향 범위를 줄이는 데 도움이 됩니다. Degree가 높은 노드에 손을 대기 전에 이것이 God 노드임을 알고 접근하는 것과 모르고 접근하는 것은 안전성에서 차이가 납니다.
설치와 첫 그래프 빌드
설치 절차
Graphify를 설치하는 데 필요한 환경은 Python 3.10 이상과 uv(또는 pipx)입니다. PyPI 패키지 이름이 graphifyy(y가 두 개)라는 점에 주의해야 합니다. 이름이 비슷한 다른 패키지가 존재하며 무관합니다. CLI 명령어 자체는 graphify입니다.
설치 후 graphify install을 실행하면 시스템 수준으로, graphify install --project를 실행하면 현재 저장소 단위로 설치됩니다. 저장소 단위 설치를 선택하면 .graphify/ 설정 파일이 프로젝트 루트에 생성되고, 팀 전체가 같은 그래프 설정을 공유할 수 있습니다. 협업 프로젝트라면 --project 방식을 선택해 설정을 버전 관리에 포함시키는 것이 권장됩니다.
팀 단위 프로젝트라면 저장소 단위 설치로 그래프 설정을 공유합니다.
첫 번째 그래프 빌드
설치 후 Claude Code나 Gemini CLI 등 지원 에이전트에서 /graphify .를 실행하면 현재 디렉터리를 대상으로 그래프가 빌드됩니다. Codex에서는 $graphify .로 호출합니다. 빌드가 완료되면 graphify-out/ 디렉터리 아래 세 파일이 생성됩니다.
graph.html은 브라우저에서 노드를 클릭하고 필터·검색할 수 있는 인터랙티브 시각화입니다. GRAPH_REPORT.md는 핵심 개념 목록, 의외의 연결, 추천 질문을 정리한 보고서로, 프로젝트를 처음 접하는 사람이 구조를 파악하는 데 유용합니다. graph.json은 전체 그래프 데이터로, 에이전트가 원본 파일을 다시 읽지 않고 직접 질의하는 대상입니다.
아래는 FastAPI 코드베이스에서 그래프를 빌드한 뒤 특정 개념을 설명하도록 질의하는 예시입니다(README에 수록된 예시를 기반으로 합니다).
# 그래프 빌드 후 APIRouter 노드 설명 요청
graphify explain "APIRouter"README 예시 기준으로 routing.py L2210, Degree 47이 출력되며 각 연결마다 [EXTRACTED] 또는 [INFERRED] 태그와 관계 유형이 함께 표시됩니다. 명령 한 번으로 이 개념이 코드베이스에서 얼마나 중심적인 역할을 하는지와 어떤 모듈들과 연결되는지를 파악할 수 있습니다. 파일을 일일이 열지 않아도 됩니다.
에이전트가 항상 그래프를 쓰도록 설정
그래프를 빌드했더라도 에이전트가 기존 파일 읽기 방식으로 돌아가면 효과가 절반입니다. Graphify는 이를 방지하는 연동 설정을 제공합니다. graphify claude install을 실행하면 Claude Code가 Read나 Glob으로 파일을 하나씩 열기 전에 그래프 경로로 먼저 유도되는 훅이 설치됩니다. Gemini CLI도 같은 방식으로 연결됩니다. Codex나 Cursor 같은 에이전트는 AGENTS.md나 .cursor/rules 같은 지침 파일로 동일한 효과를 만듭니다.
연동을 제거할 때는 graphify uninstall을 사용하고, --purge 플래그를 추가하면 graphify-out/ 디렉터리도 함께 삭제됩니다.
에이전트 질의 — query · path · explain
세 가지 질의 명령의 역할
Graphify는 에이전트가 그래프를 탐색할 때 쓰는 세 가지 질의 명령을 제공합니다. 각각의 역할이 명확히 구분됩니다.
graphify query "<질문>"은 자연어 질문을 받아 해당 범위의 하위 그래프를 반환합니다. 전체 그래프가 아니라 질문과 관련된 노드와 엣지만 추출하므로 에이전트의 컨텍스트 소비를 줄입니다. 기능 탐색이나 버그 원인 추적처럼 범위가 열려 있는 질문에 적합합니다.
graphify path A B는 두 개념 사이의 최단 경로를 찾습니다. README 예시에서 graphify path "FastAPI" "ModelField"는 3 hops 최단 경로를 반환합니다. 의존성 체인을 파악하거나, 변경이 전파되는 경로를 추적할 때 유용합니다. 영향 범위 분석이나 테스트 범위 결정에도 쓸 수 있습니다.
graphify explain "<개념>"은 단일 노드의 모든 연결을 펼쳐 보여 줍니다. 파일 위치, Degree, 연결 유형, 신뢰 태그가 한 번에 출력됩니다. 처음 보는 클래스나 모듈의 전체 맥락을 빠르게 파악하는 데 가장 직접적인 명령입니다.
세 명령은 목적이 다르므로 에이전트가 질의 의도에 따라 적절히 선택합니다.
하위 그래프 반환의 의미
graphify query가 전체 그래프 대신 하위 그래프를 반환하는 설계는 토큰 효율과 직결됩니다. 수십만 노드를 가진 그래프 전체를 에이전트 컨텍스트에 올리면 오히려 파일을 순회하는 것보다 더 많은 토큰이 소비될 수 있습니다. 질문 범위에 맞는 서브그래프만 추출하면 에이전트는 필요한 구조 정보만 얻고, 나머지는 그래프에 남겨 둡니다. Graphify Cloud가 내세우는 "에이전트 토큰 소비 80% 절감"은 이 구조에서 나오는 주장이지만, 해당 수치는 Cloud 마케팅 문구이고 독립 검증이 없으므로 현업 결과와 다를 수 있습니다.
# NOTE: / # WHY: 주석과 ADR 연동
Graphify는 소스 파일에 작성된 # NOTE: 또는 # WHY: 주석을 별도 노드로 만들어 그래프에 연결합니다. ADR(Architecture Decision Record)이나 RFC 문서를 참조하는 주석도 해당 문서 노드와 엣지로 이어집니다. 이 기능은 코드에 녹아 있는 설계 의사결정을 그래프 위에서 탐색 가능하게 만들어 줍니다.
특정 클래스가 왜 그런 구조를 갖는지를 묻는 에이전트 질의가 들어오면, # WHY: 노드를 거쳐 관련 ADR로 이어지는 경로가 반환될 수 있습니다. 코드베이스의 설계 의도를 추적하는 경로가 생기는 것입니다. ADR을 코드 주석으로 참조하는 관행을 팀이 유지할수록 그래프의 설명 능력이 높아집니다.
코드와 설계 문서가 같은 그래프 위에서 연결되면 에이전트가 "왜 이렇게 짰는지"를 코드 맥락 안에서 파악할 수 있습니다.
벡터 RAG와의 차이 및 트레이드오프
두 접근법의 핵심 차이
벡터 임베딩 기반 RAG와 Graphify의 그래프 접근법은 코드 탐색 문제를 서로 다른 방식으로 풉니다. 벡터 RAG는 텍스트 조각을 고차원 공간에 투영해 의미 유사도로 검색합니다. 개념의 이름이나 주석이 다르더라도 의미가 가까우면 같은 버킷에 묶일 수 있어, 자연어 서술이 풍부한 문서 검색에서 강점이 있습니다. 단, 코드의 구조적 관계(호출 체인, 상속, 임포트 의존성)는 임베딩에 잘 포착되지 않습니다. A가 B를 호출한다는 사실이 유사도 벡터에 직접 반영되지 않기 때문입니다.
Graphify는 AST에서 추출한 명시적 관계를 그래프 엣지로 저장하므로 구조적 탐색에서 유리합니다. "이 함수를 호출하는 모든 경로", "이 클래스를 상속하는 모든 클래스"처럼 관계 탐색이 핵심인 질의에서 그래프 순회가 훨씬 직접적입니다. 반면 자연어 서술 위주의 문서에서 의미론적 유사도를 기준으로 검색해야 할 때는 벡터 RAG가 여전히 유리합니다.
| 항목 | 벡터 RAG | Graphify |
|---|---|---|
| 인덱스 방식 | 임베딩 벡터 | AST 파싱 → 그래프 |
| 코드 빌드 비용 | 임베딩 API 비용 | LLM 크레딧 0 |
| 구조 관계 탐색 | 약함 | 강함 |
| 의미 유사도 검색 | 강함 | 보통 |
| 결정론적 재빌드 | API 의존 | 로컬 완결 |
| 언어 지원 | 모델 의존 | tree-sitter 약 40개 |
| 주의점 | 코드 구조 손실 | 비정형 자연어에 약함 |
README 벤치마크 해석
Graphify README에는 제작사가 직접 측정한 벤치마크가 수록되어 있습니다. LOCOMO(n=300) recall@10에서 0.497(mem0 0.048, supermemory 0.149), LongMemEval-S(n=50)에서 76%(dense RAG와 동률)입니다. QA 정확도는 45.3%로, 비교 대상인 supermemory(49.7%)보다 낮습니다. 이 수치는 독립 검증이 이루어지지 않은 제작사 측정값입니다. 특히 메모리 벤치마크(LOCOMO, LongMemEval)는 코드베이스 탐색보다 대화·문서 메모리 시나리오에 가깝고, QA 정확도가 supermemory보다 낮다는 점도 함께 고려해야 합니다. 실제 프로젝트에서 도입 효과를 판단하려면 자체 코드베이스로 별도 측정이 필요합니다.
질의 성격에 따라 그래프 순회와 벡터 검색은 서로 다른 강점을 가집니다.
Archify와의 역할 구분
같은 생태계에는 Archify라는 스킬도 있습니다. Archify는 코드베이스를 인터랙티브 아키텍처 다이어그램 HTML로 그려 주는 에이전트 스킬입니다. 한 문장으로 구분하자면 "사람이 보는 그림"이 Archify, "에이전트가 질의하는 그래프"가 Graphify입니다. 두 도구는 목적이 달라 함께 사용하는 경우가 많습니다. 온보딩 시 Archify로 전체 아키텍처를 시각화해 팀이 공유 맥락을 갖추고, 이후 에이전트 작업에는 Graphify를 연동하는 방식이 하나의 패턴입니다.
운영 환경 적용: Git 훅·증분 업데이트·민감 정보 관리
그래프 최신화 — 훅과 증분 업데이트
코드베이스는 끊임없이 변합니다. 그래프가 오래된 상태로 유지되면 에이전트가 이미 사라진 함수나 변경된 의존성을 참조하게 됩니다. Graphify는 이를 위해 두 가지 전략을 제공합니다.
graphify hook install을 실행하면 커밋이나 브랜치 전환 시 자동으로 그래프를 재빌드하는 Git 훅이 설치됩니다. 매 커밋마다 전체 그래프를 다시 빌드하면 대형 저장소에서는 시간이 상당히 걸릴 수 있습니다. --update 플래그가 이 문제를 다룹니다. graphify --update는 변경된 파일만 재추출해 그래프를 갱신합니다. 수십만 파일 규모의 모노리포에서는 전체 재빌드 대신 증분 업데이트가 현실적인 선택입니다.
대형 저장소에서는 증분 업데이트가 훅 실행 시간을 크게 줄여 줍니다.
문서·비정형 자료 연동 시 주의점
코드 그래프는 LLM 없이 빌드되지만, PDF·이미지·영상 같은 비정형 자료를 그래프에 추가하려면 어시스턴트 모델이나 별도로 설정한 API 키가 필요합니다. 문서가 많거나 영상 자막 추출(faster-whisper + yt-dlp)이 포함될 경우 이 단계에서 API 비용이 발생합니다. 비정형 자료를 포함할지 여부를 미리 판단하고, 필요 없는 항목은 .graphifyignore나 --exclude로 제외하는 것이 좋습니다. .gitignore는 자동으로 존중됩니다.
extras 기능(pdf, office, video, mcp, neo4j, falkordb 등)은 각 용도에 맞춰 별도 설치가 필요합니다. 특히 mcp extras를 설치하면 MCP stdio 서버로 Graphify를 구동할 수 있어, MCP를 지원하는 에이전트 프레임워크에 직접 연결됩니다. neo4j나 falkordb extras를 활용하면 그래프를 외부 그래프 데이터베이스로 내보낼 수도 있습니다.
저장소 병합과 민감 정보 관리
graphify merge-graphs는 여러 저장소의 그래프를 하나로 합칩니다. 마이크로서비스 아키텍처에서 서비스 간 의존성을 단일 그래프로 추적할 때 유용하지만, 합쳐지는 그래프가 늘어날수록 God 노드와 INFERRED 엣지도 함께 늘어납니다. 서비스 경계를 넘는 추정 연결이 많아지면 에이전트가 잘못된 경로로 안내될 위험이 높아집니다. 병합 후에는 신뢰도가 낮은 엣지를 검토하는 과정이 필요합니다.
보안 측면에서는 코드베이스에 하드코딩된 시크릿, 개인정보, 내부 인프라 정보가 섞여 있을 수 있다는 점을 염두에 두어야 합니다. 환경 변수 파일이나 내부 설정 파일은 .graphifyignore로 명시적으로 제외하는 것이 권장됩니다. 그래프 빌드 자체는 로컬에서 완결되지만, 비정형 자료 처리 단계에서 외부 API로 내용이 전송될 수 있으므로 민감 문서는 이 경로를 차단해야 합니다.
저장소를 병합할수록 추정 연결이 늘어나므로 병합 후 그래프 품질 검토가 중요합니다.
맺음말
핵심 요약
Graphify는 코드베이스를 tree-sitter AST 파싱으로 결정론적으로 분석하고, 코드·문서·PDF를 단일 지식 그래프로 통합합니다. 앞서 설명한 대로 코드 그래프 빌드는 LLM을 거치지 않으며, 엣지마다 EXTRACTED/INFERRED 신뢰 태그를 부여해 에이전트가 관계의 강도를 인식하며 탐색할 수 있게 합니다. query, path, explain 세 명령으로 전체 파일 순회 없이 필요한 구조 정보만 꺼냅니다. Leiden 커뮤니티 감지와 God 노드 목록은 대형 코드베이스를 처음 접할 때 구조를 빠르게 파악하는 수단이 됩니다.
# WHY: 주석과 ADR을 그래프 노드로 연결하는 기능은 코드와 설계 의도를 같은 탐색 공간 안에 묶어 줍니다. Git 훅과 증분 업데이트로 그래프를 코드베이스와 동기화하는 파이프라인을 자동화할 수 있고, MCP·neo4j 등 extras를 통해 기존 에이전트 프레임워크에 통합하는 경로도 열려 있습니다.
적용 판단 기준
Graphify가 효과적인 상황은 크게 세 가지입니다. 코드베이스 규모가 커서 AI 에이전트가 파일을 순회할 때 컨텍스트 소비가 문제가 될 때, 호출 체인·상속·임포트 의존성처럼 구조적 관계 탐색이 잦은 프로젝트일 때, ADR이나 설계 문서가 코드와 분리되어 있고 연결이 끊기는 것이 아쉬울 때입니다.
반면 의미 유사도 검색이 핵심이거나 코드베이스 규모가 작다면 벡터 RAG나 단순 파일 검색으로도 충분할 수 있습니다. 벤치마크 수치는 제작사 자체 측정이므로 실제 프로젝트 특성에 따라 결과가 다를 수 있다는 점을 감안하고, 소규모 파일럿으로 먼저 효과를 검증하는 접근이 현실적입니다. 오픈소스(Apache-2.0)이므로 Graphify Cloud 없이도 CLI만으로 전체 기능을 사용할 수 있습니다.
규모와 탐색 패턴 두 가지가 모두 해당할 때 Graphify의 효과가 가장 분명하게 드러납니다.