그래피파이(graphify) 실전: 어떤 코드 저장소든 검색 가능한 지식 그래프로 바꾸기

중급 난이도 | 약 20분 | graphify로 임의의 코드 저장소를 검색 가능한 지식 그래프로 변환하는 전체 과정을 익히게 됩니다. 무작정 grep에서 벗어나, 71.5x 토큰 압축을 달성하는 구조화된 코드 이해를 경험하세요.

프로젝트 소개

graphify는 AI 코딩 어시스턴트 스킬(skill)로, Safi Shamsi가 개발했습니다. GitHub 주소는 safishamsi/graphify입니다. 핵심 포지션은 아주 단순합니다. 어떤 폴더든(코드, 노트, 논문, 이미지, 심지어 비디오까지) 압축해 검색 가능한 하나의 지식 그래프로 만들고, AI 어시스턴트와의 매 대화가 구조화된 지식 기반으로 이루어지게 하여 맹목적인 전체 텍스트 매칭을 없애는 것.

특징은 세 가지로 요약됩니다.

멀티모달 입력: 코드(20개 언어), 문서, 이미지, PDF, 음성/영상 등 모두 지원하며, 동일한 그래프로 통합
임베딩 없이 클러스터링: Leiden 커뮤니티 탐지 알고리즘으로 그래프 토폴로지(엣지 구조)만 기반으로 클러스터링합니다. 벡터 데이터베이스가 필요 없고, 임베딩 모델을 따로 돌릴 필요도 없습니다.
정직한 신뢰도(confidence): 각 관계 엣지에 EXTRACTED / INFERRED / AMBIGUOUS를 표기합니다. 어떤 것은 찾아낸 것(extracted)이고, 어떤 것은 추론한 것(inferred)인지 알 수 있습니다.

graphify는 Claude Code, OpenClaw, Codex, Cursor, Trae 등 주요 AI 코딩 어시스턴트의 /graphify 명령으로 사용할 수도 있고, MCP Server 또는 CLI를 통해 독립적으로 호출할 수도 있습니다.

대상 독자

최소 하나 이상의 중형 프로젝트(천 줄 이상)를 작성해 보았고, 일상적으로 Claude Code / OpenClaw / Codex 또는 다른 AI 코딩 어시스턴트를 사용합니다. 새로운 코드 저장소를 마주하면 소스코드를 직접 읽도록 시키는 편인데, 파일 수가 늘면서 토큰이 빠르게 소모되고 컨텍스트가 조각나는 문제가 점점 더 뚜렷해집니다. 이 글은 바로 그 문제를 해결하기 위해 작성되었습니다.

핵심 의존성과 환경

의존성	최소 버전	설명
Python	3.10+	graphify의 핵심 언어
AI 코딩 어시스턴트	임의	Claude Code / OpenClaw / Codex / Cursor 등
Git	임의	git hooks 기능이 필요
pip	최신	PyPI 패키지 `graphifyy` 설치에 사용

TIP

graphify의 PyPI 패키지 이름은 graphifyy입니다(여기에 y가 하나 더 붙습니다). CLI 명령은 여전히 graphify입니다. 헷갈려서 다른 걸 설치하지 마세요. graphify* 접두사가 붙은 다른 패키지들은 이 프로젝트와 무관합니다.

전체 프로젝트 구조

my-project/
├── graphify-out/
│   ├── graph.json          # 영속화된 지식 그래프(세션 간 조회 가능)
│   ├── GRAPH_REPORT.md     # 구조화 분석 리포트(god nodes, 예상치 못한 연결, 제안 질문)
│   ├── graph.html          # 인터랙티브 그래프(vis.js, 브라우저로 바로 열기)
│   ├── cache/              # SHA256 캐시 디렉터리
│   └── transcripts/        # 음성/영상 전사 캐시( video 의존성이 설치된 경우에만 생성)
├── .graphifyignore         # 제외 규칙(문법은 .gitignore와 동일)
└── .graphify/hooks/            # graphify hook install 후 자동 생성

단계별 진행

1단계 — graphify 설치

graphify는 두 단계로 나뉩니다. 먼저 Python 패키지를 설치하고, 다음으로 AI 코딩 어시스턴트에 대한 플랫폼 적응 계층을 설치합니다.

# 1단계: PyPI 패키지 설치
pip install graphifyy

# 2단계: 플랫폼용 적응 계층 설치
# Claude Code 기준:
graphify install

# 다른 플랫폼이면 아래처럼 해당 명령으로 변경:
# graphify install --platform codex
# graphify install --platform opencode
# graphify install --platform claw        # OpenClaw
# graphify install --platform aider
# graphify install --platform droid       # Factory Droid
# graphify install --platform trae
# graphify install --platform cursor
# graphify install --platform gemini

# Windows 사용자는 문제가 생기면 플랫폼을 명시적으로 지정하세요:
graphify install --platform windows

WARNING

graphify install은 설정 파일(예: Claude Code의 settings.json)에 기록해야 합니다. 현재 디렉터리 또는 사용자 디렉터리에 쓰기 권한이 있는지 확인하세요. Docker 컨테이너에서 실행한다면, 먼저 영속화(persist) 디렉터리를 마운트한 뒤 설치하세요.

설치가 끝나면, AI 코딩 어시스턴트가 /graphify 명령을 인식하게 됩니다.

2단계 — 최초 실행: 지식 그래프 생성

분석하고 싶은 코드 디렉터리 아무 곳이나 들어가서 실행합니다.

# 현재 디렉터리 분석
/graphify .

# 지정 디렉터리 분석
/graphify ./src

# 지정 디렉터리 분석 + 더 공격적인 추론 모드 활성화
/graphify ./src --mode deep

# HTML 시각화는 건너뛰고 보고서와 JSON만 생성(더 빠름)
/graphify ./src --no-viz

graphify는 다음 세 단계로 처리합니다.

AST 추출(LLM 없음) — tree-sitter로 코드 파일을 파싱하고, 클래스/함수/가져오기(import) 관계/콜 그래프/cdocstring과 설명 주석을 추출합니다.
의미 추출(LLM 호출) — 문서, 논문, 이미지 등 콘텐츠에 대해 Claude를 호출해 개념/관계/설계 동기를 추출합니다.
그래프 구성과 클러스터링 — 모든 추출 결과를 합치고, Leiden 커뮤니티 발견 알고리즘(엣지 밀도 기반, embeddings 불필요)으로 클러스터링합니다.

실행이 끝나면 graphify-out/ 디렉터리에 다음 세 가지 산출물이 생성됩니다.

ls graphify-out/
# graph.json  GRAPH_REPORT.md  graph.html  cache/

3단계 — 세 산출물의 사용법 이해

graphify-out/graph.json — 영속화된 그래프 본체

이것이 전체 시스템의 핵심입니다. 포맷은 표준 NetworkX JSON 내보내기입니다.

{
  "nodes": [
    {
      "id": "DigestAuth",
      "label": "DigestAuth",
      "source_file": "src/auth.py",
      "source_location": "L42",
      "community": "auth"
    }
  ],
  "edges": [
    {
      "source": "DigestAuth",
      "target": "Response",
      "relation": "imports",
      "confidence": "EXTRACTED",
      "confidence_score": 1.0
    },
    {
      "source": "Attention",
      "target": "Adam",
      "relation": "semantically_similar_to",
      "confidence": "INFERRED",
      "confidence_score": 0.87
    }
  ]
}

모든 엣지는 confidence 라벨을 갖습니다.

EXTRACTED: 소스 코드에 그대로 존재하는 관계(신뢰도 1.0)
INFERRED: 합리적인 추론( confidence_score 포함, 0.0~1.0)
AMBIGUOUS: 불확실한 관계로, 리포트에 표시되어 사람이 검토할 수 있게 합니다.

graphify-out/GRAPH_REPORT.md — 구조화 분석 보고서

이 문서는 AI 어시스턴트를 위한 요약입니다. 아래 내용을 포함합니다.

God Nodes: 차수가 가장 높은 핵심 개념(다른 모든 노드가 결국 여기를 통과)
Surprising Connections: 파일/타입 간의 연결로서 예상 밖인 연결. "왜"에 대한 설명이 함께 제공
Suggested Questions: 그래프가 독특하게 답할 수 있는 4~5개의 질문
Design Rationale: docstring과 주석(# NOTE:, # WHY:, # HACK:)에서 추출한 설계 동기

graphify-out/graph.html — 인터랙티브 그래프

브라우저로 직접 열어 사용합니다. 노드를 클릭하고 검색하며, 커뮤니티별 필터링도 지원합니다. 사람이 코드 구조를 탐색하기에 적합합니다.

4단계 — 그래프 조회: 세 가지 명령

그래프가 있다고 끝이 아닙니다. 조회할 수 있어야 합니다. graphify에는 세 가지 쿼리 명령이 내장되어 있습니다.

query — 의미(semantic) 쿼리

# 가장 자주 사용: 그래프에서 질문과 관련된 노드와 경로 찾기
graphify query "what connects Attention to the optimizer?"

# 토큰 예산 제한
graphify query "show the auth flow" --budget 1500

# DFS로 특정 경로를 추적(무작위 샘플링이 아님)
graphify query "what connects DigestAuth to Response?" --dfs

# 기본 그래프가 아닌 다른 경로의 그래프 지정
graphify query "..." --graph path/to/another-graph.json

출력에는 노드 라벨, 엣지 타입, 신뢰도, 소스 파일과 소스 위치가 포함됩니다. 이 출력 내용을 그대로 AI 어시스턴트에 붙여 넣어 질문에 답하게 할 수 있습니다.

Use this graph query output to answer the question. Prefer the graph
structure over guessing, and cite the source files when possible.

path — 두 노드 사이의 경로 찾기

# 노드 A에서 노드 B까지의 전체 경로 추적
graphify path "DigestAuth" "Response"

explain — 단일 노드의 문맥(컨텍스트) 설명

# 노드의 이웃, 커뮤니티, 관련 엣지를 표시
graphify explain "SwinTransformer"

TIP

AI 코딩 어시스턴트가 MCP(Model Context Protocol)를 지원한다면 CLI를 건너뛰고, MCP로 그래프에 직접 접근하게 할 수 있습니다. 8단계를 참고하세요.

5단계 — Always-On Hook 통합(권장 설정)

매번 /graphify를 수동으로 치는 건 조금 번거롭습니다. graphify는 그래프 지식을 AI 어시스턴트의 대화 컨텍스트에 자동으로 주입해, 매번 질문할 때 파일을 맹목적으로 찾기(search)보다 그래프를 우선적으로 보게 해줍니다.

Claude Code

graphify claude install

두 가지를 수행합니다. CLAUDE.md에 규칙을 작성(Claude가 GRAPH_REPORT.md를 읽도록)하고, settings.json에 PreToolUse hook을 설치하여 매번 Glob 및 Grep 호출 전에 그래프 프롬프트를 주입합니다.

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

OpenClaw / Aider / Trae 등

이 플랫폼들은 tool hook을 지원하지 않으므로 AGENTS.md를 사용합니다.

graphify claw install   # OpenClaw
graphify aider install  # Aider
graphify trae install   # Trae

Cursor

graphify cursor install

.cursor/rules/graphify.mdc에 작성하고 alwaysApply: true로 설정하면, Cursor가 대화마다 자동으로 로드합니다.

제거(uninstall)는 해당 uninstall 명령으로 수행합니다.

graphify claude uninstall
graphify cursor uninstall
# ...

6단계 — 증분 업데이트: 매번 전체 재구축하지 않기

코드 저장소는 매일 변합니다. 전체 재구축(full rebuild)은 너무 느립니다. graphify에는 두 가지 증분 메커니즘이 있습니다.

--update: SHA256 캐시 기반 증분 추출

# 변경된 파일만 처리하고, 기존 그래프에 병합
/graphify ./src --update

cache 디렉터리에는 파일 내용 해시를 기준으로 이전 처리 결과가 기록됩니다. graphify는 파일 해시를 비교하여, 변경된 파일만 다시 AST 및 LLM 추출 절차를 수행합니다.

--watch: 파일 변경을 자동 감시

# 백그라운드 실행. 코드 파일 저장 시 즉시 AST 재구성
/graphify ./src --watch

# 문서/이미지 변경 후에는 --update를 수동으로 실행하라는 알림이 표시됩니다

코드 변경이 트리거하는 --watch 재구축은 순수 AST 작업이라 매우 빠르며 LLM 호출이 필요 없습니다. 반면 문서와 이미지가 변경되면 LLM로 재추출해야 하므로, watch는 --update를 한 번 수동 실행하라고 안내합니다.

7단계 — git Hooks: 매 Commit마다 자동으로 그래프 재구축

수동으로 돌리고 싶지 않고, 백그라운드 프로세스도 켜기 싫다면 그래프 재구축을 git에 맡기면 됩니다.

graphify hook install

.git/hooks/에 post-commit과 post-checkout 두 개의 훅을 기록합니다. 커밋하거나 브랜치를 전환할 때마다 git이 자동으로 그래프 재구축을 트리거합니다. 재구축이 실패하면(AST 파싱 오류, LLM 타임아웃 등) 훅이 0이 아닌 종료 코드를 내면서 git 동작을 중단해, 조용한(silent) 실패를 방지합니다.

상태 확인 및 제거:

graphify hook status
graphify hook uninstall

8단계 — 고급 사용법

MCP Server: AI가 그래프에 네이티브로 접근

AI 어시스턴트가 MCP 프로토콜을 지원한다면, 그래프를 MCP 도구로 노출할 수 있습니다.

python -m graphify.serve graphify-out/graph.json

출력은 MCP stdio 설정 문자열입니다. 이를 AI 어시스턴트의 MCP 구성에 붙여넣기만 하면 됩니다. 노출되는 도구는 다음과 같습니다.

query_graph: 의미 기반 서브그래프 쿼리
get_node: 노드 상세 정보 가져오기
get_neighbors: 이웃 노드 가져오기
shortest_path: 두 노드 사이의 최단 경로 찾기

Neo4j 내보내기

더 전문적인 그래프 분석을 위해 그래프를 Neo4j로 가져오고 싶나요?

# Neo4j로 수동 임포트할 Cypher 스크립트 생성
/graphify ./src --neo4j

# 또는 실행 중인 Neo4j 인스턴스로 직접 푸시
/graphify ./src --neo4j-push bolt://localhost:7687

에이전트가 읽을 수 있는 Wiki 생성

# Markdown 위키로 내보내기. AI Agent가 파일을 읽어 지식 저장소를 탐색할 수 있음
/graphify ./src --wiki

graphify-out/wiki/index.md(입구) + 각 커뮤니티와 god node에 해당하는 하나의 Markdown 문서가 생성됩니다.

지원되는 파일 유형 일람

유형	확장자	추출 방식
코드	`.py .ts .js .go .rs .java .c .cpp .rb .cs .kt .scala .php .swift .lua .zig .ps1 .ex .m .jl`	tree-sitter AST
문서	`.md .txt .rst`	Claude 의미 추출
이미지	`.png .jpg .webp`	Claude Vision
PDF	`.pdf`	Claude 추출( `pip install graphifyy[pdf]` 필요)
음성/영상	`.mp4 .mp3 .wav`	로컬 Whisper 전사( `pip install graphifyy[video]` 필요)
비디오 URL	YouTube 등	yt-dlp로 오디오 다운로드 → Whisper 전사

다른 LLM 제공자 지정

graphify는 기본적으로 플랫폼에 내장된 모델을 사용합니다(Claude Code는 Anthropic, Codex는 OpenAI). 다른 모델을 강제로 사용하고 싶다면 환경 변수를 통해 지정할 수 있습니다(해당 skill.md 파일 참고).

자주 묻는 문제(FAQ) 해결

1. 설치 후 graphify 명령을 찾을 수 없음

보통 Python 환경 또는 PATH 문제입니다.

# 패키지 설치 위치 확인
pip show graphifyy

# python -m으로 호출( PATH에 의존하지 않음 )
python -m graphify --help

# 또는 pipx로 격리 설치(권장)
pip install pipx && pipx install graphifyy

2. 그래프 노드가 매우 적거나 거의 비어 있음

.graphifyignore가 목표 파일을 잘못 제외하고 있는지 확인하세요.

# graphify가 실제로 어떤 파일을 스캔했는지 확인
/graphify ./src --no-viz  # --no-viz를 추가하면 AST만 수행하고 LLM은 호출하지 않아 빠릅니다

# .graphifyignore 문법 확인(.gitignore와 동일)
cat .graphifyignore

또한 파일 유형이 지원 목록에 없을 가능성도 있습니다. 위의 「지원되는 파일 유형」 표에서 코드 파일의 확장자가 포함되어 있는지 확인하세요.

3. LLM 추출 단계에서 타임아웃이 나거나 API 오류

네트워크 문제이거나 API Key 설정 문제일 수 있습니다.

# API Key가 존재하는지 확인(Claude Code 사용자는 보통 자동 구성됨)
# 다른 플랫폼 사용자는 해당 플랫폼의 API Key 환경 변수 확인

# --budget으로 토큰을 제한해 한 번의 요청이 너무 커지는 것을 방지
/graphify ./src --budget 2000

# 타임아웃 후 강제로 건너뛰고 나머지 파일을 계속 처리(전체 실행을 막지 않음)

4. cache 때문에 증분 업데이트 후 그래프가 일관되지 않음

SHA256 캐시가 손상되었거나 파일이 외부에서 변경된 경우입니다.

# cache를 지워 전체 재구축 강제
rm -rf graphify-out/cache
/graphify ./src

# 또는 특정 파일의 cache만 삭제
rm graphify-out/cache/<해당 해시>.json
/graphify ./src --update

5. Claude Code PreToolUse Hook이 동작하지 않음

대개 settings.json의 경로 또는 형식 문제입니다.

# hooks가 제대로 기록되었는지 확인
cat ~/.claude/settings.json | grep graphify

# IDE가 형식을 바꿨다면, graphify hook 부분을 수동으로 다시 추가
# graphify skill.md의 PreToolUse hook 형식을 참고

6. --watch에서 watchdog가 없다고 나옴

watchdog은 선택 의존성입니다.

pip install graphifyy[watch]

확장 읽기 / 심화 방향

1. 커스텀 Extractor: 새 언어 지원 추가

코드 저장소에서 graphify가 아직 지원하지 않는 언어(예: Racket, Nim)를 사용한다면, extract.py에 새로운 extract_<lang> 함수를 추가할 수 있습니다. tree-sitter로 AST를 기반으로 구현하고, ARCHITECTURE.md의 「Adding a new language extractor」 섹션의 단계를 따르세요. 전체 프로세스는 명확합니다. 함수 작성 → 접미사 등록 → 의존성 추가 → 테스트 작성.

2. GraphRAG 파이프라인: 그래프 쿼리를 RAG에 연결

graphify의 핵심 가치는: 매번 원본 파일을 다시 읽을 필요가 없다는 점입니다. 토큰 소모가 O(n×파일 크기)에서 O(서브그래프 크기)로 줄어듭니다. RAG Pipeline과 결합할 때 권장되는 연결 방식은 다음과 같습니다.

import json

# 1. 먼저 GRAPH_REPORT.md로 상위 의도 판단
# 2. graphify query로 관련 서브그래프를 가져오기
# 3. 서브그래프를 컨텍스트로 LLM에 전달

with open("graphify-out/graph.json") as f:
    graph = json.load(f)

# graph["nodes"]와 graph["edges"]가 컨텍스트입니다

3. Penpax: graphify 저자의 단말(엣지) 측 디지털 트윈 비전

graphify의 장기 로드맵은 Penpax입니다. 회의 기록, 브라우저 히스토리, 파일, 이메일, 코드까지 모두 연결해 계속 업데이트되는 하나의 지식 그래프를 만드는 단말 측 디지털 트윈 프로젝트로, 클라우드를 쓰지 않고 데이터로 모델을 학습시키지도 않습니다.

4. 멀티모달 확장: 비디오 강의를 그래프로 변환

기술 강연, Conference 영상, 팟캐스트 오디오가 있다면 --video 의존성을 사용해 그것들도 지식 그래프에 포함할 수 있습니다.

pip install 'graphifyy[video]'
/graphify ./corpus --whisper-model medium

Whisper는 로컬에서 실행되므로 오디오가 머신 밖으로 나가지 않습니다. 전사 결과는 graphify-out/transcripts/에 캐시되며, 반복 실행 시에는 캐시를 그대로 읽어옵니다.

5. 그래프 협업: 팀이 지식 구조를 공유

graphify의 산출물(graph.json, GRAPH_REPORT.md)은 순수 텍스트라 git에 커밋할 수 있습니다. 팀원이 pull한 뒤 graphify hook install을 실행하면 동일한 그래프를 자동으로 재사용합니다. 즉, 아키텍처 지식은 버전 관리가 가능하고, 코드 리뷰 시 그래프 노드를 인용할 수 있으며, PR 설명에도 god nodes를 직접引用할 수 있습니다. 그 결과 팀의 지식 이해는 더 이상 "누가 누구에게 물어봐야 하는지"에 의존하지 않게 됩니다.