Graphify: 코드베이스 지식 그래프 도구

1. 프로젝트 개요

Graphify는 문서, SQL 스키마, 구성 파일, PDF를 포함한 모든 코드베이스를 질의 가능한 지식 그래프로 변환하여, 개발자가 파일을 일일이 뒤지거나 불투명한 의미론적 검색에 의존하는 대신 설명 가능한 그래프 탐색을 통해 크고 낯선 프로젝트를 이해할 수 있게 해줍니다.

2. 배경 및 포지셔닝

대규모 코드베이스를 이해하는 전통적인 방법은 파일을 수동으로 뒤지거나, 두 코드 조각이 왜 관련이 있는지 이유를 설명하지 않고 "유사한" 결과를 반환하는 벡터 임베딩 검색에 의존하는 것이었습니다. Graphify는 이러한 격차를 해소하기 위해 만들어졌습니다: 결정론적 AST 도구(tree-sitter)로 소스 코드를 로컬에서 파싱하고, 탐색·질의·설명이 가능한 실제 엔티티 및 관계 그래프를 구축합니다.

이 프로젝트의 핵심 사명은 투명성입니다. 추출된 모든 관계는 EXTRACTED(소스에 명시적으로 존재, 예: import 또는 함수 호출) 또는 INFERRED(graphify 자체 분석으로 해결)로 태그가 지정되므로, 개발자는 연결이 코드에서 나온 사실인지 파생된 결론인지 항상 알 수 있습니다.

일반적인 RAG 방식 코드 어시스턴트와 비교하여, graphify는 명시적으로 벡터 인덱스가 아님을 표방합니다 — 핵심 그래프 구축에는 임베딩이나 벡터 저장소가 전혀 사용되지 않습니다. 코드 분석은 tree-sitter를 통해 전적으로 로컬 머신에서 실행되며, 소스 코드 그래프 구축에는 LLM 호출과 API 크레딧이 전혀 필요 없습니다. 선택적 AI 백엔드는 PDF, 이미지, 비디오와 같은 비코드 형식의 의미론적 추출에만 호출됩니다.

3. 기능 분류

🕸️ 그래프 구축 — 핵심 기능, 프로젝트에서 지식 그래프 생성

갓-노드 감지(코드베이스에서 가장 많이 연결된 개념 식별)
Leiden 기반 클러스터링을 통한 커뮤니티 감지로 하위 시스템 찾기
tree-sitter를 통한 약 40개 언어의 파일 간 링크 해석
# NOTE: 및 # WHY: 주석을 일급 그래프 노드로 변환하는 근거 추출
변경된 파일만 다시 추출하는 증분 업데이트

🔍 질의 및 탐색 — 그래프가 생성된 후 이를 조사하는 명령

graph.json에 대한 자연어 질의
두 명명된 엔티티 간 최단 경로 조회
엔티티가 왜 중요한지, 무엇과 연결되는지 표면화하는 explain 명령
검토 큐를 관련성 순으로 정렬하는 AI 지원 PR 트리아지
아키텍처 다이어그램 내보내기(예: 호출 흐름 HTML 시각화)

🌐 다중 형식 수집 — 소스 코드를 넘어 그래프 확장

36개 tree-sitter 문법의 소스 코드(Python, TypeScript, Go, Rust, Java, C/C++, Ruby 등)
문서 및 PDF
faster-whisper를 통한 로컬 전사가 가능한 이미지 및 비디오/오디오
SQL 스키마 및 코드형 인프라(Terraform)
Salesforce Apex, Pascal/Delphi 및 기타 틈새 생태계를 위한 선택적 확장

🤖 AI 어시스턴트 통합 — 기존 개발자 워크플로우에 그래프 도입

20개 이상의 AI 코딩 어시스턴트에서 네이티브 /graphify 스킬/명령 지원
플랫폼별 설치 프로그램(훅, 지시 파일 또는 네이티브 스킬 등록)
Claude Code, Cursor, Codex, Gemini CLI, GitHub Copilot CLI 등을 포괄

4. 주요 하이라이트

결정론적이고 설명 가능한 그래프 — 모든 엣지가 추출된 사실 또는 추론된 결론으로 라벨링되어 임베딩 기반 유사도 검색에서 흔한 추측을 제거합니다.
완전 로컬 코드 분석 — 소스 코드 그래프 구축에는 LLM 호출과 API 크레딧이 전혀 필요 없으며, 코드 자체에 대한 어떤 것도 머신을 떠나지 않습니다.
광범위한 언어 지원 — 기본 제공 36개 tree-sitter 문법으로 거의 모든 주류 언어와 선택적 확장을 통한 여러 전문 언어를 포괄합니다.
깊은 AI 어시스턴트 통합 — 별도의 독립 워크플로우를 요구하지 않고 20개 이상의 인기 AI 코딩 도구 내에서 네이티브 명령으로 작동합니다.
데이터로서의 근거 — 설계 결정 주석(# NOTE:, # WHY:)이 질의 가능한 그래프 노드로 승격되어 일반적으로 유실되는 의도를 보존합니다.
강력한 검색 벤치마크 — LOCOMO 벤치마크(n=300)에서 graphify는 recall@10 0.497을 보고하며, 자체 벤치마크에 인용된 유사 메모리/검색 도구보다 현저히 앞섭니다.

5. 역할별 사용 사례

일반 개발자
기존 AI 코딩 어시스턴트 내에서 /graphify .를 사용하여 낯선 저장소에 대한 즉각적이고 설명 가능한 컨텍스트를 얻으세요 — 수동 검색 없이 기능이 파일 간에 어떻게 연결되는지 추적할 수 있습니다.

DevOps/SRE
SQL 스키마 및 Terraform 수집을 활용하여 애플리케이션 코드와 함께 코드형 인프라 관계를 매핑하고, 경로 질의를 사용하여 서비스와 이를 뒷받침하는 인프라 간의 종속성을 추적하세요.

데이터/연구 과학자
문서, PDF, 비디오/오디오 자료까지 코드베이스와 동일한 그래프로 수집하여 연구 노트와 사양을 구현에 직접 연결하는 질의를 가능하게 하세요.

프로젝트 매니저
graphify prs --triage를 사용하여 AI 순위가 매겨진 풀 리퀘스트 검토 큐를 얻고, 그래프 내보내기(예: 호출 흐름 다이어그램)를 사용하여 다이어그램을 수동으로 그리지 않고 이해관계자에게 아키텍처를 전달하세요.

6. 시작하기

필요한 것 찾기 — 저장소의 docs/ 디렉토리에서 문서, 아키텍처 가이드, 번역된 README(14개 언어)를 살펴보거나, ARCHITECTURE.md에서 모듈별 분석을 읽어보세요.

설치 / 통합

uv tool install graphifyy
graphify install

그런 다음 지원되는 AI 코딩 어시스턴트 내에서 /graphify .를 호출하여 현재 프로젝트의 그래프를 구축하세요. 대체 설치 방법:

pipx install graphifyy
# 또는
pip install graphifyy

기여

git clone https://github.com/Graphify-Labs/graphify.git
cd graphify && git checkout v8
uv sync --all-extras
uv run pytest tests/ -q

활발한 개발은 v8 브랜치에서 진행됩니다. 커밋은 fix: / feat: / docs: 접두사를 따르며, 새 언어 지원에는 tests/fixtures/ 아래의 픽스처와 test_languages.py의 테스트 케이스가 포함되어야 합니다.

7. 프로젝트 구조

graphify/
├── .github/              # GitHub 워크플로우(CI, 릴리스)
├── docs/                 # 14개 언어 번역을 포함한 문서
├── graphify/             # 메인 패키지 소스 코드
├── scripts/              # 유틸리티 스크립트
├── tests/                # 언어 픽스처를 포함한 테스트 스위트
├── tools/                # 헬퍼 도구
├── worked/                # 검토자 노트가 포함된 예제 추출
├── ARCHITECTURE.md       # 모듈 책임 및 언어 통합 가이드
├── BENCHMARKS.md         # 성능 및 정확도 지표
└── AGENTS.md             # 에이전트 프레임워크 문서

graphify/는 핵심 추출 및 질의 엔진을 보유하며, ARCHITECTURE.md는 모듈이 어떻게 결합되는지 이해하거나 새 언어 지원을 추가하려는 기여자에게 권장되는 시작점입니다.

8. 관련 생태계

의존 / 기반:

tree-sitter — 로컬 코드 분석을 구동하는 결정론적 AST 파싱 제공
faster-whisper — 비디오/오디오 입력의 로컬 전사에 사용
선택적 그래프 및 데이터베이스 백엔드: Neo4j, FalkorDB, PostgreSQL/SQL

보완 도구:

AI 코딩 어시스턴트(Claude Code, Cursor, Codex, Gemini CLI, GitHub Copilot CLI 등)를 대체하지 않고 함께 작동 — 해당 도구가 소비하는 구조화된 컨텍스트를 공급
문서, 이미지, 비디오의 의미론적 추출을 위한 선택적 AI 백엔드(Ollama를 통한 로컬 옵션 포함)

9. 라이선스

Graphify는 이중 라이선스로 제공되며, 사용자는 자신의 사용 사례에 가장 적합한 라이선스를 선택할 수 있습니다.

✅ Apache License 2.0 또는 MIT License 중 선택하여 코드 사용, 수정, 배포 가능
✅ 두 라이선스 조건에 따라 상업 및 독점 프로젝트에서 사용 가능
❌ 두 라이선스 모두 어떠한 보증도 제공하지 않음 — 소프트웨어는 "있는 그대로" 제공됨
ℹ️ 저작자 표시 및 라이선스 고지 요구 사항은 Apache-2.0과 MIT 간에 약간 다름 — 재배포 전에 선택한 라이선스의 특정 조건을 검토하세요

10. FAQ

Q: graphify가 내 코드를 외부 서버나 LLM으로 보내나요?
A: 아니요. 소스 코드는 tree-sitter를 통해 로컬에서 파싱되며, 코드 그래프 구축에는 LLM 호출이 전혀 필요 없습니다. PDF, 이미지, 비디오의 선택적 처리만 구성된 AI 백엔드를 사용하며, 이것도 Ollama를 통해 완전히 로컬에서 실행할 수 있습니다.

Q: graphify는 어떤 AI 코딩 어시스턴트와 작동하나요?
A: Claude Code, Cursor, Codex, Gemini CLI, GitHub Copilot CLI를 포함한 20개 이상과 작동합니다. graphify install을 실행하여 플랫폼별 통합을 설정하세요.

Q: 벡터 임베딩을 사용하는 RAG 도구와 어떻게 다른가요?
A: Graphify는 벡터 인덱스가 아닌 실제 탐색 가능한 그래프를 구축합니다. 관계는 EXTRACTED 또는 INFERRED로 명시적으로 태그가 지정되므로 결과는 유사도 점수가 아닌 설명 가능한 형태입니다.

Q: 지원되는 프로그래밍 언어는 몇 개인가요?
A: 기본적으로 36개 tree-sitter 문법이 포함되어 대부분의 주류 언어를 포괄하며, Salesforce Apex 및 Pascal/Delphi와 같은 언어를 위한 추가 선택적 확장이 있습니다.

Q: 기존 그래프를 어떻게 질의하나요?
A: 생성된 graph.json에 대해 graphify query "what connects auth to database?", graphify path "ServiceA" "ServiceB", 또는 graphify explain "ComponentName"과 같은 명령을 사용하세요.

11. 빠른 링크

저장소: https://github.com/Graphify-Labs/graphify
아키텍처 가이드: 저장소 루트의 ARCHITECTURE.md
기여: 저장소 README의 개발 설정 및 지침
벤치마크: 저장소 루트의 BENCHMARKS.md

12. 요약

Graphify는 개발자에게 코드베이스와 주변 문서, 스키마 및 기타 산출물이 실제로 어떻게 결합되는지에 대한 설명 가능하고 로컬에서 계산된 지도를 제공하여, 수동 파일 검색과 불투명한 유사도 검색을 탐색 가능하고 질의 가능한 그래프로 대체합니다. 특히 크거나 낯선 저장소에 온보딩하는 개발자와 AI 코딩 어시스턴트가 추측이 아닌 검증 가능하고 출처가 있는 컨텍스트로 아키텍처를 추론하도록 하려는 팀에게 특히 가치 있습니다.