코드베이스를 질의 가능한 지식 그래프로: Graphify-Labs/graphify v0.9.92의 tree-sitter 파이프라인·EXTRACTED/INFERRED 엣지·에이전트 훅 심층 해부

코딩 에이전트가 낯선 저장소에 들어가면 제일 먼저 하는 일은 대개 같다. grep으로 이름을 찾고, 파일을 하나씩 열고, 같은 파일을 세션마다 다시 읽는다. 컨텍스트 창은 그 사이에 원문 코드로 채워진다. Graphify-Labs/graphify는 이 순서를 뒤집자는 프로젝트다. 먼저 저장소 전체를 지식 그래프(노드=클래스·함수·모듈·문서 개념, 엣지=호출·임포트·상속·참조)로 한 번 만들어 두고, 에이전트는 원문 대신 그 그래프에 query·path·explain을 던진다. 코드 부분은 tree-sitter AST로 로컬에서 결정적으로 파싱하므로 API 키도 LLM 호출도 필요 없다. 오늘(2026-10-20) GitHub Trending Python 일간 8위(오늘 +751 stars)에 올랐고, 저장소를 만든 지 6개월 반 만에 12만 9천 스타를 넘겼다.

이 글은 “그래프로 바꿔 준다”는 홍보 문구를 실무자 관점에서 뜯어본다. ① 7단계 파이프라인과 모듈 경계, ② EXTRACTED/INFERRED/AMBIGUOUS 신뢰도 체계와 graph.json 스키마의 함정, ③ 코드가 어디까지 로컬에 머물고 무엇이 LLM으로 나가는지라는 데이터 경계, ④ Claude Code 훅·지시 파일·MCP 서버라는 세 가지 통합 방식, ⑤ 자체 벤치마크를 어떻게 읽어야 하는지. 그리고 박스(리눅스 VM, 8 vCPU)에서 PyPI 공식 패키지 graphifyy 0.9.92를 격리된 HOME에 설치해 FastAPI 저장소를 API 키 없이 그래프로 만들고, 질의·MCP·훅 동작까지 직접 재 봤다. 모든 수치는 2026-10-20 11:50~11:56 KST 실측이거나 저장소·PyPI·GitHub API에서 확인한 값이다.

한눈에 보기: 오늘 기준 스냅숏

왜 지금 트렌딩인가: 하루 한 번 꼴의 릴리스

Graphify는 “에이전트 토큰 비용”이라는 이번 가을 개발자 커뮤니티의 공통 화두 한가운데에 있다. 같은 날 Trending에 컨텍스트 압축(headroom), 장기 기억(ai-memory), 에이전트 하네스(ruflo)가 함께 올라와 있는데, Graphify는 그중 “읽기 자체를 줄이는” 쪽이다. 저장소 활동도 매우 빠르다. 최근 8개 릴리스가 약 일주일에 몰려 있고, 0.9.92 한 번에 커뮤니티 PR 23건이 들어갔다.

저장소 구조: 라이브러리 + 호스트별 스킬 본문

ARCHITECTURE.md의 첫 문장이 구조를 요약한다. “graphify는 파이썬 라이브러리가 뒷받침하는 Claude Code 스킬이다. 스킬은 라이브러리를 조율하고, 라이브러리는 단독으로도 쓸 수 있다.” 실제 트리를 보면 그 말대로 파이썬 패키지와 에이전트별 스킬 마크다운이 한 패키지에 같이 들어 있다.

파이프라인: 7단계, 코드에는 LLM이 없다

핵심 흐름은 detect() → extract() → build() → cluster() → analyze → report.generate() → export.to_*()다. 단계 사이에는 평범한 파이썬 dict와 NetworkX 그래프만 오간다. 단, 추출기 일부는 “현재 스캔 루트”라는 모듈 수준 상태에 기대고 있어 완전한 무상태는 아니라고 문서가 스스로 밝힌다(0.9.92에서 이 공유 방식을 정리하는 수정이 들어갔다).

설계상 가장 중요한 선택은 “임베딩·벡터 스토어를 쓰지 않는다”는 점이다. 검색은 질문 키워드로 시작 노드를 잡고 BFS/DFS로 이웃을 훑는 그래프 순회다. 덕분에 결과가 결정적이고 “왜 이 노드가 나왔는지”를 엣지로 설명할 수 있지만, 이름이 전혀 다른 개념 간의 의미 유사도는 문서 의미 패스가 만들어 준 semantically_similar_to 엣지가 없으면 잡지 못한다. 코드만 있는 저장소에서는 순수한 구조 그래프라는 뜻이다.

그래프 스키마와 신뢰도: 무엇을 믿을 수 있나

graph.json은 NetworkX node-link 형식이며 graph.schema_version(현재 1)과 graph.graphify_version을 담는다. 함정이 하나 있다. 파일에는 "directed": false라고 적혀 있지만 모든 링크는 실제로 방향이 있고, source→target 순서가 곧 방향이다. 그래서 json_graph.node_link_graph()로 그냥 읽으면 무방향 그래프가 끝점 순서를 바꿔 방향 정보가 사라진다. 직접 파싱하는 도구를 만든다면 graphify.paths.load_node_link_graph()로 읽고 _src/_tgt 마커를 따라야 한다. CLI의 path가 기본으로 방향 탐색을 하고 JSON의 directed 플래그를 보지 않는 것도 같은 이유다.

데이터 경계: 무엇이 로컬에 남고 무엇이 나가나

헤드리스 graphify extract는 설정된 키를 보고 백엔드를 자동 선택한다. 우선순위는 Gemini → Kimi → Claude → OpenAI → DeepSeek → Azure → Bedrock → Ollama이고, 자동 선택 시 어떤 환경 변수 때문에 그 제공자가 골라졌는지 출력한다. 셸에 여러 키가 깔려 있는 개발 머신이라면 “의도하지 않은 제공자로 문서가 나가는” 상황이 생길 수 있으니 GRAPHIFY_BACKEND로 명시하는 습관을 권한다. README는 Kimi(MOONSHOT_API_KEY)가 중국 Moonshot AI 서버로 간다는 점도 따로 경고한다. 데이터 거주성 요구가 있으면 GRAPHIFY_BACKEND=ollama, 아예 막으려면 GRAPHIFY_BACKEND=none이다.

에이전트에 붙이는 세 가지 방식

Graphify의 실질적인 가치는 그래프 생성보다 “에이전트가 실제로 그래프를 먼저 보게 만드는” 쪽에 있다. 방법은 플랫폼마다 다르다.

훅 쪽 구현은 꽤 신중하다. hook-guard는 표준 입력으로 도구 호출 JSON을 받아, 프로젝트 안에 신선한 그래프가 있을 때만 additionalContext로 “먼저 graphify query를 돌려라”라는 안내를 넣는다. 모든 예외는 fail-open(아무것도 출력하지 않고 통과)이고, 프로젝트 밖 파일 읽기는 무시하며, 그래프가 해당 파일보다 오래됐으면 “읽어도 된다”는 부드러운 안내로 낮춘다. 옵트인 --strict 모드에서만 세션당 첫 번째 원문 읽기를 permissionDecision: deny로 한 번 막는데, 최근 30분(GRAPHIFY_HOOK_STRICT_TTL, 기본 1800초) 안에 query·explain·path를 이미 돌렸다면 막지 않는다. 반대로 말하면 지시 파일 방식의 플랫폼에서는 “그래프를 먼저 보라”가 모델의 재량에 달려 있다.

설치와 기본 사용

# 설치 (uv 권장, PyPI 이름은 y 두 개)
uv tool install "graphifyy==0.9.92"        # 또는 pipx install graphifyy
graphify install                           # 감지된 어시스턴트에 스킬 등록 (--project 로 저장소 범위)

# 에이전트 안에서
/graphify .                                # 그래프 생성: graph.json, graph.html, GRAPH_REPORT.md

# 에이전트 없이(CI·스크립트) 코드만, 키 없이
GRAPHIFY_BACKEND=none graphify extract . --code-only
graphify cluster-only . --no-label         # 리포트·HTML 생성(LLM 라벨링 생략)

# 질의
graphify query "what connects auth to the database?" --budget 2000
graphify path "applications.py::FastAPI" "ModelField"
graphify explain "APIRouter"
graphify affected "solve_dependencies()" --depth 2
graphify god-nodes --top 10

# 유지
graphify update .                          # 코드 변경분 재추출(LLM 없음)
graphify hook install                      # post-commit/checkout/merge/rewrite 자동 재빌드

박스 스모크: FastAPI를 키 없이 그래프로

박스에서 다음 조건으로 실제로 돌렸다. 결과는 이 환경 한 번의 측정이며, 다른 하드웨어·저장소에서는 달라진다.

수치 외에 실무에 바로 의미 있는 관찰이 몇 가지 있었다.

벤치마크 주장은 어떻게 읽어야 하나

README 상단은 “LOCOMO recall@10 0.497, LLM 크레딧 0”을 내세운다. BENCHMARKS.md(마지막 갱신 2026-07-05)를 보면 측정 방식이 비교적 투명하게 적혀 있다. 모든 시스템을 같은 하네스·같은 모델(Kimi K2.6)·같은 예산으로 돌렸고, 채점 판정은 두 번째 판정자와 90.6% 일치(Cohen’s kappa 0.81)했다고 한다. 다만 실무자라면 아래 맥락을 함께 봐야 한다.

비슷한 도구와의 비교

포지션을 한 줄로 말하면, Graphify는 “LSP만큼 정밀하진 않지만 grep보다 훨씬 구조적이고, GraphRAG와 달리 코드 색인에 돈이 들지 않는” 지점에 있다. 호출 해석이 2차 패스의 휴리스틱(INFERRED)이라 동적 디스패치·리플렉션·메타프로그래밍이 많은 코드에서는 엣지가 빠지거나 틀릴 수 있다. CHANGELOG의 수정 항목 대부분이 바로 이 호출 해석·ID 충돌 문제라는 점이 현재 성숙도를 보여 준다.

보안·라이선스·운영 리스크

도입 체크리스트

정리

Graphify는 “에이전트가 grep하고 파일을 다시 읽는 비용”을 한 번 만든 구조 그래프로 대체하자는 도구다. 코드 부분은 tree-sitter로 로컬에서 결정적으로 처리되고, 모든 엣지에 EXTRACTED/INFERRED 근거가 붙으며, Claude Code에서는 PreToolUse 훅으로 에이전트의 탐색 순서 자체를 바꾼다. 박스에서 FastAPI 패키지(52파일)는 API 키 없이 2.1초 만에 노드 980·엣지 2,585 그래프가 됐고, 저장소 전체(1,176파일)도 11.8초면 끝났으며, 네트워크를 끊어도 같은 결과가 나왔다. 반면 이름이 겹치면 path가 추측 대신 거부하고, update와 extract --code-only의 결과 범위가 다르며, 벤치마크는 대부분 자체 하네스 수치라는 점도 확인했다. 지금 시점의 현실적인 사용법은 코드 전용·버전 고정으로 시작해, 우리 저장소에서 에이전트 턴과 토큰이 실제로 줄어드는지 직접 재 본 뒤 문서 패스와 strict 훅으로 넓혀 가는 것이다.