코드·PDF·유튜브를 한 번에 지식 그래프로 — graphify가 해결하는 5가지 개발자 문제

대규모 코드베이스 파악에 수일이 걸리는 문제를 graphify는 코드·PDF·유튜브를 지식 그래프로 변환해 토큰 71배 절감으로 해결합니다.

 

새 프로젝트에 투입됐는데 레포지토리가 수십 개 파일에 논문·슬라이드까지 흩어져 있던 경험, 한 번쯤 있으신가요? Claude Code나 Cursor에 파일을 통째로 붙여넣으면 컨텍스트가 터지고, 그렇다고 파일 하나씩 읽어달라고 하면 "왜 이 구조인지"를 설명해 주는 곳이 없습니다. 핵심 설계 의도가 코드 주석에 숨어 있거나, 아예 내부 위키 PDF에만 적혀 있는 경우도 많습니다.

graphify는 이 문제를 세 가지 방식으로 해결합니다. 첫째, 코드 파일은 LLM 없이 tree-sitter AST로 로컬에서 파싱해 함수·클래스·호출 그래프를 추출합니다. 둘째, 논문·슬라이드·이미지·영상은 Claude 서브에이전트가 병렬로 개념과 관계를 추출합니다. 셋째, 추출된 모든 정보를 NetworkX 그래프로 합쳐 인터랙티브 HTML과 질의 가능한 JSON으로 내보냅니다. Claude Code에서 /graphify . 한 줄이면 충분합니다.

이 글에서는 graphify가 실제로 해결하는 개발자 5가지 고통 포인트, 지원 파일 형식 전체, 설치부터 첫 그래프 생성까지의 단계별 가이드, 그리고 Claude Code·Cursor·Gemini CLI에서의 항상-켜두기 설정을 모두 다룹니다.

📑 목차

• graphify란 무엇인가
• graphify가 해결하는 5가지 개발자 문제
• 지원 파일 형식 총정리
• 설치 및 첫 실행 Step-by-Step
• 그래프 질의 실전 예시
• 항상-켜두기 설정 (Claude Code · Cursor · Gemini CLI)
• 자주 묻는 질문

📌 이 글에서 배울 수 있는 것

1. 코드·PDF·영상·유튜브를 단일 지식 그래프로 합치는 원리와 71배 토큰 절감 효과
2. pip install graphifyy && graphify install로 Claude Code에서 즉시 사용하는 방법
3. Claude Code, Cursor, Gemini CLI에서 그래프를 항상 켜두는 설정법

graphify란 무엇인가

graphify는 AI 코딩 어시스턴트(Claude Code, Cursor, Gemini CLI 등)에서 /graphify 한 줄로 호출하는 스킬입니다. 폴더 안의 모든 파일 — 소스 코드, 마크다운, PDF, 이미지, 영상, 유튜브 링크 — 을 읽어 지식 그래프(knowledge graph)를 구축하고, 그 그래프를 통해 AI 어시스턴트가 코드베이스를 구조적으로 이해할 수 있게 합니다.

GitHub 스타 19,800개(2026년 4월 기준)를 받은 이 오픈소스 프로젝트는 2026년 4월 10일 v0.4.0을 릴리즈하며 비디오·오디오 코퍼스 지원을 추가했습니다. PyPI 패키지명은 graphifyy(y 두 개)입니다.

graphify 작동 원리 — 입력 파일에서 지식 그래프 출력까지

그래프 생성 결과는 세 파일로 나뉩니다. graph.html은 노드를 클릭하고 커뮤니티별로 필터링할 수 있는 인터랙티브 시각화 파일입니다. GRAPH_REPORT.md는 "갓 노드(god node, 연결이 가장 많은 개념)"와 예상치 못한 연결, 추천 질문을 담은 요약 보고서입니다. graph.json은 세션이 끝난 뒤에도 질의할 수 있는 영속적 그래프 파일입니다.

graphify가 해결하는 5가지 개발자 문제

① 새 코드베이스 파악에 며칠이 걸린다

대규모 레포를 처음 접할 때 가장 어려운 것은 "왜 이렇게 설계했는가"를 파악하는 일입니다. graphify는 코드 파일의 docstring, # NOTE:·# WHY: 주석, 설계 문서를 rationale_for 노드로 추출해 설계 의도를 그래프에 포함합니다. GRAPH_REPORT.md를 읽으면 어시스턴트가 파일 하나하나를 grep하는 대신 구조를 기반으로 탐색합니다.

② 코드·논문·슬라이드가 따로 놀아 맥락 연결이 안 된다

같은 알고리즘을 구현한 코드 파일과 논문이 아무 연결 없이 레포에 공존하는 경우가 많습니다. graphify는 semantically_similar_to 엣지로 코드와 논문의 개념을 연결합니다. 이 엣지는 Leiden 커뮤니티 감지에도 직접 반영돼, 임베딩이나 벡터 DB 없이 의미적 유사성을 그래프 위상(topology)으로 표현합니다.

③ AI 어시스턴트가 전체 파일을 읽느라 토큰이 폭발한다

52개 파일(Karpathy 레포 + 논문 5편 + 이미지 4장) 코퍼스 실측 결과, graphify는 원본 파일을 직접 읽는 방식 대비 쿼리당 71.5배 적은 토큰을 사용했습니다(공식 벤치마크). 첫 실행 시 추출 비용이 발생하지만, 이후 쿼리는 압축된 그래프를 읽기 때문에 비용이 대폭 줄어듭니다. SHA256 캐시로 변경된 파일만 재처리합니다.

④ 영상 강의·유튜브 링크의 내용을 코드와 연결하기 어렵다

v0.4.0부터는 pip install 'graphifyy[video]' 한 줄로 영상·오디오 지원이 활성화됩니다. /graphify add <유튜브 URL>을 입력하면 yt-dlp가 오디오만 내려받고, faster-whisper가 로컬에서 전사합니다. 전사본은 코드·논문과 동일한 추출 파이프라인을 거쳐 그래프에 통합됩니다. 오디오는 외부로 전송되지 않습니다.

⑤ 추론 결과가 "추출된 사실"인지 "추론한 것"인지 모른다

graphify의 모든 관계(엣지)는 EXTRACTED(소스에서 직접 발견), INFERRED(합리적 추론, 신뢰도 점수 0.0~1.0 포함), AMBIGUOUS(검토 필요) 세 가지로 태그됩니다. AI 어시스턴트가 무엇을 사실로 알고 무엇을 추론했는지 항상 구분할 수 있습니다.

graphify 출력 파일 — graph.html 인터랙티브 시각화 화면

지원 파일 형식 총정리

유형	확장자	추출 방식
코드	.py .ts .js .go .rs .java .c .cpp .rb .cs 외 10개	tree-sitter AST (로컬, LLM 불필요)
문서	.md .txt .rst	Claude 서브에이전트 병렬 추출
논문·PDF	.pdf	인용 마이닝 + 개념 추출
오피스	.docx .xlsx	마크다운 변환 후 Claude 추출 (pip install graphifyy[office])
이미지	.png .jpg .webp .gif	Claude Vision (다국어 지원)
영상·오디오	.mp4 .mov .mp3 .wav 외	faster-whisper 로컬 전사 후 Claude 추출 (pip install graphifyy[video])
유튜브·URL	모든 공개 영상 URL	yt-dlp 오디오 다운로드 → Whisper 전사

코드 파일은 20개 언어(Python, JS, TS, Go, Rust, Java, C, C++, Ruby, C#, Kotlin, Scala, PHP, Swift, Lua, Zig, PowerShell, Elixir, Objective-C, Julia)를 지원합니다. 제외할 폴더가 있다면 프로젝트 루트에 .graphifyignore 파일을 만들어 .gitignore와 동일한 문법으로 작성하면 됩니다.

Obsidian을 지식 관리 도구로 사용하고 있다면 Obsidian Mind North Star와 세션 훅 활용법, 매일 컨텍스트를 이어가는 워크플로와 graphify의 --obsidian 옵션을 함께 활용해 보세요. 그래프를 Obsidian 볼트로 내보낼 수 있습니다.

설치 및 첫 실행 Step-by-Step

준비물: Python 3.10 이상, Claude Code(또는 Cursor·Gemini CLI 등 지원 어시스턴트) | 소요시간: 약 5분

☐ 오늘 할 일 체크리스트

• ☐ Python 3.10+ 버전 확인
• ☐ pip install graphifyy 실행
• ☐ graphify install로 Claude Code에 스킬 등록
• ☐ 대상 폴더에서 /graphify . 실행
• ☐ graphify-out/GRAPH_REPORT.md 내용 확인
• ☐ (선택) graphify claude install로 항상-켜두기 설정

Step 1 — 패키지 설치

터미널을 열고 아래 명령을 실행합니다. PyPI 패키지명은 graphifyy(y 두 개)임에 주의하세요. graphify라는 이름의 다른 패키지와 혼동하지 않도록 공식 레포(safishamsi/graphify)에서 확인을 권장합니다.

pip install graphifyy

영상·유튜브 지원이 필요하다면 아래와 같이 extras를 추가합니다.

pip install 'graphifyy[video]'

Step 2 — AI 어시스턴트에 스킬 등록

Claude Code를 사용하는 경우 아래 명령 한 줄로 스킬이 설치됩니다. Windows도 자동 감지됩니다.

graphify install

다른 플랫폼은 --platform 옵션으로 지정합니다.

graphify install --platform codex      # OpenAI Codex
graphify install --platform gemini     # Gemini CLI
graphify cursor install                # Cursor

Step 3 — 첫 그래프 생성

Claude Code에서 분석할 폴더로 이동한 뒤 아래 명령을 입력합니다. 현재 디렉토리 전체를 분석합니다.

/graphify .

특정 폴더만 분석하려면 경로를 지정합니다.

/graphify ./docs

실행이 완료되면 graphify-out/ 폴더에 graph.html, GRAPH_REPORT.md, graph.json이 생성됩니다.

Step 4 — 유튜브·URL 추가 (선택)

특정 유튜브 영상을 코퍼스에 추가하고 싶다면 아래와 같이 입력합니다. 오디오 다운로드 → 로컬 전사 → 그래프 업데이트가 자동으로 진행됩니다.

/graphify add https://youtube.com/watch?v=...

graphify-out 폴더 구조 — graph.html, GRAPH_REPORT.md, graph.json

⚠️ 주의: 코드 파일은 tree-sitter로 로컬 처리되어 파일 내용이 외부로 전송되지 않습니다. 단, 문서·이미지·영상의 추출 과정에서 플랫폼(Claude Code라면 Anthropic, Codex라면 OpenAI)의 API로 내용이 전송됩니다. 보안이 중요한 내부 문서는 .graphifyignore로 제외하는 것을 권장합니다.

그래프 질의 실전 예시

그래프가 생성된 뒤에는 /graphify query로 자연어 질의가 가능합니다. 어시스턴트는 raw 파일을 grep하는 대신 그래프를 탐색해 답합니다.

/graphify query "인증 흐름의 핵심 모듈은 무엇인가?"
/graphify query "DigestAuth와 Response는 어떻게 연결되는가?" --dfs
/graphify path "Trainer" "Optimizer"
/graphify explain "SwinTransformer"

--dfs 옵션은 깊이 우선 탐색(Depth-First Search)으로 두 노드 사이의 구체적인 경로를 추적합니다. --budget 500을 붙이면 응답 토큰을 약 500개로 제한할 수 있습니다. 터미널에서 AI 어시스턴트 없이 직접 그래프를 질의하는 것도 가능합니다.

MCP 서버를 지원하는 환경이라면 python -m graphify.serve graphify-out/graph.json으로 MCP 서버를 띄워 query_graph, get_node, shortest_path 등을 구조화된 툴 콜로 호출할 수도 있습니다. vLLM이나 Ollama 같은 로컬 추론 엔진과 결합하면 완전한 온프레미스 구성이 가능합니다 — vLLM vs Ollama vs SGLang 비교 가이드에서 각 엔진의 특징을 확인해 보세요.

항상-켜두기 설정 (Claude Code · Cursor · Gemini CLI)

그래프를 한 번만 쓰고 끝내기 아깝습니다. 항상-켜두기 설정을 하면 AI 어시스턴트가 파일을 검색하기 전에 자동으로 GRAPH_REPORT.md를 참조합니다.

Claude Code

graphify claude install

CLAUDE.md에 지시문을 추가하고, settings.json에 PreToolUse 훅을 설치합니다. 이후 Glob·Grep 호출 전마다 "지식 그래프가 존재하면 GRAPH_REPORT.md를 먼저 읽어라"는 메시지가 자동으로 삽입됩니다.

Cursor

graphify cursor install

.cursor/rules/graphify.mdc를 alwaysApply: true로 생성합니다. 별도 훅 없이 모든 대화에 규칙이 자동 포함됩니다.

Gemini CLI

graphify gemini install

GEMINI.md에 지시문을 추가하고, 파일 읽기 툴 호출 전에 발화하는 BeforeTool 훅을 .gemini/settings.json에 설치합니다.

✍️ 직접 테스트한 경험
실제로 40개 파일 규모의 Python 프로젝트에 graphify를 실행한 뒤 Claude Code에서 "인증 미들웨어가 어떤 모듈에 의존하는가?"라고 물었더니, 파일을 하나하나 읽지 않고 곧바로 AuthMiddleware → TokenValidator → UserRepository 경로를 그래프에서 추적해 알려줬습니다. 같은 질문을 그래프 없이 할 때와 비교해 응답 속도와 정확도 모두 체감할 수 있었습니다. (출처: 직접 테스트, 2026년 4월)

자주 묻는 질문

Q. graphify는 무료인가요? 라이선스는 무엇인가요?

MIT 라이선스 오픈소스로 무료입니다. 단, 그래프 추출 과정에서 AI 어시스턴트 플랫폼(Claude Code라면 Anthropic)의 API를 호출하므로 해당 플랫폼의 사용 비용이 발생할 수 있습니다. 코드 파일은 로컬 AST 처리라 API 비용이 없습니다.

Q. Claude Code 외에 어떤 AI 어시스턴트를 지원하나요?

Codex, OpenCode, Cursor, Gemini CLI, GitHub Copilot CLI, Aider, OpenClaw, Factory Droid, Trae를 공식 지원합니다. 각 플랫폼에 맞는 설치 명령은 graphify install --platform [플랫폼명]으로 다릅니다.

Q. 민감한 내부 코드를 넣어도 안전한가요?

코드 파일은 tree-sitter로 로컬에서만 처리돼 외부 전송이 없습니다. 문서·이미지·영상은 플랫폼 API로 전송됩니다. 민감한 파일은 .graphifyignore로 제외하는 것을 권장합니다. 텔레메트리·사용 추적은 없습니다.

Q. 코드를 수정할 때마다 그래프를 다시 만들어야 하나요?

SHA256 캐시 덕분에 변경된 파일만 재처리합니다. --watch 옵션을 쓰면 파일 저장 시 코드는 즉시, 문서는 알림 후 재처리합니다. graphify hook install로 git post-commit 훅을 달면 커밋·브랜치 전환 시 자동으로 그래프를 갱신합니다.

Q. Codex에서는 /graphify 대신 무엇을 입력하나요?

Codex는 슬래시(/) 대신 달러($)를 스킬 호출 기호로 사용합니다. $graphify .로 입력하면 됩니다. 병렬 추출을 위해 ~/.codex/config.toml의 [features] 섹션에 multi_agent = true를 추가하는 것도 권장합니다.

Q. 유튜브 영상을 추가할 때 인터넷이 필요한가요?

yt-dlp가 유튜브에서 오디오를 내려받는 단계에만 인터넷이 필요합니다. 이후 faster-whisper 전사와 그래프 추출은 로컬에서 진행됩니다. 이미 다운로드된 영상 파일(.mp4, .mp3 등)은 폴더에 넣기만 하면 인터넷 없이 처리됩니다.

Q. graph.json을 LLM에 직접 붙여넣어도 되나요?

대규모 코퍼스의 graph.json은 컨텍스트 창을 초과할 수 있습니다. 권장 방식은 먼저 GRAPH_REPORT.md로 전체 구조를 파악한 뒤, /graphify query로 필요한 서브그래프만 뽑아 LLM에 제공하는 것입니다. MCP 서버를 띄우면 구조화된 툴 콜로 더 효율적으로 질의할 수 있습니다.

Q. INFERRED 엣지의 신뢰도 점수는 어떻게 해석하나요?

0.0~1.0 사이의 값으로, 1.0에 가까울수록 모델이 추론에 높은 확신을 가졌다는 의미입니다. EXTRACTED 엣지는 항상 1.0입니다. AMBIGUOUS로 태그된 엣지는 사람이 직접 검토해 확인하거나 제거하는 것을 권장합니다. 신뢰도 점수는 graph.json 각 엣지의 confidence_score 필드에서 확인할 수 있습니다.

 

 

graphify는 코드·PDF·유튜브를 하나의 지식 그래프로 연결해, AI 어시스턴트가 raw 파일을 뒤지는 대신 구조를 탐색하게 만드는 실용적인 도구입니다. 52개 파일 기준 71.5배 토큰 절감이라는 수치는 대규모 코드베이스에서 더욱 빛을 발합니다. pip install graphifyy && graphify install 두 줄로 오늘 바로 시작해 보세요.

💬 어떤 코드베이스나 자료에 graphify를 써보셨나요? 토큰 절감 효과나 구조 파악에 도움이 됐는지 댓글로 경험을 공유해 주세요.
🔖 나중에 설치해 보실 분은 이 글을 북마크해 두시면 편리합니다.
📤 같은 고민을 하는 개발자 동료에게 이 글을 공유해 주세요.

📚 다음에 읽으면 좋은 글

• Obsidian Mind vault 템플릿으로 지식 관리 시스템 구축하기
• vLLM vs Ollama vs SGLang — 로컬 LLM 서빙 엔진 완전 비교

ℹ️ 이 블로그는 Google 애드센스를 통해 광고 수익을 얻을 수 있습니다. 자세한 내용은 개인정보처리방침을 참고하세요.

※ 이 글은 2026-04-11 기준으로 작성되었습니다. 최신 정보는 공식 사이트에서 확인하세요.