💡 요약
Graphify는 전체 소스코드와 프로젝트 문서, 미디어 파일(PDF, 이미지, 영상)을 분석하여 영구 탐색이 가능한 지식 그래프(Knowledge Graph)로 자동 구성하는 오픈소스 도구입니다. 대형 프로젝트 분석 시 발생하던 AI 에이전트(Claude Code, Cursor, Codex 등)의 토큰 소모를 방지하고, 인터랙티브 graph.html 시각화와 아키텍처 핵심 노드(God Node) 분석 보고서를 제공합니다.
| 구분 | 주요 기술 사양 및 특징 |
|---|---|
| 개발사 / 리포지토리 | Graphify Labs / https://github.com/Graphify-Labs/graphify |
| 설치 패키지명 | PyPI graphifyy (실행 명령어: graphify) |
| 분석 2단계 구조 | 1단계 로컬 AST 구조 추출 (tree-sitter) + 2단계 의미론 추출 (LLM) |
| 출력 포맷 | 인터랙티브 HTML (graph.html), 보고서 (GRAPH_REPORT.md), JSON (graph.json), Obsidian 노드 |
| 관계 신뢰도 태그 | EXTRACTED (명시적 코드 연결), INFERRED (의미 추론 연결), AMBIGUOUS |
| 증분 업데이트 지원 | --update 및 --watch 옵션 지원 (변경 파일만 증분 추출하여 시간 단축) |
Graphify의 필요성과 기존 RAG와의 차이점
수만 줄 이상의 대형 소스코드나 복잡한 모노레포 프로젝트를 AI 에이전트에 입력할 때, 매번 수십만 토큰의 파일 전체를 읽거나 벡터 검색(RAG)을 수행하면 다음과 같은 한계가 발생합니다:
- 전체 맥락 유실: 벡터 검색은 단편적인 텍스트 유사도만 검색하므로 파일과 함수 간의 상호 의존성(의존 관계 트리)을 파악하기 어렵습니다.
- 높은 토큰 비용: 매 질문마다 소스 파일을 반복적으로 챗봇에 읽히게 되어 비용이 증가합니다.
Graphify는 소스코드 구조를 파싱(AST)하여 노드(클래스, 함수, 모듈)와 엣지(호출, 상속, 참조)로 이루어진 지식 그래프를 생성합니다. 한번 구축된 그래프는 영구 보관되며, AI 에이전트는 이 그래프를 바탕으로 아키텍처 질문에 답변합니다.
Graphify 5단계 지식 그래프 추출 파이프라인
소스코드와 문서를 분석하여 그래프 데이터로 완성하는 과정입니다:
Graphify 설치 및 기본 명령어 사용법
Graphify는 Python 패키지 환경에서 uv 또는 pip를 통해 간편하게 설치할 수 있습니다.
📍 패키지 설치 명령어 (PyPI 명칭: graphifyy)
# uv를 사용하는 경우 (추천)
uv tool install graphifyy
# 또는 pip 사용 시
pip install graphifyy💡 꿀팁 PyPI 등록 이름은 `graphifyy`(y가 2개)이지만, 터미널 실행 명령어 및 AI 스킬 호출은 `graphify`를 사용합니다.
주요 CLI 명령 옵션 정리
| 명령어 옵션 | 설명 |
|---|---|
graphify |
현재 디렉터리 전체를 분석하여 graphify-out/ 결과 폴더 생성 |
graphify https://github.com/유저/리포지토리 |
GitHub 리포지토리를 직접 클론하여 지식 그래프 생성 |
graphify . --update |
변경되거나 새롭게 추가된 파일만 증분(Incremental) 재분석 |
graphify . --watch |
소스코드 변경을 감지하여 실시간으로 지식 그래프 자동 갱신 |
graphify query "질문" |
구축된 그래프 위에서 너비 우선 탐색(BFS)으로 특정 기능 문맥 탐색 |
graphify path "노드A" "노드B" |
노드 A와 노드 B 사이의 최단 호출 경로 추적 |
graphify . --obsidian |
옵시디언(Obsidian) 볼트 연동용 마크다운 파일 출력 |
생성 결과물 및 아키텍처 탐색 기법
분석이 완료되면 graphify-out/ 폴더에 다음과 같은 핵심 결과물이 생성됩니다:
graph.html(인터랙티브 웹 그래프):- 웹 브라우저에서 열어 소스코드 내 모든 클래스, 함수, 모듈 간의 연결을 드래그하여 시각적으로 탐색합니다.
GRAPH_REPORT.md(아키텍처 인사이트 보고서):- 프로젝트에서 가장 연결 상태가 복잡한 **갓 노드(God Nodes)**와 뜻밖의 모듈 연결 관계(Surprising Connections)를 분석해 줍니다.
graph.json(GraphRAG용 데이터):- AI 프로그램이 그래프 질의 응답을 수행할 때 참고하는 정형 데이터 구조입니다.
⚠️ 참고 순수 소스코드만 분석할 때는 LLM API 키 없이 100% 로컬 AST 파싱으로 동작합니다. PDF나 이미지 문서에서 의미를 함께 추출하려는 경우 `GEMINI_API_KEY` 환경변수를 설정하면 보다 깊은 2단계 분석이 수행됩니다.
✅ 한눈에 보는 실행 체크리스트
✅ Graphify 적용 및 활용 체크리스트
- ☑️ 패키지 설치: `uv tool install graphifyy` 또는 `pip install graphifyy`
- ☑️ 그래프 생성 실행: 대상 프로젝트 폴더로 이동 후 `graphify` 실행
- ☑️ 시각화 확인: `graphify-out/graph.html` 브라우저로 오픈
- ☑️ 인사이트 확인: `graphify-out/GRAPH_REPORT.md`에서 주요 의존성 및 갓 노드 체크
- ☑️ 질문 탐색: `graphify query "주요 기능 작동 원리"` 명령어로 특정 의존성 검색
자주 묻는 질문 (FAQ)
Q1. 코드 수정 시 매번 전체 프로젝트를 다시 분석해야 하나요?
아닙니다. graphify . --update 명령어를 실행하면 해시값이 변경된 신규/수정 파일만 선별하여 증분 분석을 진행하므로 소요 시간이 단축됩니다.
Q2. Graphify는 어떤 언어를 지원하나요?
tree-sitter 파서 기반으로 Python, TypeScript, JavaScript, Go, Rust, C/C++, Java 등 대부분의 주요 프로그래밍 언어를 완벽하게 지원합니다.
Q3. Neo4j나 FalkorDB 같은 그래프 DB로 내보낼 수 있나요?
네. graphify . --neo4j 또는 graphify . --falkordb 옵션을 부여하면 해당 그래프 DB에 입력할 수 있는 Cypher 쿼리 파일(cypher.txt)이 생성됩니다.