Graphify 완전 가이드 — AI 코딩 어시스턴트를 위한 지식 그래프 도구

1. Graphify가 뭔가요?

여러분이 쓰는 Claude Code나 Cursor가, 우리 코드베이스 전체의 구조를 한 번에 파악할 수 있다면 어떨까요?

보통 AI 어시스턴트에게 코드 관련 질문을 하면, 관련 파일을 일일이 context에 붙여넣거나, 어떤 파일이 어디에 있는지 직접 설명해줘야 합니다. 프로젝트 규모가 커질수록 이 과정이 점점 번거로워지죠.

🕸️

Graphify는 코드, 문서, 논문, 이미지를 읽어서 AI 코딩 어시스턴트가 이해할 수 있는 지식 그래프(Knowledge Graph)로 변환하는 오픈소스 도구입니다.

항목	내용
GitHub Stars	23,600+
라이선스	MIT (무료, 상업적 사용 가능)
개발자	Safi Shamsi
지원 AI 플랫폼	Claude Code, Cursor, Copilot CLI, Codex, OpenCode, Gemini CLI, Aider, OpenClaw, Trae — 총 9개
지원 언어	22개 (Python, JS, TS, Go, Rust, Java 등)
토큰 절감	71.5배 (52개 파일 벤치마크, 쿼리당 ~1,700 vs 나이브 ~123,000 토큰)
핵심 보안	소스 코드 원본은 LLM에 전송되지 않음 — 로컬 AST 파싱

DA팀 입장에서 특히 관심 가질 부분은 Python 지원과 로컬 파싱 방식입니다. 코드를 외부로 보내지 않는다는 점은 보안 정책상 중요한 조건이 될 수 있습니다.

---

2. Karpathy의 /raw 폴더에서 시작된 이야기

2026년 4월 3일, AI 연구자 Andrej Karpathy가 X(트위터)에 조용히 하나의 아이디어를 올렸습니다. 제목은 "LLM Knowledge Bases".

아이디어 자체는 단순했습니다. 프로젝트 루트에 세 개의 폴더를 만든다는 것이었죠.

• /raw — 논문, 스크린샷, 메모, 코드 스니펫을 분류 없이 그냥 던져 넣는 폴더
• /wiki — LLM이 /raw를 읽고 정리한 구조화된 위키
• /outputs — AI가 생성한 분석 결과물

a large fraction of my recent token throughput is going less into manipulating code, and more into manipulating knowledge
— Andrej Karpathy

코드를 다루듯 지식을 다루고, LLM을 컴파일러처럼 사용하는 방식입니다. /raw에 재료를 넣으면, LLM이 /wiki라는 실행 가능한 지식으로 컴파일해주는 구조죠.

💡

이게 왜 중요한가? 매번 /raw 전체를 LLM에 읽히면 토큰 비용이 급격히 늘어납니다. 그리고 파일이 많아질수록 AI가 파일 간의 관계와 구조를 파악하기가 어려워집니다.

Safi Shamsi는 이 트윗을 보고 다른 질문을 떠올렸습니다. "이걸 코드베이스에 자동으로 적용하면 어떨까?" 수동으로 폴더를 관리하는 대신, 코드베이스를 파싱해서 지식 그래프를 자동으로 생성하고 AI 어시스턴트가 필요한 부분만 쿼리하게 만들면 된다는 것이었습니다. 그렇게 Graphify가 만들어졌습니다.

공개 후 48시간 만에 GitHub 스타 6,000개를 돌파했습니다. 빠른 반응은 이 문제가 많은 개발자들이 이미 체감하고 있던 불편함이었음을 보여줍니다.

---

3. 작동 원리 — 어떻게 동작하나요?

새 책이 들어왔을 때 사서가 하는 일을 3단계로 나누면 Graphify의 동작 원리를 이해할 수 있습니다. 책을 받아서 목차를 정리하고, 그림이나 DVD 같은 비텍스트 자료를 텍스트로 옮기고, 마지막으로 책들 사이의 주제적 연결고리를 파악해 같은 서가에 배치하는 과정이죠.

Pass 1: 코드 구조 추출 (AST 파싱)

"책의 목차와 색인을 자동으로 만드는 단계"

Tree-sitter라는 파서 도구를 사용해 22개 프로그래밍 언어의 코드를 분석합니다. 함수, 클래스, 임포트, 호출 관계 등 코드의 뼈대를 추출해서 구조화된 형태로 정리합니다.

🔒

핵심: 이 단계에서는 LLM을 전혀 사용하지 않습니다. 완전히 로컬에서 실행되기 때문에 코드 원본이 외부 서버로 전송되지 않습니다.

Pass 2: 미디어 변환 (트랜스크립션)

"그림책과 DVD의 내용을 텍스트로 요약하는 단계"

PDF, 이미지, 영상/오디오 파일을 텍스트로 변환합니다. 오디오 변환에는 faster-whisper를 사용하는데, 이 역시 로컬에서 실행되어 클라우드로 전송되지 않습니다. YouTube 링크라면 yt-dlp로 오디오를 먼저 다운로드한 뒤 동일하게 로컬에서 변환합니다.

Pass 3: 의미 추출 및 그래프 구축

"사서가 책들 사이의 주제적 연결고리를 파악하고, 관련 책끼리 같은 서가에 배치하는 단계"

Claude 등 LLM 서브에이전트가 문서와 이미지에서 개념과 관계를 병렬로 추출합니다. 추출된 데이터는 NetworkX 그래프로 병합되고, Leiden 알고리즘으로 커뮤니티(관련 개념 그룹)를 클러스터링합니다.

🧠

핵심 차별점: 임베딩이 아닌 그래프 토폴로지(Graph Topology)

일반적인 RAG 시스템은 텍스트를 벡터로 변환(임베딩)해서 유사도를 계산합니다.

Graphify는 벡터 임베딩 없이, 그래프 엣지(Edge)의 밀도로 클러스터링합니다. 코드의 구조적 관계를 직접 활용하므로 더 정확한 맥락 파악이 가능합니다.

출력물: graphify-out/ 폴더

파일	내용
graph.html	브라우저에서 직접 탐색 가능한 대화형 그래프 뷰어
GRAPH_REPORT.md	갓 노드(가장 많이 연결된 핵심 개념), 주목할 연결, 추천 질문이 담긴 요약 보고서
graph.json	프로그래밍으로 쿼리 가능한 영구 그래프 데이터
cache/	SHA256 캐싱으로 변경된 파일만 다시 처리 — 반복 실행 비용 절감

엣지 신뢰도 태깅 (Edge Confidence Tagging)

• EXTRACTED (신뢰도 1.0) — 코드에서 직접 발견한 구조적 연결. 사실에 가깝습니다.
• INFERRED (0.0~1.0) — 문서나 이미지에서 추론한 의미적 연결. 숫자가 낮을수록 불확실합니다.
• AMBIGUOUS — 불확실한 연결. 수동으로 확인이 필요한 항목입니다.

---

4. 대안 비교 — 다른 방법들과 뭐가 다른가요?

코드베이스를 AI에게 이해시키는 방법은 여러 가지가 있습니다. Graphify가 어떤 위치에 있는지 주요 접근법과 비교해보겠습니다.

핵심 접근법 비교

비교 항목	전통 RAG	Karpathy /raw 방식	Graphify
자동화	높음 (자동 임베딩)	낮음 (수동 관리)	높음 (자동 그래프 생성)
구조 이해	낮음 (텍스트 유사도만)	중간 (사람이 정리)	높음 (코드 구조 + 의미 관계)
보안	코드를 임베딩 서버로 전송	원본을 LLM에 전달	코드는 로컬 파싱만
멀티모달	제한적	가능 (수동)	자동 (코드+문서+이미지+영상)
토큰 효율	보통 (청크 단위 검색)	낮음 (전체 읽기)	높음 (71.5배 절감)
유지보수	벡터 DB 필요	수동 업데이트	캐시 기반 증분 업데이트

기존 코드 탐색 도구와의 비교

• Sourcegraph와의 차이
• 기업용 크로스 레포 코드 검색에 특화된 도구입니다. 수십 개 레포를 넘나드는 심볼 검색, PR 리뷰, 배치 변경 등이 강점입니다. Graphify는 단일 레포 내 구조적 이해에 집중하므로 용도 자체가 다릅니다.
• Code2Vec과의 차이
• 함수를 벡터 공간에 임베딩하여 코드 간 표면적 유사도를 포착하는 연구용 접근법입니다. Graphify는 호출 그래프(call graph), 임포트 관계, 설계 의도까지 보존하는 방향을 지향합니다.
• Neo4j와의 차이
• 강력한 그래프 데이터베이스이지만, 코드를 분석해서 그래프를 "자동 생성"해주지는 않습니다. 그래프 구조를 직접 설계하고 데이터를 넣어야 합니다. Graphify는 그 생성 과정을 자동화하는 레이어에 해당합니다.

📌

Graphify는 'AI 어시스턴트의 코드 이해력을 높이는 것'에 특화된 도구입니다. 범용 검색(Sourcegraph)이나 범용 DB(Neo4j)와 경쟁하는 것이 아니라, 보완적으로 사용할 수 있습니다.

---

5. 설치 & 사용법 — 바로 써보기

사전 준비물

✅

• Python 3.10 이상
• AI 코딩 어시스턴트 (Claude Code, Cursor, Codex 중 하나)
• API 키 설정 완료 — 어시스턴트에서 이미 사용 중이라면 추가 설정은 불필요

설치 (2줄)

pip install graphifyy
graphify install

PyPI 패키지명은 graphifyy (y가 두 개)이지만, 이후 사용하는 CLI 명령어는 graphify (y 하나)입니다. graphify install을 실행하면 현재 사용 중인 AI 어시스턴트를 감지해 자동으로 맞춤 설정해줍니다.

기본 사용법

/graphify .                    # 현재 디렉토리 전체 스캔
/graphify ./raw                # 특정 폴더만 스캔
/graphify ./raw --update       # 변경된 파일만 업데이트
/graphify ./raw --watch        # 실시간 자동 동기화

그래프 탐색 명령어

/graphify query "이 프로젝트의 핵심 모듈은?"    # 자연어로 질문
/graphify path "DigestAuth" "Response"          # 두 개념 간 경로 추적
/graphify explain "Client"                      # 특정 모듈의 역할과 의존성 설명

내보내기 옵션

graphify <path> --svg        # SVG 이미지로 저장
graphify <path> --neo4j      # Neo4j Cypher 쿼리로 변환
graphify <path> --obsidian   # Obsidian 볼트로 연동
graphify <path> --wiki       # 위키피디아 스타일 문서로 정리

플랫폼별 Always-On 연동 (한 번만 실행)

graphify claude install    # Claude Code 연동
graphify cursor install    # Cursor 연동
graphify codex install     # Codex 연동

이 명령어를 한 번 실행해두면, 이후 AI 어시스턴트가 코드를 탐색하기 전에 자동으로 GRAPH_REPORT.md를 먼저 참고합니다.

⚠️

주의사항

1. API 비용: 문서/이미지 시맨틱 추출 시 LLM API 호출이 발생합니다. 코드 파싱(Pass 1)은 로컬 실행이라 무료입니다.
2. .graphifyignore 설정: node_modules, .git, 빌드 산출물 등은 미리 제외 설정을 권장합니다.
3. 첫 빌드 시간: 대규모 코드베이스는 첫 스캔에 시간이 걸릴 수 있습니다. 이후 --update로 증분 업데이트를 활용하세요.

---

6. 실전 평가 — 솔직히, 지금 쓸 만한가?

결론부터 말하면, "가능성은 분명하지만 지금 당장 믿고 쓰기엔 이른 단계"입니다.

장점 5가지

👍

1. 보안 — 코드 원본이 LLM에 전송되지 않습니다. 로컬 AST 파싱 후 구조 정보만 추출합니다.
2. 토큰 효율 — 52개 파일 기준 71.5배 절감. 쿼리당 ~1,700 토큰 vs 나이브 ~123,000 토큰.
3. 멀티모달 — 코드 + 문서 + PDF + 이미지 + 영상 통합 분석.
4. 플랫폼 범용성 — Claude Code, Cursor 등 9개 AI 어시스턴트 지원.
5. 오픈소스 MIT — 무료이고 상업적 사용도 가능합니다.

실사용 리뷰 — Kevin Kinnett (시니어 소프트웨어 엔지니어)

TypeScript 코드베이스에서 직접 테스트 — 369개 노드, 505개 엣지, 57개 커뮤니티가 성공적으로 생성되었습니다. 그래프 쿼리로 아키텍처 인사이트를 확인하는 것 자체는 작동했습니다.
그러나 핵심 출력물인 GRAPH_REPORT.md가 빈 파일로 생성되었습니다. 이 파일이 Claude Code 연동의 핵심이기 때문에, 실질적인 AI 어시스턴트 연동은 동작하지 않았습니다.
평가: "좋은 아이디어의 초기 구현 문제이지, 나쁜 아이디어의 마케팅 문제가 아니다."

한계 4가지

⚠️

1. 초기 성숙도 — 빈 리포트 파일처럼 기본 기능에서 안정성 이슈가 존재합니다.
2. LLM API 비용 — 문서/이미지 시맨틱 추출 시 API 호출이 발생합니다.
3. 러닝커브 — CLI 설정, 플랫폼별 연동 설정이 필요합니다.
4. 커뮤니티 초기 단계 — 공식 문서와 예제가 아직 충분하지 않습니다.

지금 당장 프로덕션에 넣기보다는, 1-2개월 후 안정화를 지켜보면서 소규모 파일럿으로 시도해보는 것이 현실적입니다.

---

7. DA팀 시사점 — 우리 팀에서는 어떻게 활용할 수 있을까?

DA팀은 SQL, Python, Airflow DAG라는 명확한 코드베이스를 갖고 있고, Claude Code를 이미 사용 중입니다. Graphify가 실질적으로 도움이 될 수 있는 시나리오를 살펴보겠습니다.

활용 시나리오 3가지

1. Airflow DAG 구조 파악 (온보딩)

da-airflow에는 도메인별로 수백 개의 DAG가 쌓여 있습니다. 신규 팀원이 "이 DAG는 어떤 데이터를 읽고, 어디에 씁니까?"라는 질문에 답을 찾으려면 지금은 코드를 직접 뒤지거나 담당자에게 물어봐야 합니다.

Graphify를 적용하면 DAG 간 의존성, common/ 폴더의 공유 유틸리티 참조 관계, 핵심 파이프라인 흐름을 자동으로 매핑할 수 있습니다.

2. SQL 프로젝트 영향도 분석

특정 Athena 테이블의 스키마를 변경할 때, 어떤 DAG와 쿼리가 영향을 받는지 파악하는 일은 지금도 수동 grep 작업에 의존하는 경우가 많습니다. 그래프 구조가 갖춰지면 /graphify path "source_table" "final_report" 같은 명령으로 의존 체인을 추적할 수 있습니다.

3. 분석 문서 + 코드 통합

data-analytics 폴더의 노트북과 SQL 파일은 서로 연관되어 있지만, 그 관계가 명시적으로 관리되지 않는 경우가 많습니다. Graphify의 멀티모달 지원을 활용하면 노트북과 SQL 파일 간의 참조 관계를 구조화할 수 있습니다.

현실적 권고

💬

• 즉시 프로덕션 도입은 권장하지 않습니다 (초기 성숙도 이슈)
• 소규모 파일럿 권장: da-airflow의 특정 도메인 폴더(예: Commerce DAGs)에서 시험 운영
• 1-2개월 후 재평가: 안정화된 버전에서 전체 도입 여부 결정
• ROI: 코드베이스 규모가 클수록 토큰 절감 효과가 선형 이상으로 커집니다

핵심 메시지

Graphify 자체보다 중요한 건, AI 코딩 어시스턴트가 코드를 '구조적으로' 이해하는 방향으로 진화하고 있다는 흐름입니다. 지식 그래프(Knowledge Graph) 기반 접근은 앞으로 더 많은 도구에서 채택될 가능성이 높으므로, 이 트렌드를 주목해두는 것이 좋겠습니다.

---

📚

참고 링크

• GitHub 저장소
• 공식 홈페이지
• PyPI 패키지 (graphifyy)
• Karpathy 원문 포스트
• Kevin Kinnett 실사용 리뷰