Graphify 완전 분석: AI 코딩 어시스턴트를 위한 지식 그래프 엔진

GitHub: https://github.com/safishamsi/graphify
PyPI: pip install graphifyy
현재 버전: v0.4.9 (2026.04.13)
라이선스: MIT
Stars: 24.9k / Forks: 2.7k

---

목차

1. 왜 이 도구가 필요한가 — 문제 정의
2. Graphify란 무엇인가
3. 내부 아키텍처 심층 분석
4. 기술 스택 분해
5. 설치 및 플랫폼별 통합
6. 출력물 완전 분석
7. 핵심 명령어 실전 가이드
8. 다른 도구와의 비교
9. 성능 벤치마크: 71.5x 토큰 절감
10. Always-on 훅 메커니즘 상세 분석
11. MCP 서버로 활용하기
12. 실무 활용 시나리오
13. 한계점과 주의사항
14. 결론

---

1. 왜 이 도구가 필요한가 — 문제 정의

AI 코딩 어시스턴트를 실무에서 쓰다 보면 반드시 맞닥뜨리는 벽이 있다. 프로젝트 규모가 커질수록 AI가 코드를 이해하는 방식이 점점 비효율적으로 변한다는 것이다.

기존 방식의 구조적 한계

문제 1: 매 질문마다 원본 파일을 다시 읽는다

일반적인 AI 코딩 어시스턴트는 질문이 들어올 때마다 Glob, Grep, 파일 읽기를 반복한다. 같은 아키텍처 질문을 5번 물어보면 같은 파일을 5번 읽는다. 컨텍스트 윈도우를 낭비하고, 토큰 비용이 선형으로 증가한다.

문제 2: "무엇"은 알아도 "왜"를 모른다

코드 파일 자체에는 구현 로직이 있지만, 그 코드가 왜 그렇게 설계되었는지는 README, 설계 문서, 주석, 심지어 화이트보드 사진에 흩어져 있다. 기존 코드 인덱서는 이 두 세계를 연결하지 못한다.

문제 3: 키워드 검색은 구조를 드러내지 못한다

"이 모듈이 인증 흐름과 어떻게 연결되는가?" 같은 질문은 단어 매칭으로 해결할 수 없다. 관계 구조가 명시적으로 모델링되어야 한다.

문제 4: 멀티모달 자료의 단절

코드, PDF 논문, 마크다운 문서, 아키텍처 다이어그램 이미지를 하나의 맥락에서 함께 이해하는 것은 기존 도구로 어렵다.

Andrej Karpathy의 /raw 폴더 문제

Graphify의 탄생 배경에는 Andrej Karpathy의 작업 방식이 있다. 그는 논문, 트윗 캡처, 아키텍처 스크린샷, 개인 메모를 /raw 폴더에 무작위로 쌓아두고 필요할 때 AI 컨텍스트에 통째로 밀어 넣는 방식을 사용했다. 직관적이지만 치명적인 문제가 있다 — 파일이 늘수록 토큰 비용이 기하급수적으로 증가하고, 파일들 사이의 관계는 AI가 매번 새로 추론해야 한다.

Graphify는 이 워크플로우의 편리함은 유지하면서 관계를 한 번 추출해 재사용 가능한 구조로 만든다는 아이디어에서 출발했다.

---

2. Graphify란 무엇인가

Graphify는 코드, 문서, 이미지를 포함한 프로젝트 자산을 질의 가능한 지식 그래프(Knowledge Graph)로 변환하는 AI 코딩 어시스턴트용 스킬이다.

단순히 코드를 인덱싱하는 도구가 아니다. 다음 두 가지를 동시에 달성하려 한다:

1. 구조적 이해: 클래스, 함수, 모듈 간의 관계를 그래프로 표현
2. 의미론적 이해: 문서, 이미지, 주석에서 설계 의도(rationale)와 개념 관계를 추출

결과물은 graph.json이라는 영구 그래프 파일로 저장되며, 이후 질의는 원본 파일 대신 이 그래프를 사용한다.

핵심 포지셔닝

기존: 질문 → grep/glob → 원본 파일 반복 읽기 → 답변
Graphify: 질문 → graph.json 조회 (71.5x 적은 토큰) → 답변

AI에게 더 많은 파일을 보여주는 도구가 아니라, AI가 더 적은 비용으로 더 구조적으로 이해하게 만드는 도구다.

---

3. 내부 아키텍처 심층 분석

3단계 처리 파이프라인

README와 ARCHITECTURE.md를 기반으로 정리하면 Graphify는 다음 세 단계로 동작한다:

Pass 1: 결정론적 AST 추출 (LLM 없음)

코드 파일(.py, .ts, .go, .rs, .java ...)
    ↓
tree-sitter AST 파싱
    ↓
추출 항목:
  - 클래스 / 함수 정의
  - import 관계 (의존성 그래프)
  - call graph (함수 호출 관계)
  - docstring / 인라인 주석
  - # NOTE:, # WHY:, # HACK: 등 rationale 주석
    ↓
노드 + 엣지 (EXTRACTED, confidence=1.0)

핵심 포인트: 코드 분석에 LLM을 사용하지 않는다. tree-sitter 기반 파싱이므로 소스 코드는 외부로 전송되지 않는다. 23개 언어를 지원한다(Python, JS/TS, Go, Rust, Java, C/C++, Ruby, C#, Kotlin, Scala, PHP, Swift, Lua, Zig, PowerShell, Elixir, Objective-C, Julia, Vue, Svelte, Dart).

Pass 2: 비디오/오디오 로컬 전사 (선택적)

.mp4, .mov, .mp3, .wav, YouTube URL ...
    ↓
yt-dlp (오디오 추출) → faster-whisper (로컬 전사)
    ↓
domain-aware prompt (corpus god node 기반) 적용
    ↓
transcript 캐시 저장
    ↓
이후 Claude 추출 파이프라인으로 전달

graphify-out/transcripts/에 캐시되므로 재실행 시 재전사하지 않는다. 오디오는 로컬에서만 처리된다.

Pass 3: 병렬 LLM 서브에이전트 추출

문서(.md, .txt, .rst) + PDF + 이미지 + transcript
    ↓
Claude 서브에이전트 병렬 실행
    ↓
각 파일에서 추출:
  - 핵심 개념 노드
  - 노드 간 관계 + 관계 타입
  - 설계 근거(design rationale)
  - 의미론적 유사성 엣지 (semantically_similar_to)
    ↓
노드 + 엣지
  - EXTRACTED (직접 명시된 관계, confidence=1.0)
  - INFERRED (추론된 관계, confidence=0.0~1.0)
  - AMBIGUOUS (불확실한 관계, 검토 필요)

그래프 빌드 및 클러스터링

세 패스의 결과물이 NetworkX 그래프로 병합된다:

# 내부 동작 흐름 (개념적 표현)
G = nx.Graph()

# AST 추출 결과 병합
for node, edges in ast_results:
    G.add_node(node)
    G.add_edges_from(edges)

# LLM 추출 결과 병합
for node, edges in llm_results:
    G.add_node(node)
    G.add_edges_from(edges, confidence=edge.confidence)

# Leiden 커뮤니티 탐지 (graspologic 라이브러리)
communities = leiden_algorithm(G)

클러스터링의 핵심 설계 결정: 임베딩(Embedding)을 사용하지 않는다. 벡터 데이터베이스가 필요 없다. LLM이 추출한 semantically_similar_to 엣지가 이미 그래프에 포함되어 있으므로, 에지 밀도 기반의 Leiden 알고리즘만으로 의미론적 커뮤니티를 탐지할 수 있다.

관계 스키마

{
  "source": "DigestAuth",
  "target": "HTTPAdapter",
  "relation": "depends_on",
  "provenance": "EXTRACTED",
  "confidence_score": 1.0,
  "source_file": "auth.py",
  "source_line": 142
}

{
  "source": "attention_mechanism",
  "target": "optimizer_state",
  "relation": "semantically_similar_to",
  "provenance": "INFERRED",
  "confidence_score": 0.73,
  "source_file": "transformer_paper.pdf"
}

이 스키마 덕분에 "어디서 나온 관계인지", "LLM이 추론한 것인지 코드에서 직접 뽑은 것인지"를 항상 추적할 수 있다.

---

4. 기술 스택 분해

컴포넌트 기술 역할

코드 분석	tree-sitter	AST 파싱, 23개 언어 지원
그래프 구조	NetworkX	노드/엣지 관리, 경로 탐색
커뮤니티 탐지	Leiden (graspologic)	벡터 없는 토폴로지 기반 클러스터링
시각화	vis.js	인터랙티브 HTML 그래프
의미 추출	Claude / GPT-4	문서, 이미지 개념-관계 추출
오디오 전사	faster-whisper	로컬 전사, 외부 전송 없음
영상 처리	yt-dlp	오디오 추출
그래프 서버	Python MCP stdio	LLM 도구 호출용 서버
캐싱	SHA256	변경 파일만 재처리

의존성 그룹 (pyproject.toml 기반):

• 기본: networkx, tree-sitter, graspologic (Leiden)
• MCP: mcp 패키지 추가
• 비디오: faster-whisper, yt-dlp
• PDF: pypdf 또는 관련 파서
• 오피스: python-docx, openpyxl
• Neo4j: neo4j 드라이버

---

5. 설치 및 플랫폼별 통합

기본 설치

pip install graphifyy && graphify install

주의: PyPI 패키지명은 graphifyy (y 두 개)이지만 CLI 명령은 graphify다. pip install graphify는 무관한 다른 패키지를 설치한다.

플랫폼별 설치

# Claude Code (Linux/Mac/Windows — 자동 감지)
graphify install

# Windows 명시적 지정
graphify install --platform windows

# AI 코딩 어시스턴트별
graphify install --platform codex       # OpenAI Codex
graphify install --platform opencode    # OpenCode
graphify install --platform copilot     # GitHub Copilot CLI
graphify install --platform aider       # Aider
graphify install --platform claw        # OpenClaw
graphify install --platform droid       # Factory Droid
graphify install --platform trae        # Trae
graphify install --platform gemini      # Gemini CLI
graphify install --platform hermes      # Hermes

Cursor는 별도 명령:

graphify cursor install

Codex 추가 설정 — ~/.codex/config.toml에 병렬 처리 활성화:

[features]
multi_agent = true

optional dependency 설치

# 비디오/오디오 지원
pip install 'graphifyy[video]'

# 오피스 파일(.docx, .xlsx) 지원
pip install 'graphifyy[office]'

# MCP 서버 지원
pip install 'graphifyy[mcp]'

# Neo4j 직접 연동
pip install 'graphifyy[neo4j]'

# 전체 설치
pip install 'graphifyy[video,office,mcp,neo4j]'

WSL / Ubuntu 환경 주의사항

Ubuntu는 python3 명령을 사용하며 PEP 668 환경 충돌이 발생할 수 있다. 프로젝트 venv 사용을 권장한다:

python3 -m venv .venv && .venv/bin/pip install "graphifyy[mcp]"

.mcp.json에서 venv 경로를 명시해야 한다:

{
  "mcpServers": {
    "graphify": {
      "type": "stdio",
      "command": ".venv/bin/python3",
      "args": ["-m", "graphify.serve", "graphify-out/graph.json"]
    }
  }
}

---

6. 출력물 완전 분석

graphify-out/
├── graph.html       # 인터랙티브 시각화
├── GRAPH_REPORT.md  # AI가 읽는 구조 요약
├── graph.json       # 영구 그래프 데이터
├── cache/           # SHA256 기반 증분 캐시
└── transcripts/     # 오디오 전사 캐시 (video 옵션 시)

graph.html

vis.js 기반의 인터랙티브 그래프 뷰어다. 노드를 클릭하면 연결 관계를 확인할 수 있고, 커뮤니티 단위 필터링, 검색이 가능하다. 브라우저에서 바로 열 수 있는 단일 HTML 파일로 외부 의존성이 없다.

GRAPH_REPORT.md

AI 어시스턴트가 아키텍처 질문에 답하기 전 읽어야 할 "지도"다. 다음 내용이 포함된다:

## God Nodes (최고 연결도 개념)
- `AuthManager`: 42개 연결 (인증 흐름의 허브)
- `RequestDispatcher`: 38개 연결 (요청 라우팅 중심)

## Surprising Connections
- `CacheLayer` ↔ `AuthToken`: 코드-문서 교차 연결
  (why: 캐시 무효화 로직이 토큰 갱신과 의존 관계)

## Suggested Questions
1. AuthManager와 CacheLayer 사이의 경로는?
2. RequestDispatcher가 왜 이 구조를 채택했는가?
...

graph.json

노드, 엣지, 커뮤니티 정보를 포함한 전체 그래프 데이터. 직접 파싱하거나 graphify query 명령으로 서브그래프를 추출해서 사용한다.

cache/ (SHA256)

각 파일의 SHA256 해시를 기록한다. --update 실행 시 변경된 파일만 재처리하므로 대형 코드베이스에서 반복 실행 비용을 크게 낮춘다.

---

7. 핵심 명령어 실전 가이드

그래프 생성

# 현재 디렉터리 전체
/graphify .

# 특정 폴더
/graphify ./raw

# 더 공격적인 INFERRED 엣지 추출
/graphify ./raw --mode deep

# 변경 파일만 재처리 (증분 업데이트)
/graphify ./raw --update

# 방향 그래프 (source→target 방향 보존)
/graphify ./raw --directed

# 기존 graph.json에서 클러스터링만 재실행 (LLM 없음)
/graphify ./raw --cluster-only

# HTML 시각화 생략 (빠른 실행)
/graphify ./raw --no-viz

콘텐츠 추가

# arXiv 논문 추가 + 그래프 업데이트
/graphify add https://arxiv.org/abs/1706.03762

# 트윗 추가
/graphify add https://x.com/karpathy/status/...

# YouTube 영상 추가 (오디오 추출 → Whisper 전사)
/graphify add 

# 저자 태깅
/graphify add https://... --author "Andrej Karpathy"

질의 및 탐색

# 자연어 질의
/graphify query "인증 흐름은 어느 모듈과 연결되는가?"

# DFS로 특정 경로 추적
/graphify query "show the auth flow" --dfs

# 토큰 예산 제한 (비용 제어)
/graphify query "..." --budget 1500

# 두 노드 간 최단 경로
/graphify path "DigestAuth" "Response"

# 특정 노드 상세 설명
/graphify explain "SwinTransformer"

# 특정 graph.json 파일 지정
/graphify query "..." --graph path/to/graph.json

내보내기

# Obsidian vault 생성 (옵트인)
/graphify ./raw --obsidian
/graphify ./raw --obsidian --obsidian-dir ~/vaults/myproject

# SVG 내보내기
/graphify ./raw --svg

# GraphML (Gephi, yEd 호환)
/graphify ./raw --graphml

# Neo4j Cypher 파일 생성
/graphify ./raw --neo4j

# Neo4j 인스턴스에 직접 push
/graphify ./raw --neo4j-push bolt://localhost:7687

# 에이전트가 탐색할 수 있는 Wiki 생성
/graphify ./raw --wiki

# MCP 서버 시작
/graphify ./raw --mcp

# 파일 변경 감지 자동 동기화
/graphify ./raw --watch

Git 훅 통합

# post-commit, post-checkout 훅 설치
graphify hook install

# 상태 확인
graphify hook status

# 제거
graphify hook uninstall

파일 제외 설정 (.graphifyignore)

# .gitignore 문법과 동일
vendor/
node_modules/
dist/
build/
*.generated.py
**/__pycache__/

---

8. 다른 도구와의 비교

도구 방식 멀티모달 지식 그래프 코드 분석 설계 의도 추출

Graphify	그래프 토폴로지	✅ 코드+문서+이미지+영상	✅ 명시적	AST + LLM	✅ rationale 추출
Sourcegraph	키워드 검색	❌ 코드 중심	❌	코드 인덱싱	❌
Code2Vec	벡터 임베딩	❌	❌ 함수 임베딩	함수 단위	❌
CodeGraph	정적 분석	❌	부분적	AST	❌
Neo4j	범용 그래프 DB	❌ (직접 처리 불가)	✅ (수동 구성)	❌	❌
RAG 시스템	벡터 검색	일부	❌	청킹 기반	❌

Graphify의 차별화 포인트:

• 임베딩 없는 클러스터링: 벡터 DB 불필요. LLM이 추출한 의미론적 엣지가 그래프 구조 안에 내장되어 있어 Leiden 알고리즘만으로 커뮤니티를 탐지한다.
• 관계 출처 추적: EXTRACTED / INFERRED / AMBIGUOUS 레이블로 항상 추적 가능.
• 코드의 "왜"까지 추출: # WHY:, # NOTE:, # HACK: 주석을 rationale_for 노드로 추출한다.
• Hyperedge 지원: 페어(pair) 엣지로 표현 불가능한 3개 이상 노드 관계를 표현한다.

---

9. 성능 벤치마크: 71.5x 토큰 절감

Graphify README에서 제시하는 벤치마크 데이터:

코퍼스 파일 수 토큰 절감률 위치

Karpathy repos + 논문 5편 + 이미지 4개	52개	71.5x	worked/karpathy-repos/
graphify 소스 + Transformer 논문	4개	5.4x	worked/mixed-corpus/
httpx (합성 Python 라이브러리)	6개	~1x	worked/httpx/

해석 포인트:

• 파일 수가 적으면 그래프 이점이 거의 없다. 6개 파일은 컨텍스트 윈도우에 다 들어간다.
• 52개 파일(코드+논문+이미지)에서 71.5x 절감이 나온다.
• 절감이 쌓이는 방식: 첫 실행은 그래프 구축 비용이 든다. 이후 반복 질의부터 절감이 시작된다. SHA256 캐시로 변경 파일만 재처리하므로 질의가 쌓일수록 이점이 커진다.
• 이 수치는 레포지토리 제공 자료 기준이므로 모든 프로젝트에서 동일하게 재현되는 값으로 보기보다는 대형 혼합 코퍼스에서의 주장값으로 해석하는 것이 적절하다.

---

10. Always-on 훅 메커니즘 상세 분석

Graphify의 가장 강력한 기능 중 하나는 AI 어시스턴트가 파일을 직접 검색하기 전에 항상 그래프를 먼저 참조하도록 강제하는 메커니즘이다.

# 플랫폼별 always-on 설치
graphify claude install    # CLAUDE.md + PreToolUse hook
graphify codex install     # AGENTS.md + PreToolUse hook (.codex/hooks.json)
graphify opencode install  # AGENTS.md + tool.execute.before plugin
graphify cursor install    # .cursor/rules/graphify.mdc (alwaysApply: true)
graphify gemini install    # GEMINI.md + BeforeTool hook

Claude Code의 구현 방식

graphify claude install을 실행하면 두 가지가 설치된다:

1) CLAUDE.md 섹션 추가:

## graphify
Read `graphify-out/GRAPH_REPORT.md` before answering architecture questions.

2) settings.json PreToolUse hook:

Claude Code가 Glob 또는 Grep 도구를 호출하기 직전에 훅이 발동한다. 지식 그래프가 존재하면 Claude는 다음 메시지를 받는다:

graphify: Knowledge graph exists. Read GRAPH_REPORT.md for god nodes 
and community structure before searching raw files.

이로 인해 Claude는 파일 검색 대신 그래프 보고서를 먼저 읽고 구조를 파악한 뒤 필요한 부분만 깊게 들어간다.

플랫폼별 메커니즘 차이

플랫폼 메커니즘 방식

Claude Code	PreToolUse hook	Glob/Grep 호출 전 인터셉트
Codex	PreToolUse hook	Bash 도구 호출 전 인터셉트
OpenCode	tool.execute.before plugin	JS 플러그인으로 도구 출력 주입
Cursor	.cursor/rules/graphify.mdc	alwaysApply: true 규칙
Gemini CLI	BeforeTool hook	파일 읽기 도구 호출 전 인터셉트
Aider/OpenClaw/Trae	AGENTS.md	훅 없음, 규칙만

Always-on vs 명시적 트리거

Always-on (GRAPH_REPORT.md):
  → 전체 구조 파악, god node, community 요약
  → "지도"를 제공

/graphify query|path|explain:
  → graph.json 홉-바이-홉 탐색
  → 엣지 타입, 신뢰도 점수, 소스 위치까지 확인
  → "지도에서 정확한 경로 탐색"

---

11. MCP 서버로 활용하기

Graphify는 graph.json을 MCP(Model Context Protocol) 서버로 노출할 수 있다. AI 어시스턴트가 도구 호출로 그래프를 직접 탐색할 수 있게 된다.

# MCP 서버 시작
python -m graphify.serve graphify-out/graph.json

제공되는 MCP 도구:

• query_graph: 자연어 질의
• get_node: 특정 노드 상세 정보
• get_neighbors: 인접 노드 탐색
• shortest_path: 두 노드 간 최단 경로

.mcp.json 설정 예시:

{
  "mcpServers": {
    "graphify": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "graphify.serve", "graphify-out/graph.json"]
    }
  }
}

이 방식을 사용하면 텍스트 복붙 없이 AI가 구조화된 그래프 접근을 반복적으로 수행할 수 있다.

---

12. 실무 활용 시나리오

시나리오 1: 대형 레거시 코드베이스 온보딩

새 팀원이 복잡한 레거시 코드베이스를 파악해야 할 때:

# 1. 그래프 빌드 (최초 1회)
/graphify . --mode deep

# 2. always-on 설치
graphify claude install

# 3. 구조 탐색
/graphify query "핵심 인증 흐름을 설명해줘"
/graphify explain "PaymentProcessor"
/graphify path "UserController" "DatabaseAdapter"

GRAPH_REPORT.md의 god node 목록에서 시스템의 핵심 허브 컴포넌트를 빠르게 파악할 수 있다.

시나리오 2: 논문 + 코드 연구 저장소

ML 연구자가 논문과 구현 코드를 함께 관리할 때:

# 논문, 메모, 코드가 섞인 raw 폴더 처리
/graphify ./raw

# arXiv 논문 직접 추가
/graphify add https://arxiv.org/abs/1706.03762 --author "Vaswani et al."
/graphify add https://arxiv.org/abs/2010.11929 --author "Dosovitskiy et al."

# 개념 간 연결 탐색
/graphify query "attention mechanism과 optimizer 사이의 연결은?"
/graphify query "ViT와 Transformer의 공통 개념은?"

코드의 함수와 논문의 수식 개념이 semantically_similar_to 엣지로 연결된다.

시나리오 3: 아키텍처 리뷰 자동화

# 1. 그래프 빌드
/graphify . --directed  # 의존 방향 보존

# 2. 순환 의존성 의심 모듈 탐색
/graphify query "순환 의존 가능성이 있는 모듈은?"

# 3. god node 분석 (지나치게 연결된 모듈 = 설계 냄새)
# GRAPH_REPORT.md의 god node 섹션 확인

# 4. 특정 리팩터링 영향 범위 파악
/graphify query "AuthService를 변경할 때 영향받는 컴포넌트는?"

시나리오 4: CI/CD 통합

# Git 훅 설치 (post-commit, post-checkout)
graphify hook install

# 이후 모든 커밋 후 자동 그래프 재빌드
# 브랜치 전환 후 자동 그래프 재빌드

빌드 실패 시 훅이 non-zero exit으로 종료하므로 git이 오류를 표면화한다.

시나리오 5: 멀티모달 회의/강의 노트 통합

pip install 'graphifyy[video]'

# 회의 녹음 파일 + 슬라이드 + 문서 통합
/graphify ./meeting-corpus

# YouTube 강의 추가
/graphify add https://youtube.com/watch?v=...

# --whisper-model medium: 기술 용어 인식 정확도 향상
/graphify ./corpus --whisper-model medium

---

13. 한계점과 주의사항

기술적 한계

1) INFERRED 엣지는 검토가 필요하다

LLM이 추론한 관계는 그럴듯하지만 틀릴 수 있다. 특히 설계 의도(rationale)나 의미론적 유사성 판단은 과신하면 안 된다. confidence_score를 항상 확인하고, AMBIGUOUS 엣지는 반드시 사람이 검토해야 한다.

2) 클러스터링 품질은 추출 품질에 종속된다

Leiden 알고리즘이 아무리 좋아도, 초기 노드/엣지 추출이 부실하면 커뮤니티 탐지 결과도 의미 없다. 입력 파일의 문서화 수준이 결과에 직결된다.

3) 소규모 프로젝트에서는 이점이 작다

6개 파일 수준의 코드베이스는 그래프 구축 오버헤드 대비 이점이 거의 없다. 대형 프로젝트(30개 파일 이상, 문서+이미지 혼합)에서 가치가 커진다.

4) 언어 지원 현황을 항상 확인하라

README와 pyproject.toml 사이에 지원 언어 수가 다를 수 있다. 사용 전 현재 버전 기준으로 확인하는 것이 안전하다.

사용상 주의사항

API 비용 관리

문서/이미지/전사본에 대한 LLM 추출은 Claude 또는 GPT-4 API를 호출한다. 대형 코퍼스를 처음 처리할 때 API 비용이 발생한다. SHA256 캐시 덕분에 이후 재실행은 변경 파일에 대해서만 비용이 든다.

코드 파일은 외부 전송 없음

AST 추출은 tree-sitter 기반 로컬 처리다. 소스 코드 자체는 API로 전송되지 않는다. 다만 docstring, 주석 내용은 LLM으로 전달될 수 있으므로 민감한 주석 내용이 있는 경우 주의가 필요하다 (.graphifyignore로 제외 가능).

플랫폼별 기능 차이

OpenClaw, Aider는 병렬 에이전트 지원이 초기 단계이므로 순차 추출을 사용한다. Claude Code나 Codex 대비 추출 속도가 느릴 수 있다.

---

14. 결론

Graphify는 AI 코딩 어시스턴트와의 상호작용 패러다임을 "파일 반복 탐색"에서 "구조화된 그래프 탐색"으로 바꾸려는 시도다. 핵심 설계 철학을 세 가지로 요약하면:

1. 한 번 추출, 반복 재사용
첫 실행에서 그래프를 구축하면 이후 질의는 raw 파일 대신 압축된 그래프를 사용한다. 반복 질의가 많을수록 이점이 커진다.

2. 코드의 "무엇"과 문서의 "왜"를 연결
AST로 구조를 추출하고, LLM으로 설계 의도를 추출해서 하나의 그래프로 연결한다. AI가 코드의 동작뿐 아니라 배경 맥락까지 이해할 수 있게 된다.

3. 투명한 근거 추적
EXTRACTED / INFERRED / AMBIGUOUS 레이블과 confidence_score로 AI의 답변 근거를 항상 검증할 수 있다.

이 도구가 특히 가치 있는 상황:

• 대형 레거시 코드베이스 온보딩
• 논문 + 코드 + 메모가 섞인 연구 저장소
• 아키텍처 질문을 반복적으로 던지는 팀
• 설계 결정 배경을 문서화하고 추적하고 싶은 프로젝트

반대로 체감 이점이 작은 경우:

• 파일 수가 적은 소규모 프로젝트
• 단순 텍스트 검색만 필요한 경우
• 코드만 있고 설계 문서가 거의 없는 경우

GitHub 24.9k Stars는 이 도구가 해결하는 문제의 보편성을 증명한다. "AI에게 더 많은 파일을 보여주는 대신, AI가 더 적은 비용으로 더 잘 이해하게 만든다"는 방향은 앞으로 AI 개발 도구가 나아갈 중요한 흐름 중 하나다.

---

참고 자료

• GitHub: safishamsi/graphify
• Javaexpert Tistory: Graphify 카파시의 위키 구현 버전
• PyTorchKR: Graphify AI Knowledge Graph